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

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

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

当前编辑器直接提供 Target Tag、Value、Condition、Setup Script 和三个外观选项。普通点名和模板点名直接按界面可读形式填写，保存时会自动规范为安全字符串表达式。

• Target Tag：`PLC1.PUMP.CMD_START` 或 `<PLC>.CMD_START`
• Value：true、1、"AUTO" 或表达式
• Condition：按钮当前是否允许操作
• Setup Script：准备 Value 使用的变量
• Options：手型光标、启用时粗边框、禁用时隐藏

Target Tag: <PLC>.CMD_START
Value: true
Condition: operatorReady === true

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

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

// Value
return operatorReady ? 1 : 0;

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

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

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

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

• Target Tag：`<PLC>.CMD_WORD`
• Bit Index：0 到 31
• Bit Action：Set、Reset、Toggle
• FORCE：当前不可用，旧设置会被忽略

Target Tag: <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]`；写入位时不应在 Target Tag 中写 `[3]`。Write Tag Bit 的 Target Tag 填 `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)

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

Write Tag 和 Write Tag Bit 的 Target Tag 可以填写完整点名，也可以填写带模板变量的点名。当前编辑器直接显示 `<PLC>.CMD_START` 或 `<PLC>.<RUN_TAG>`，无需手工补引号；保存时会自动规范为字符串表达式。

Target Tag: <PLC>.CMD_START
Value: 1

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

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

HQControl 会拒绝 FORCE 写入，因此当前 Write Tag Bit 编辑器不再提供 FORCE 勾选框。旧项目若残留 UseForceMode=true，重新保存该行为时会忽略旧设置并写回 false。

PermissionCode、RequireConfirm、ConfirmText、RequireReason、AuditAction 属于运行协议字段，当前 Write Tag 与 Write Tag Bit 编辑器不直接展示它们；编辑已有行为时会保留这些字段。最终权限、确认、原因和审计逻辑由运行端执行，不要把它们误写进 Target Tag、Value 或 Condition。

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

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