Write Tag / Write Tag Bit：面向设备动作时，优先走明确写入链 | HQ VISU Designer

一个值写到一个 Tag，是 Write Tag 最典型的场景。启停命令、模式切换、设定值写入、确认动作，都适合它。正式项目里，这通常比纯脚本写值更可靠，因为它能带更多运行平台字段。

• 适合单值写入
• 适合权限、确认、原因输入接管
• 适合正式项目关键按钮

Tag Expression 填完整点名或模板变量点名；Value 填要写入的值；Enabled 控制当前是否允许写入；PermissionCode、RequireConfirm、ConfirmText、RequireReason、AuditAction 交由运行端处理权限、确认、原因和审计。

• Tag Expression：`'<PLC>.CMD_START'`
• Value：true、1、"AUTO" 或表达式
• Enabled：按钮当前是否可操作
• PermissionCode：运行端权限码
• RequireConfirm / ConfirmText：确认提示
• RequireReason：要求填写原因
• AuditAction：审计动作名称

Tag Expression: '<PLC>.CMD_START'
Value: true
Enabled: operatorReady === true
PermissionCode: 'io:write'
RequireConfirm: true
ConfirmText: '确认启动设备？'

Value 可以填写固定值、模板变量字符串、ReadTag 结果、页面变量或多行脚本返回值。写布尔命令时返回 true / false；写模式和状态码时返回整数；写设定值时返回数字；写文本时返回字符串。字段类型应与目标 Tag 类型一致。

• 布尔命令：true / false
• 模式码：1、2、3 或 ReadTagInteger(...) 的结果
• 设定值：12.5 或计算表达式
• 文本："AUTO" 或模板变量字符串
• 多行脚本：使用 return 返回最终值

// Value
return operatorReady ? 1 : 0;

Enabled 用于判断当前动作是否允许执行。条件不满足时，可以仅禁用操作，也可以配合 Hide when not enabled 隐藏入口。权限不足、设备未就绪、当前上下文未选择时，建议让 Enabled 返回 false，并在页面上提供清晰状态说明。

• Enabled 返回布尔值
• false 表示当前动作不可执行
• Hide when not enabled 可隐藏入口
• 禁用原因应通过状态文本或提示表达

当目标是修改整数 Tag 内的某一位，而不是整值本身时，优先使用 Write Tag Bit。它底层会先读当前整数值，再按位计算 Set / Reset / Toggle，然后再写回。

Tag Expression 填父整数 Tag，不追加 `[n]`；Bit Index 填 0 到 31；Bit Action 选择 Set、Reset 或 Toggle。需要确认和权限时，同样由运行端字段接管。

• Tag Expression：`'<PLC>.CMD_WORD'`
• Bit Index：0 到 31
• Bit Action：Set、Reset、Toggle
• UseForceMode：仅在项目规范明确要求时使用

Tag Expression: '<PLC>.CMD_WORD'
Bit Index: 3
Bit Action: Set

`Set` 将目标位写为 1；`Reset` 将目标位写为 0；`Toggle` 将目标位取反。运行端会先读取父级整数 Tag 当前值，再按 Bit Index 计算目标位，最后把新的整数值提交给宿主机。Bit Index 0 表示最低位。

• Set：目标位 = 1
• Reset：目标位 = 0
• Toggle：目标位取反
• Bit Index 0：最低位
• 目标 Tag：父级整数 Tag

读取位时使用 `TAG[bit]`，例如 `Device.STATUS[3]`；写入位时不应在 Tag Expression 中写 `[3]`。Write Tag Bit 的 Tag Expression 填 `Device.STATUS`，Bit Index 填 `3`。该规则可以避免运行端将位引用误当成完整写入目标。

• 读取位语法：`TAG[bit]`
• 读取位：`ReadTagBoolean("Device.STATUS[3]", false)`
• 写位目标：`Device.STATUS`
• 写位位号：`Bit Index = 3`
• 写位动作：`Set / Reset / Toggle`

// 正确：读取位
ReadTagBoolean("Device.STATUS[3]", false)

// 正确：写位字段
Tag Expression: "Device.STATUS"
Bit Index: 3
Bit Action: Toggle

Write Tag 和 Write Tag Bit 的 Tag 字段可以填写完整点名，也可以填写带模板变量的点名。包含模板变量时应写成字符串，例如 `'<PLC>.CMD_START'` 或 `'<PLC>.<RUN_TAG>'`。

Tag: '<PLC>.CMD_START'
Value: 1

最终是否成功由宿主机决定。宿主机可以做权限校验、确认框、原因输入、审计记录和异步写入。因此，界面发起写入动作，不等于设备端已经同步确认完成。

qtedit.writeTag({
  TagName: "Device.CMD",
  Value: 1,
  PermissionCode: "io:write",
  RequireConfirm: true,
  ConfirmText: "确认执行写值？"
});

只有在宿主和项目规范明确支持 FORCE 语义，且业务上确实需要强制写位时，再考虑打开它。否则不要把 FORCE 当成普通写值的默认选项。

PermissionCode 用于交给运行端判断当前用户是否具备操作权限；RequireConfirm 和 ConfirmText 用于关键操作前确认；RequireReason 用于需要记录原因的操作。页面侧负责提供字段，最终权限、确认、原因和审计逻辑由运行端执行。

关键写值应放在按钮点击、确认动作或明确操作触发的脚本中。页面加载、自动刷新、普通动画表达式和质量提示不应自动下发设备命令。这样可以让运行端权限、确认、原因输入和审计链路都有清晰触发来源。

• 适合：按钮点击、确认按钮、明确操作脚本
• 不适合：页面加载时自动写入
• 不适合：Move / Rotate / Scale / Script Color 等表达式位
• 关键写值应让用户能看到目标、值和确认信息