所属产品: Mingcedar Studio DESIGNER
Write Tag / Write Tag Bit：面向设备动作时，优先走明确写入链 | Mingcedar Studio
只要动作最终要落到 Tag，优先理解 Write Tag 和 Write Tag Bit，再判断是否需要脚本扩展。
<section id="write-tag" class="docs-block docs-block-intro docs-block-current"> <span class="section-kicker">写值</span> <h2>Write Tag / Write Tag Bit：面向设备动作时，优先走明确写入链</h2> <p>只要动作最终要落到 Tag，优先理解 Write Tag 和 Write Tag Bit，再判断是否需要脚本扩展。</p> <div class="docs-detail-list"> <article id="write-tag-item-1" class="docs-detail-row"> <strong>Write Tag 适合什么</strong> <p>一个值写到一个 Tag，是 Write Tag 最典型的场景。启停命令、模式切换、设定值写入、确认动作，都适合它。标准单值动作优先用 Write Tag，配置集中便于维护；需要多步校验时用 Click Script，WriteTag 系列同样支持写入选项。</p> <ul> <li>适合单值写入</li><li>适合权限、确认、原因输入接管</li><li>适合正式项目关键按钮</li> </ul> </article><article id="write-tag-item-2" class="docs-detail-row"> <strong>Write Tag 关键字段</strong> <p>当前编辑器直接提供 Target Tag、Value、Condition、Setup Script 和三个外观选项。普通点名和模板点名直接按界面可读形式填写，保存时会自动规范为安全字符串表达式。</p> <ul> <li>Target Tag：`PLC_LINE01.PUMP01.CMD_START` 或 `<PLC>.CMD_START`</li><li>Value：true、1、"AUTO" 或表达式</li><li>Condition：按钮当前是否允许操作</li><li>Setup Script：准备 Value 使用的变量</li><li>Options：手型光标、启用时粗边框、禁用时隐藏</li> </ul> <pre class="docs-code-block"><code>Target Tag: <PLC>.CMD_START
Value: true
Condition: operatorReady === true</code></pre> </article><article id="write-tag-item-3" class="docs-detail-row"> <strong>Value 字段支持哪些写法</strong> <p>Value 可以填写固定值、模板变量字符串、ReadTag 结果、页面变量或多行脚本返回值。写布尔命令时返回 true / false；写模式和状态码时返回整数；写设定值时返回数字；写文本时返回字符串。字段类型应与目标 Tag 类型一致。</p> <ul> <li>布尔命令：true / false</li><li>模式码：1、2、3 或 ReadTagInteger(...) 的结果</li><li>设定值：12.5 或计算表达式</li><li>文本："AUTO" 或模板变量字符串</li><li>多行脚本：使用 return 返回最终值</li> </ul> <pre class="docs-code-block"><code>// Value
return operatorReady ? 1 : 0;</code></pre> </article><article id="write-tag-item-4" class="docs-detail-row"> <strong>Condition 和 Hide when disabled</strong> <p>Condition 用于判断当前动作是否允许执行。条件不满足时，可以仅禁用操作，也可以配合 Hide when disabled 隐藏入口。设备未就绪或当前上下文未选择时，建议让 Condition 返回 false，并在页面上提供清晰状态说明。</p> <ul> <li>Condition 返回布尔值</li><li>false 表示当前动作不可执行</li><li>Hide when disabled 可隐藏入口</li><li>禁用原因应通过状态文本或提示表达</li> </ul> </article><article id="write-tag-item-5" class="docs-detail-row"> <strong>Write Tag Bit 适合什么</strong> <p>当目标是修改整数 Tag 内的某一位，而不是整值本身时，优先使用 Write Tag Bit。它底层会先读当前整数值，再按位计算 Set / Reset / Toggle，然后再写回。</p> </article><article id="write-tag-item-6" class="docs-detail-row"> <strong>Write Tag Bit 关键字段</strong> <p>Target Tag 填父整数 Tag，不追加 [n]；Bit Index 为 0 到 31，同时必须落在父 Tag 的实际类型位宽内（例如 16 位仅 0 到 15）；Bit Action 选择 Set、Reset 或 Toggle。此流程先读整值再写回，不等于 PLC 原子位指令；多个写入者并发修改同一状态字时，应在 PLC 或业务端协调。</p> <ul> <li>Target Tag：`<PLC>.CMD_WORD`</li><li>Bit Index：0 到 31，且小于父 Tag 实际位宽</li><li>Bit Action：Set、Reset、Toggle</li><li>FORCE：当前不可用，旧设置会被忽略</li> </ul> <pre class="docs-code-block"><code>Target Tag: <PLC>.CMD_WORD
Bit Index: 3
Bit Action: Set</code></pre> </article><article id="write-tag-item-7" class="docs-detail-row"> <strong>Set / Reset / Toggle 的结果</strong> <p>`Set` 将目标位写为 1；`Reset` 将目标位写为 0；`Toggle` 将目标位取反。运行端会先读取父级整数 Tag 当前值，再按 Bit Index 计算目标位，最后把新的整数值提交给宿主机。Bit Index 0 表示最低位。</p> <ul> <li>Set：目标位 = 1</li><li>Reset：目标位 = 0</li><li>Toggle：目标位取反</li><li>Bit Index 0：最低位</li><li>目标 Tag：父级整数 Tag</li> </ul> </article><article id="write-tag-item-8" class="docs-detail-row"> <strong>读取位和写入位不要混用字段</strong> <p>读取位时使用 `TAG[bit]`，例如 `PLC_LINE01.PUMP01.STATUS[3]`；写入位时不应在 Target Tag 中写 `[3]`。Write Tag Bit 的 Target Tag 填 `PLC_LINE01.PUMP01.STATUS`，Bit Index 填 `3`。该规则可以避免运行端将位引用误当成完整写入目标。</p> <ul> <li>读取位语法：`TAG[bit]`</li><li>读取位：`ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)`</li><li>写位目标：`PLC_LINE01.PUMP01.STATUS`</li><li>写位位号：`Bit Index = 3`</li><li>写位动作：`Set / Reset / Toggle`</li> </ul> <pre class="docs-code-block"><code>// 正确：读取位
ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)
// 正确：写位字段
Target Tag: PLC_LINE01.PUMP01.STATUS
Bit Index: 3
Bit Action: Toggle</code></pre> </article><article id="write-tag-item-9" class="docs-detail-row"> <strong>点击写入的 Tag 字段也可以用模板变量</strong> <p>Write Tag 和 Write Tag Bit 的 Target Tag 可以填写完整点名，也可以填写带模板变量的点名。当前编辑器直接显示 `<PLC>.CMD_START` 或 `<PLC>.<RUN_TAG>`，无需手工补引号；保存时会自动规范为字符串表达式。</p> <pre class="docs-code-block"><code>Target Tag: <PLC>.CMD_START
Value: 1</code></pre> </article><article id="write-tag-item-10" class="docs-detail-row"> <strong>写值动作为什么不一定立即生效</strong> <p>最终是否成功由宿主机决定。宿主机可以做权限校验、确认框、原因输入、审计记录和异步写入。因此，界面发起写入动作，不等于设备端已经同步确认完成。</p> <pre class="docs-code-block"><code>hqVisuDesigner.WriteTag({
TagName: "PLC_LINE01.PUMP01.CMD",
Value: 1,
PermissionCode: "io:write",
RequireConfirm: true,
ConfirmText: "确认执行写值？"
});</code></pre> </article><article id="write-tag-item-11" class="docs-detail-row"> <strong>FORCE 当前不可用</strong> <p>Mingcedar 会拒绝 FORCE 写入，因此当前 Write Tag Bit 编辑器不再提供 FORCE 勾选框。旧项目若残留 UseForceMode=true，重新保存该行为时会忽略旧设置并写回 false。</p> </article><article id="write-tag-item-12" class="docs-detail-row"> <strong>权限、确认和原因输入的配置边界</strong> <p>PermissionCode、RequireConfirm、ConfirmText、RequireReason、AuditAction 属于运行协议字段，当前 Write Tag 与 Write Tag Bit 编辑器不直接展示它们；编辑已有行为时会保留这些字段。最终权限、确认、原因和审计逻辑由运行端执行，不要把它们误写进 Target Tag、Value 或 Condition。</p> </article><article id="write-tag-item-13" class="docs-detail-row"> <strong>写值应来自明确用户动作</strong> <p>关键写值应放在按钮点击、确认动作或明确操作触发的脚本中。页面加载、自动刷新、普通动画表达式和质量提示不应自动下发设备命令。这样可以让运行端权限、确认、原因输入和审计链路都有清晰触发来源。</p> <ul> <li>适合：按钮点击、确认按钮、明确操作脚本</li><li>不适合：页面加载时自动写入</li><li>不适合：Move / Rotate / Scale / Script Color 等表达式位</li><li>关键写值应让用户能看到目标、值和确认信息</li> </ul> </article> </div> <div class="docs-note-grid"> <figure id="write-tag-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current/write/write-normal.png" alt="Write Tag" loading="lazy" decoding="async"> <figcaption> <strong>Write Tag</strong> <p>一个值写到一个 Tag 时，优先使用明确的写值行为。</p> </figcaption> </figure><figure id="write-tag-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current/write/bit-normal.png" alt="Write Tag Bit" loading="lazy" decoding="async"> <figcaption> <strong>Write Tag Bit</strong> <p>位级写入应使用专门的 Write Tag Bit，目标 Tag 填父级整数点名，位号由 Bit Index 指定。</p> </figcaption> </figure> </div> </section>