交互行为详解 | HQ VISU Designer

交互

Before Use

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

交互 优先使用标准行为

如果插件已经提供明确行为入口，例如 Open Link、Open Page as Popup、Write Tag、Open Diagnosis，应优先使用标准行为。标准行为具有更清晰的字段边界，也便于运行平台按权限、确认和审计规则接管。

交互 配置行为和脚本行为的区别

配置行为适合标准化动作，例如打开页面、打开/关闭弹窗、写值、打开诊断和设置变量；脚本行为适合局部特殊动作、样式变化和组合逻辑。正式项目应以配置行为表达主要动作，脚本用于补充特例。

交互 阅读顺序

先看 Set Variable / Open Diagnosis / Open Link / Popup / Write Tag 这些标准动作，再看 Click / Hover / Press-Release 三种脚本动作，最后看交互类通用选项。

变量

Set Variable on Click：先改页面运行时状态，不直接碰设备

这个行为适合把一次点击结果写入运行时变量空间，用于页面局部联动、局部显示切换和流程阶段标记。

它最适合什么场景

切换选中项、切换面板显隐、记录当前 tab、切换当前设备卡片、保存一次页面运行时状态，这些场景适合 Set Variable on Click。它不是设备写入动作，而是页面上下文动作。

字段说明

Variable 填写变量名本身，不额外加引号；Value 可以是单行表达式，也可以是完整多行脚本；Enabled 决定当前点击是否允许生效。

Value 支持哪些写法

Value 可以填写固定字符串、数字、布尔表达式、变量或多行脚本。多行脚本需要用 return 返回最终写入值。Variable 字段填写变量名，不填写完整 Tag 点名，也不加引号。

Variable：currentTab
Value 固定文本："alarm"
Value 表达式：nextTab
Value 多行脚本：return selectedDevice;
Enabled：running === true

// Variable
currentTab

// Value
return selectedDevice === "PUMP01" ? "pump" : "overview";

相对 Write Tag 的优先场景

只要结果只影响页面显示或页面内逻辑，而不需要发到 PLC 或宿主机标签服务，就优先用 Set Variable on Click。这样边界更清楚，也更安全。

// Definition
var nextValue = "tab-alarm";

// Variable
currentTab

// Value
nextValue

诊断

Open Diagnosis：把宿主诊断窗口需要的字段一次带齐

Open Diagnosis 不是普通弹窗，而是向宿主机发出“请按诊断协议打开一个诊断窗口”的请求。

它会把什么信息带给宿主机

核心字段是 PLC、Template、Status Prefix、Title 和启用条件。宿主机据此决定当前诊断属于哪台 PLC、打开哪个弹窗模板、状态点名前缀的组合方式、标题显示内容，以及弹窗里哪些 bad 点应该被带出来。

字段与用途

PLC 用于识别当前设备或控制器；Template 用于选择诊断模板；Status Prefix 用于和模板中的尾缀组合成诊断点名；Title 用于弹窗标题；Enabled 用于控制当前对象是否允许打开诊断。

PLC：设备或 PLC 标识
Template：诊断模板名称
Status Prefix：诊断点名前缀
Title：弹窗标题
Enabled：启用条件

Status Prefix 和 Title 说明

Status Prefix 是可选前缀，宿主机会把它和模板内填写的尾缀组合成诊断点名的一部分；Title 更适合作为弹窗左上角标题或分组标题。PLC 是 PLC 名称，Template 是宿主机弹出模板名称。启用条件为 false 时，这个诊断动作不启用。

诊断字段里可以直接用模板变量

PLC、Template、Status Prefix、Title 都可以使用模板变量。填写时应按字符串写法使用 `'<PLC>'`、`'<MUBAN>'`、`'<STATUS_PREFIX>'`、`'<TITLE>'`；单引号和双引号都支持。

PLC: '<PLC>'
Template: '<MUBAN>'
Status Prefix: '<STATUS_PREFIX>'
Title: '<TITLE>'

Open Diagnosis 的适用场景

只要点击对象的目的，是打开一个与设备相关的诊断窗、故障窗、设备详情诊断窗，而不是简单跳页，就更适合 Open Diagnosis。

hqVisuDesigner.openDiagnosis({
  PLC: "PLC1",
  ID: "F01",
  DiagnosisControl: "device-default",
  GroupRightIndex: "F01",
  RunWhen: true
});

