所属产品: Mingcedar Studio DESIGNER

交互行为详解 | Mingcedar Studio

交互行为处理用户操作之后的动作结果。配置时先明确目标：写页面变量、写 Tag、跳转页面、打开或关闭页面弹窗、打开诊断窗，还是执行自定义指针脚本。

首次发布 2026-10-25T12:48:42.583144527Z 最近更新 2026-10-25T12:48:42.583143595Z

<section id="preface" class="docs-block docs-block-intro"> <span class="section-kicker">交互</span> <h2>使用前说明</h2> <p>交互行为处理用户操作之后的动作结果。配置时先明确目标：写页面变量、写 Tag、跳转页面、打开或关闭页面弹窗、打开诊断窗，还是执行自定义指针脚本。</p> <div class="docs-task-grid"> <article id="preface-item-1" class="docs-task-card"> <span>交互</span> <strong>优先使用标准行为</strong> <p>如果插件已经提供明确行为入口，例如 Open Link、Open Page as Popup、Write Tag、Open Diagnosis，应优先使用标准行为。标准行为具有更清晰的字段边界，也便于运行平台按权限、确认和审计规则接管。</p> </article><article id="preface-item-2" class="docs-task-card"> <span>交互</span> <strong>配置行为和脚本行为的区别</strong> <p>配置行为适合标准化动作，例如打开页面、打开/关闭弹窗、写值、打开诊断和设置变量；脚本行为适合局部特殊动作、样式变化和组合逻辑。正式项目应以配置行为表达主要动作，脚本用于补充特例。</p> </article><article id="preface-item-3" class="docs-task-card"> <span>交互</span> <strong>阅读顺序</strong> <p>先看 Set Variable / Open Diagnosis / Open Link / Popup / Write Tag 这些标准动作，再看 Click / Hover / Press-Release 三种脚本动作，最后看交互类通用选项。</p> </article> </div> </section> <section id="set-variable" class="docs-block"> <span class="section-kicker">变量</span> <h2>Set Variable on Click：页面运行时变量赋值</h2> <p>这个行为适合把一次点击结果写入运行时变量空间，用于页面局部联动、局部显示切换和流程阶段标记。</p> <div class="docs-detail-list"> <article id="set-variable-item-1" class="docs-detail-row"> <strong>它最适合什么场景</strong> <p>切换选中项、切换面板显隐、记录当前 tab、切换当前设备卡片、保存一次页面运行时状态，这些场景适合 Set Variable on Click。它不是设备写入动作，而是页面上下文动作。</p> </article><article id="set-variable-item-2" class="docs-detail-row"> <strong>字段说明</strong> <p>Variable（Target variable）填写变量名，不加引号；Value 可以是单行表达式，也可以是返回值的多行脚本；Condition 决定当前点击是否允许生效。Setup Script 可准备 Value 和 Condition 使用的局部变量。</p> </article><article id="set-variable-item-3" class="docs-detail-row"> <strong>Value 支持哪些写法</strong> <p>Value 可以填写固定字符串、数字、布尔表达式、变量或多行脚本。多行脚本需要用 return 返回最终写入值。Variable 字段填写变量名，不填写完整 Tag 点名，也不加引号。</p> <ul> <li>Variable：currentTab</li><li>Value 固定文本："alarm"</li><li>Value 表达式：nextTab</li><li>Value 多行脚本：return selectedDevice;</li><li>Condition：running === true</li> </ul> <pre class="docs-code-block"><code>// Variable

currentTab

// Value

return selectedDevice === "PUMP01" ? "pump" : "overview";</code></pre> </article><article id="set-variable-item-4" class="docs-detail-row"> <strong>相对 Write Tag 的优先场景</strong> <p>只要结果只影响页面显示或页面内逻辑，而不需要发到 PLC 或宿主机标签服务，就优先用 Set Variable on Click。这样边界更清楚，也更安全。</p> <pre class="docs-code-block"><code>// Setup Script

var nextValue = "tab-alarm";

// Variable

currentTab

// Value

