交互行为详解 | HQ VISU Designer

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

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

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

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

// Variable
currentTab

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

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

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

// Variable
currentTab

// Value
nextValue

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

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

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

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。

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

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

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

File / URL 可以直接选择 PPT 导出的页面，也可以手动输入相对路径、上级路径或网站地址。宿主机会根据内容判断是本画面包页面、相对文件还是外部网站。

• PPT 页面：从页面列表直接选择。
• 相对文件：可以输入 `./page.html`、`../area/page.html`、`../../common/help.html`。
• 网站地址：可以输入 `www.bing.com`、`https://example.com` 或内网系统地址。
• 固定跳转优先用配置；动态目标再用脚本。

同画面包页面可以使用页面列表选择；相对文件可以使用 `./`、`../`；外部网站应使用完整 http 或 https 地址。内网系统地址也可以作为 URL，但应确认运行端终端能访问该地址。

• 同包页面：从页面列表选择
• 相对路径：`./help.html`、`../area/detail.html`
• 外部地址：`https://example.com`
• 内网地址：`http://<server-ip>:<port>/path`

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

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

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

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

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

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

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

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

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

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

悬停高亮、预览、局部透明度变化、帮助提示和短时反馈都适合 Hover Script。它最好的用法是做轻量反馈，而不是承载重业务逻辑。

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

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

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

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

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

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

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