诊断弹窗只显示相关 bad 点

宿主机弹窗诊断只显示被点击组件关联的 Tag，以及弹窗配置关联的 Tag。它不会把当前页面所有 bad 点都放入弹窗。这样点击某个设备时，用户看到的是该设备相关问题，而不是整页报警合集。

组件绑定了具体 Tag 时，优先按组件 Tag 过滤。
弹窗配置填写了 tags、deviceCodes、areaCodes、objectIdentifiers 或 groupCodes 时，再按这些范围合并过滤。
Status Prefix 可为空；为空时只用模板尾缀或配置范围判断。
模板语法 `<name>` 可以用于动画、文本、诊断字段和常用行为配置，导出时按模板实例替换。

**Open Diagnosis**
打开诊断窗时，真正关键的是把运行平台需要的字段传对，而不是只让一个按钮在界面上可点击。

跳转

Open Link：按五种可见目标模式配置跳转

当前编辑器把目标分为 Presentation Page、File / URL、System Screen、Website、Script Action；先选用户可见模式，再配置该模式支持的目标、打开方式和参数。

五种 Destination type

新配置应按编辑器当前显示的五种模式理解，不直接操作底层 `ppt-page`、`html-page`、`screen-code`、`external-url`、`javascript` 兼容值。

Presentation Page：从当前 PPT 页面列表选择，编辑器显示 Page ID、Page No.、Page Title 和 Runtime File。
File / URL：选择文件，或填写导出页、相对文件路径及 URL。
System Screen：填写宿主机 Menu / Screen Code，用于跨画面包或菜单导航。
Website：填写可访问的网站或内网系统 URL。
Script Action：只有目标需要动态计算或动作需要组合时使用。

地址写法

同 PPT 页面优先用 Presentation Page 选择；文件或相对页面使用 File / URL；跨画面包使用 System Screen；外部与内网站点使用 Website。

同 PPT 页面：Presentation Page
相对文件：File / URL，例如 `./help.html`、`../area/detail.html`
跨画面包：System Screen + Menu / Screen Code
外部地址：Website，例如 `https://example.com`
内网地址：Website，例如 `http://<server-ip>:<port>/path`

打开方式选择

默认在宿主框架内打开，适合普通 HMI 页面切换；需要只显示目标画面时选择全屏打开；需要保留当前页面并打开外部系统时选择新标签打开。

框架内打开：普通菜单页、设备页、工艺页。
全屏打开：Andon、大屏、只希望看到目标画面的页面。
新标签打开：外部网站、报表系统、帮助文档或第三方平台。

脚本跳转的适用场景

如果跳转目标需要在脚本里动态计算，例如先根据页面变量决定跳到哪一页，或者需要拼出 screen code，再考虑 Click Script。固定目标优先还是配置行为。

hqVisuDesigner.openPage("Alarm");
hqVisuDesigner.openScreen("PUMP_OVERVIEW");
hqVisuDesigner.openWebsite("https://example.com", true);

**Open Link**
跳转最关键的是先分清目标类型，而不是把所有目标都当成“链接”。

弹窗

Open Page as Popup / Close Current Popup：把页面当弹窗打开并闭环关闭

打开行为放在主页面入口，关闭行为放在弹窗页内部；两者不改变主页面导航，并可通过页面参数和返回结果形成一次完整对话。

高级参数只处理动态需求

静态参数填写 JSON 对象；动态 Page Code 或动态参数才使用表达式。Backdrop 可选择 dim 或 transparent，Allow multiple 决定同一页面是否允许重复实例。

Page Code: motor_details
Page parameters: {"motorId": 3}
Display: Fit page content
Modal: true

写值

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

只要动作最终要落到 Tag，优先理解 Write Tag 和 Write Tag Bit，再判断是否需要脚本扩展。

Write Tag 适合什么

一个值写到一个 Tag，是 Write 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 字段支持哪些写法

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

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

Write Tag Bit 适合什么

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

Write Tag Bit 关键字段

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 / Reset / Toggle 的结果