nextValue</code></pre> </article> </div> <div class="docs-note-grid"> <figure id="set-variable-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/VariableWriteBehaviorEditorForm.png" alt="Set Variable on Click" loading="lazy" decoding="async"> <figcaption> <strong>Set Variable on Click</strong> <p>只改页面运行时状态时，优先用变量写入，而不是直接写设备值。</p> </figcaption> </figure> </div> </section><section id="open-diagnosis" class="docs-block"> <span class="section-kicker">诊断</span> <h2>Open Diagnosis：诊断窗口参数配置</h2> <p>Open Diagnosis 不是普通弹窗，而是向宿主机发出“请按诊断协议打开一个诊断窗口”的请求。</p> <div class="docs-detail-list"> <article id="open-diagnosis-item-1" class="docs-detail-row"> <strong>它会把什么信息带给宿主机</strong> <p>编辑器字段为 PLC、Template、Status Prefix、Title 和 Condition，但界面名称与宿主机载荷名称不同。配置时按下方映射判断用途，不能仅凭字段英文名称猜测。</p> </article><article id="open-diagnosis-item-2" class="docs-detail-row"> <strong>字段与用途</strong> <p>PLC 对应载荷 PLC，指定设备；Template 对应 ID，指定弹窗模板编码；Status Prefix 对应 DiagnosisControl，指定状态 Tag 前缀；Title 对应 GroupRightIndex，指定标题或对象名；Condition 对应 Enabled，控制动作是否允许触发。</p> <ul> <li>PLC → PLC：PLC / 设备站名</li><li>Template → ID：弹窗模板编码</li><li>Status Prefix → DiagnosisControl：状态 Tag 前缀</li><li>Title → GroupRightIndex：标题或对象名</li><li>Condition → Enabled：启用条件</li> </ul> </article><article id="open-diagnosis-item-3" class="docs-detail-row"> <strong>Status Prefix 和 Title 说明</strong> <p>例如 Template 填 'device-default'、Status Prefix 填 'AREA01.PUMP01'、Title 填 'PUMP_01'，运行端按 device-default 选择模板，并使用 AREA01.PUMP01 作为状态 Tag 前缀、PUMP_01 作为显示标题。Condition 为 false 时不触发。</p> </article><article id="open-diagnosis-item-4" class="docs-detail-row"> <strong>诊断字段里可以直接用模板变量</strong> <p>PLC、Template、Status Prefix、Title 都可以使用模板变量。填写时应按字符串写法使用 `'<PLC>'`、`'<DIAGNOSIS_TEMPLATE>'`、`'<STATUS_PREFIX>'`、`'<TITLE>'`；单引号和双引号都支持。</p> <pre class="docs-code-block"><code>PLC: '<PLC>'

Template: '<DIAGNOSIS_TEMPLATE>'

Status Prefix: '<STATUS_PREFIX>'