`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

点击写入的 Tag 字段也可以用模板变量

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: "确认执行写值？"
});

FORCE 当前不可用

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 等表达式位
关键写值应让用户能看到目标、值和确认信息

**Write Tag**
一个值写到一个 Tag 时，优先使用明确的写值行为。

**Write Tag Bit**
位级写入应使用专门的 Write Tag Bit，目标 Tag 填父级整数点名，位号由 Bit Index 指定。

脚本

Click / Hover / Press-Release Script：按真实触发阶段选择脚本

Click 处理一次点击，Hover 处理移入移出，Press/Release 处理按下与松开。能通过标准行为配置的动作仍应优先配置，脚本负责特例和组合逻辑。

Click Script 适合什么

局部动画、状态提示、自定义校验、复杂流程跳转、输入确认后二次处理，这些场景适合 Click Script。当一个动作不只是写一个值或跳转一个页面时，可以通过脚本组织组合逻辑。

Click Script 常见写法

Click Script 适合先读页面输入、再判断条件、再调用标准方法。脚本中仍应优先调用 hqVisuDesigner.openPage、hqVisuDesigner.openDiagnosis、hqVisuDesigner.writeTag 等明确方法，而不是把全部逻辑写成不可复用的 DOM 操作。

读取输入模板：template.getValue("Input Template")
确认条件：if (...) return;
写值：hqVisuDesigner.writeTag(payload)
跳转：hqVisuDesigner.openPage("Alarm")

var value = template.getValue("SetpointInput");
if (value === "") {
  hqVisuDesigner.setComponentText("Message", "请输入设定值");
  return;
}

hqVisuDesigner.writeTag({
  TagName: "Device.SETPOINT",
  Value: Number(value),
  PermissionCode: "io:write",
  RequireConfirm: true
});

Hover Script 适合什么

悬停高亮、预览、局部透明度变化、帮助提示和短时反馈都适合 Hover Script。它最好的用法是做轻量反馈，而不是承载重业务逻辑；运行端不会为 Hover Script 提供设备写入能力。

// Mouse Over
object.style.opacity = "0.7";

// Mouse Out
object.style.opacity = "1";

Press/Release Script 适合什么

需要区分按下和松开时使用 Press/Release Script。Pointer Press 在主指针按下时执行；Pointer Release 在松开、取消或丢失指针捕获时执行。两段脚本必须成对设计，释放段负责复位。

点动、按住执行、松手停止
按压态显示与恢复
Pointer Press / Pointer Release 都是完整脚本
没有单独 Condition 字段
不能替代 PLC 联锁、急停和安全回路

// Pointer Press
WriteTagBoolean("<CommandTag>", true);

// Pointer Release
WriteTagBoolean("<CommandTag>", false);

脚本优先于配置的场景

当目标需要动态计算、需要先校验输入、需要组合多个方法、或者需要在一次点击里顺序执行多个动作时，脚本通常更合适。比如先读模板值，再判断是否合法，再写 Tag，再切换页面。

不应优先使用脚本的场景

如果只是打开页面、写一个 Tag、打开诊断窗或切换一个页面变量，应优先使用明确配置行为。这样维护人员可以直接从界面理解动作意图，不需要先阅读脚本逻辑。

**Click Script**
复杂动作和局部特例更适合 Click Script，但简单动作仍优先配置行为。

**Hover Script**
Hover Script 最适合轻量反馈，而不是承担重业务逻辑。

Press/Release Script 编辑器结构 — **Press/Release Script**
实际模式会把两个脚本框显示为 Pointer Press 和 Pointer Release；释放段负责安全复位。

**脚本片段选择器**
脚本片段会根据当前输入位置插入短表达式或完整脚本，适合减少把代码写到错误字段的问题。

选项

交互通用选项：手型光标、粗边框和禁用时隐藏

很多交互行为窗口里会出现一些通用选项，它们看起来不起眼，但很影响最终使用体验。

Show hand cursor when enabled

当行为当前可用时，把鼠标指针变成手型。这能给用户一个非常直接的可点提示，尤其适合按钮、链接、跳转块和交互卡片。

Use bold border when enabled

这是样式强化选项，适合在某些对象启用时提供边框强调。不建议依赖它承担完整状态表达，它更适合作为细节增强。

Hide when disabled

当某个交互在当前条件下不应允许操作时，Hide when disabled 可以隐藏入口，避免用户误以为对象可操作。它适合条件未满足、设备未就绪或上下文未准备好的场景。