Title: '<TITLE>'</code></pre> </article><article id="open-diagnosis-item-5" class="docs-detail-row"> <strong>Open Diagnosis 的适用场景</strong> <p>只要点击对象的目的，是打开一个与设备相关的诊断窗、故障窗、设备详情诊断窗，而不是简单跳页，就更适合 Open Diagnosis。</p> <pre class="docs-code-block"><code>hqVisuDesigner.openDiagnosis({

PLC: "PLC1",

ID: "device-default",

DiagnosisControl: "AREA01.PUMP01",

GroupRightIndex: "PUMP_01"

});</code></pre> </article><article id="open-diagnosis-item-6" class="docs-detail-row"> <strong>诊断弹窗只显示相关 bad 点</strong> <p>宿主机弹窗诊断只显示被点击组件关联的 Tag，以及弹窗配置关联的 Tag。它不会把当前页面所有 bad 点都放入弹窗。这样点击某个设备时，用户看到的是该设备相关问题，而不是整页报警合集。</p> <ul> <li>组件绑定了具体 Tag 时，优先按组件 Tag 过滤。</li><li>弹窗配置填写了 tags、deviceCodes、areaCodes、objectIdentifiers 或 groupCodes 时，再按这些范围合并过滤。</li><li>Template / ID 选择弹窗模板；Status Prefix / DiagnosisControl 是状态 Tag 前缀；Title / GroupRightIndex 是标题或对象名。</li><li>模板语法 `<name>` 可以用于动画、文本、诊断字段和常用行为配置，导出时按模板实例替换。</li> </ul> </article> </div> <div class="docs-note-grid"> <figure id="open-diagnosis-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current/diagnosis/normal.png" alt="Open Diagnosis" loading="lazy" decoding="async"> <figcaption> <strong>Open Diagnosis</strong> <p>打开诊断窗时，真正关键的是把运行平台需要的字段传对，而不是只让一个按钮在界面上可点击。</p> </figcaption> </figure> </div> </section><section id="open-link" class="docs-block"> <span class="section-kicker">跳转</span> <h2>Open Link：按四种目标类型配置跳转</h2> <p>在 Destination 中选择 Internal page、External URL、System menu 或 Run script，再填写对应地址或动作。</p> <div class="docs-detail-list"> <article id="open-link-item-1" class="docs-detail-row"> <strong>四种 Destination</strong> <p>在 Destination 中选择目标类型，然后填写该类型显示的字段。以下界面图以 Internal page 为例。</p> <ul> <li>Internal page：填写 Page address（如 Main.html），或点击 Select PPT page... 选择本 PPT 页面。</li><li>External URL：打开可从运行端访问的外部或内网地址。</li><li>System menu：打开宿主机已配置的菜单目标。</li><li>Run script：目标按运行状态计算或点击后需组合动作时使用。</li> </ul> </article><article id="open-link-item-2" class="docs-detail-row"> <strong>地址写法</strong> <p>同 PPT 导出页面使用 Internal page；完整外部或内网网址使用 External URL；宿主机菜单目标使用 System menu。Internal page 的相对地址从当前导出页解析，必须留在资源根目录内。</p> <ul> <li>同 PPT 页面：Internal page + Select PPT page...</li><li>同包相对页面：Internal page，例如 `Main.html` 或 `./help.html`</li><li>宿主菜单：System menu</li><li>外部或内网网址：External URL</li> </ul> </article><article id="open-link-item-3" class="docs-detail-row"> <strong>打开方式选择</strong> <p>在 Internal page 的 Open options 中选择 HMI window 或 Page only；按需要设置 Fullscreen 和 New tab，并在导出后验证打开方式。</p> <ul> <li>HMI window：在 HMI 窗口打开目标。</li><li>Page only：只打开目标页。</li><li>Fullscreen、New tab：分别控制全屏显示和在新标签页打开。</li> </ul> </article><article id="open-link-item-4" class="docs-detail-row"> <strong>脚本跳转的适用场景</strong> <p>如果跳转目标需要按页面变量动态计算，或需要拼接 screen code，可使用 Click Script。固定目标优先使用配置行为。</p> <pre class="docs-code-block"><code>hqVisuDesigner.openPage("Alarm");

hqVisuDesigner.openScreen("PUMP_OVERVIEW");

hqVisuDesigner.openWebsite("https://example.com", true);</code></pre> </article> </div> <div class="docs-note-grid"> <figure id="open-link-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/open-link-internal-page.png" alt="Open Link 的 Internal page 设置，显示 Page address、Open options 和 Parameters" loading="lazy" decoding="async"> <figcaption> <strong>Open Link：Internal page</strong> <p>先选四种 Destination 之一；图中 Internal page 可填写导出页地址、选择 PPT 页面、设置打开方式和可选参数。</p> </figcaption> </figure> </div> </section><section id="popup-actions" class="docs-block"> <span class="section-kicker">弹窗</span> <h2>Open Page as Popup / Close Current Popup：弹窗打开与关闭</h2> <p>打开行为放在主页面入口，关闭行为放在弹窗页内部；两者不改变主页面导航，并可通过页面参数和返回结果形成一次完整对话。</p> <div class="docs-detail-list"> <article id="popup-actions-item-1" class="docs-detail-row"> <strong>Open Page as Popup 的三个主要选择</strong> <p>先选择 Popup page，再在 Appearance 中选择 Fit content 或 Full page canvas，然后在 Interaction 中设置下层页面操作、Esc 键和点击外部时的关闭方式。右侧 Enabled 控制此行为是否启用。</p> <ul> <li>Popup page：从当前 PPT 选择或输入已有导出 Page Code，不带 .html</li><li>Fit content：适配主要内容</li><li>Full page canvas：显示完整画布</li><li>Block the page behind：阻止操作下层页面</li><li>Esc closes the popup / Clicking outside closes it：配置关闭入口</li> </ul> </article><article id="popup-actions-item-2" class="docs-detail-row"> <strong>高级参数只处理动态需求</strong> <p>固定目标页可直接在主区选择。需要传参、动态指定 Page Code、设置背景或重复弹窗行为时，展开 Advanced options，按所用版本显示的字段配置，并在导出后验证效果。</p> <pre class="docs-code-block"><code>Page Code: motor_details

Page parameters: {"motorId": 3}

Display: Fit page content

Modal: true</code></pre> </article><article id="popup-actions-item-3" class="docs-detail-row"> <strong>Close Current Popup 放在哪里</strong> <p>将 Close Current Popup 绑定到弹窗页内的 Close、Cancel、OK 或 Done 按钮。默认仅关闭弹窗；打开方需要接收结果时，勾选 Return data when this button is clicked (optional) 并配置返回值。此行为不写 Tag，也不跳转主页面。</p> </article><article id="popup-actions-item-4" class="docs-detail-row"> <strong>导出边界</strong> <p>弹窗页仍是画面包页面。新增、删除、重命名弹窗页，或修改其共享脚本和资源后，必须整包导出。只导出打开按钮所在页会造成运行端缺少目标页面或资源。</p> </article> </div> <div class="docs-note-grid"> <figure id="popup-actions-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/open-popup.png" alt="Open Popup 设置显示 Popup page、Appearance、Interaction 和 Enabled" loading="lazy" decoding="async"> <figcaption> <strong>Open Popup</strong> <p>选择弹窗页、显示方式和关闭策略；传参等设置位于 Advanced options。</p> </figcaption> </figure><figure id="popup-actions-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/close-popup.png" alt="Close Popup 设置显示 Enabled 和 Return data" loading="lazy" decoding="async"> <figcaption> <strong>Close Popup</strong> <p>默认关闭当前弹窗并保留下层页面；需要时勾选 Return data。</p> </figcaption> </figure> </div> </section><section id="write-tag" class="docs-block"> <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><section id="script-interactions" class="docs-block"> <span class="section-kicker">脚本</span> <h2>Click / Hover / Press-Release Script：按真实触发阶段选择脚本</h2> <p>Click 处理一次点击，Hover 处理移入移出，Press/Release 处理按下与松开。能通过标准行为配置的动作仍应优先配置，脚本负责特例和组合逻辑。</p> <div class="docs-detail-list"> <article id="script-interactions-item-1" class="docs-detail-row"> <strong>Click Script 适合什么</strong> <p>局部动画、状态提示、自定义校验、复杂流程跳转、输入确认后二次处理，这些场景适合 Click Script。当一个动作不只是写一个值或跳转一个页面时，可以通过脚本组织组合逻辑。</p> </article><article id="script-interactions-item-2" class="docs-detail-row"> <strong>Click Script 常见写法</strong> <p>Click Script 适合先读页面输入、再判断条件、再调用标准方法。脚本中仍应优先调用 hqVisuDesigner.openPage、hqVisuDesigner.openDiagnosis、hqVisuDesigner.WriteTag 等明确方法，而不是把全部逻辑写成不可复用的 DOM 操作。</p> <ul> <li>读取输入模板：template.getValue("Input Template")</li><li>确认条件：if (...) return;</li><li>写值：hqVisuDesigner.WriteTag(payload)</li><li>跳转：hqVisuDesigner.openPage("Alarm")</li> </ul> <pre class="docs-code-block"><code>var input = template.getValue("SetpointInput");

var value = String(input == null ? "" : input).trim();

var number = Number(value);

// 示例范围 0～100，应改为项目的有效范围。

if (value === "" || !Number.isFinite(number) || number < 0 || number > 100) {

hqVisuDesigner.setComponentText("Message", "请输入 0～100 的有效设定值");

return;

}

hqVisuDesigner.WriteTag({

TagName: "PLC_LINE01.PUMP01.SETPOINT",

Value: number,

PermissionCode: "io:write",

RequireConfirm: true

});</code></pre> </article><article id="script-interactions-item-3" class="docs-detail-row"> <strong>Hover Script 适合什么</strong> <p>悬停高亮、预览、局部透明度变化、帮助提示和短时反馈都适合 Hover Script。它最好的用法是做轻量反馈，而不是承载重业务逻辑；运行端不会为 Hover Script 提供设备写入能力。</p> <pre class="docs-code-block"><code>// Mouse Over

object.style.opacity = "0.7";

// Mouse Out

object.style.opacity = "1";</code></pre> </article><article id="script-interactions-item-4" class="docs-detail-row"> <strong>Press/Release Script 适合什么</strong> <p>需要区分按下和松开时使用 Press/Release Script。Pointer Press 在主指针按下时执行；Pointer Release 在松开、取消或丢失指针捕获时执行。两段脚本必须成对设计，释放段负责复位。</p> <ul> <li>点动、按住执行、松手停止</li><li>按压态显示与恢复</li><li>Pointer Press / Pointer Release 都是完整脚本</li><li>没有单独 Condition 字段</li><li>不能替代 PLC 联锁、急停和安全回路</li> </ul> <pre class="docs-code-block"><code>// Pointer Press

WriteTagBoolean("<CommandTag>", true);

// Pointer Release

WriteTagBoolean("<CommandTag>", false);</code></pre> </article><article id="script-interactions-item-5" class="docs-detail-row"> <strong>脚本优先于配置的场景</strong> <p>当目标需要动态计算、需要先校验输入、需要组合多个方法、或者需要在一次点击里顺序执行多个动作时，脚本通常更合适。比如先读模板值，再判断是否合法，再写 Tag，再切换页面。</p> </article><article id="script-interactions-item-6" class="docs-detail-row"> <strong>不应优先使用脚本的场景</strong> <p>如果只是打开页面、写一个 Tag、打开诊断窗或切换一个页面变量，应优先使用明确配置行为。这样维护人员可以直接从界面理解动作意图，不需要先阅读脚本逻辑。</p> </article> </div> <div class="docs-note-grid"> <figure id="script-interactions-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/MouseBehaviorEditorForm.png" alt="Click Script" loading="lazy" decoding="async"> <figcaption> <strong>Click Script</strong> <p>复杂动作和局部特例更适合 Click Script，但简单动作仍优先配置行为。</p> </figcaption> </figure><figure id="script-interactions-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/MouseBehaviorEditorForm.png" alt="Hover Script" loading="lazy" decoding="async"> <figcaption> <strong>Hover Script</strong> <p>Hover Script 最适合轻量反馈，而不是承担重业务逻辑。</p> </figcaption> </figure><figure id="script-interactions-image-3" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/MouseBehaviorEditorForm.png" alt="Press/Release Script 编辑器结构" loading="lazy" decoding="async"> <figcaption> <strong>Press/Release Script</strong> <p>实际模式会把两个脚本框显示为 Pointer Press 和 Pointer Release；释放段负责安全复位。</p> </figcaption> </figure><figure id="script-interactions-image-4" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/quick-methods.png" alt="Quick Methods 方法库显示类别、方法说明、示例和参数" loading="lazy" decoding="async"> <figcaption> <strong>Quick Methods 方法库</strong> <p>按类别或搜索查找方法，查看代码示例及参数后点击 Insert；可用方法以当前插件版本为准。</p> </figcaption> </figure> </div> </section><section id="shared-options" class="docs-block"> <span class="section-kicker">选项</span> <h2>交互通用选项：手型光标、粗边框和禁用时隐藏</h2> <p>交互行为的通用选项用于提示可操作状态、强调启用状态，以及控制禁用时的显示方式。</p> <div class="docs-detail-list"> <article id="shared-options-item-1" class="docs-detail-row"> <strong>Show hand cursor when enabled</strong> <p>启用后，行为可用时鼠标指针显示为手型，用于提示按钮、链接、跳转块和交互卡片可点击。</p> </article><article id="shared-options-item-2" class="docs-detail-row"> <strong>Use bold border when enabled</strong> <p>这是样式强化选项，适合在某些对象启用时提供边框强调。不建议依赖它承担完整状态表达，它更适合作为细节增强。</p> </article><article id="shared-options-item-3" class="docs-detail-row"> <strong>Hide when disabled</strong> <p>当某个交互在当前条件下不应允许操作时，Hide when disabled 可以隐藏入口，避免用户误以为对象可操作。它适合条件未满足、设备未就绪或上下文未准备好的场景。</p> </article> </div> </section>