交互行为详解 | Mingcedar Studio

交互

使用前说明

交互行为处理用户操作之后的动作结果。配置时先明确目标：写页面变量、写 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（Target variable）填写变量名，不加引号；Value 可以是单行表达式，也可以是返回值的多行脚本；Condition 决定当前点击是否允许生效。Setup Script 可准备 Value 和 Condition 使用的局部变量。

Value 支持哪些写法

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

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

// Variable
currentTab

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

相对 Write Tag 的优先场景

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

// Setup Script
var nextValue = "tab-alarm";

// Variable
currentTab

// Value
nextValue

诊断

Open Diagnosis：诊断窗口参数配置

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

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

编辑器字段为 PLC、Template、Status Prefix、Title 和 Condition，但界面名称与宿主机载荷名称不同。配置时按下方映射判断用途，不能仅凭字段英文名称猜测。

字段与用途

PLC 对应载荷 PLC，指定设备；Template 对应 ID，指定弹窗模板编码；Status Prefix 对应 DiagnosisControl，指定状态 Tag 前缀；Title 对应 GroupRightIndex，指定标题或对象名；Condition 对应 Enabled，控制动作是否允许触发。

PLC → PLC：PLC / 设备站名
Template → ID：弹窗模板编码
Status Prefix → DiagnosisControl：状态 Tag 前缀
Title → GroupRightIndex：标题或对象名
Condition → Enabled：启用条件

Status Prefix 和 Title 说明

例如 Template 填 'device-default'、Status Prefix 填 'AREA01.PUMP01'、Title 填 'PUMP_01'，运行端按 device-default 选择模板，并使用 AREA01.PUMP01 作为状态 Tag 前缀、PUMP_01 作为显示标题。Condition 为 false 时不触发。

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

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

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

Open Diagnosis 的适用场景

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

hqVisuDesigner.openDiagnosis({
  PLC: "PLC1",
  ID: "device-default",
  DiagnosisControl: "AREA01.PUMP01",
  GroupRightIndex: "PUMP_01"
});

诊断弹窗只显示相关 bad 点

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

组件绑定了具体 Tag 时，优先按组件 Tag 过滤。
弹窗配置填写了 tags、deviceCodes、areaCodes、objectIdentifiers 或 groupCodes 时，再按这些范围合并过滤。
Template / ID 选择弹窗模板；Status Prefix / DiagnosisControl 是状态 Tag 前缀；Title / GroupRightIndex 是标题或对象名。
模板语法 `<name>` 可以用于动画、文本、诊断字段和常用行为配置，导出时按模板实例替换。

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

跳转

Open Link：按四种目标类型配置跳转

在 Destination 中选择 Internal page、External URL、System menu 或 Run script，再填写对应地址或动作。

四种 Destination

在 Destination 中选择目标类型，然后填写该类型显示的字段。以下界面图以 Internal page 为例。

Internal page：填写 Page address（如 Main.html），或点击 Select PPT page... 选择本 PPT 页面。
External URL：打开可从运行端访问的外部或内网地址。
System menu：打开宿主机已配置的菜单目标。
Run script：目标按运行状态计算或点击后需组合动作时使用。

地址写法

同 PPT 导出页面使用 Internal page；完整外部或内网网址使用 External URL；宿主机菜单目标使用 System menu。Internal page 的相对地址从当前导出页解析，必须留在资源根目录内。

同 PPT 页面：Internal page + Select PPT page...
同包相对页面：Internal page，例如 `Main.html` 或 `./help.html`
宿主菜单：System menu
外部或内网网址：External URL

打开方式选择

在 Internal page 的 Open options 中选择 HMI window 或 Page only；按需要设置 Fullscreen 和 New tab，并在导出后验证打开方式。

HMI window：在 HMI 窗口打开目标。
Page only：只打开目标页。
Fullscreen、New tab：分别控制全屏显示和在新标签页打开。

脚本跳转的适用场景

如果跳转目标需要按页面变量动态计算，或需要拼接 screen code，可使用 Click Script。固定目标优先使用配置行为。

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

Open Link 的 Internal page 设置，显示 Page address、Open options 和 Parameters — **Open Link：Internal page**
先选四种 Destination 之一；图中 Internal page 可填写导出页地址、选择 PPT 页面、设置打开方式和可选参数。

弹窗

Open Page as Popup / Close Current Popup：弹窗打开与关闭

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

高级参数只处理动态需求

固定目标页可直接在主区选择。需要传参、动态指定 Page Code、设置背景或重复弹窗行为时，展开 Advanced options，按所用版本显示的字段配置，并在导出后验证效果。

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，配置集中便于维护；需要多步校验时用 Click Script，WriteTag 系列同样支持写入选项。

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

Write Tag 关键字段

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

Target Tag：`PLC_LINE01.PUMP01.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，同时必须落在父 Tag 的实际类型位宽内（例如 16 位仅 0 到 15）；Bit Action 选择 Set、Reset 或 Toggle。此流程先读整值再写回，不等于 PLC 原子位指令；多个写入者并发修改同一状态字时，应在 PLC 或业务端协调。

Target Tag：`<PLC>.CMD_WORD`
Bit Index：0 到 31，且小于父 Tag 实际位宽
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]`，例如 `PLC_LINE01.PUMP01.STATUS[3]`；写入位时不应在 Target Tag 中写 `[3]`。Write Tag Bit 的 Target Tag 填 `PLC_LINE01.PUMP01.STATUS`，Bit Index 填 `3`。该规则可以避免运行端将位引用误当成完整写入目标。

读取位语法：`TAG[bit]`
读取位：`ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)`
写位目标：`PLC_LINE01.PUMP01.STATUS`
写位位号：`Bit Index = 3`
写位动作：`Set / Reset / Toggle`

// 正确：读取位
ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)

// 正确：写位字段
Target Tag: PLC_LINE01.PUMP01.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: "PLC_LINE01.PUMP01.CMD",
  Value: 1,
  PermissionCode: "io:write",
  RequireConfirm: true,
  ConfirmText: "确认执行写值？"
});

FORCE 当前不可用

Mingcedar 会拒绝 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 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
});

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；释放段负责安全复位。

Quick Methods 方法库显示类别、方法说明、示例和参数 — **Quick Methods 方法库**
按类别或搜索查找方法，查看代码示例及参数后点击 Insert；可用方法以当前插件版本为准。

选项

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

交互行为的通用选项用于提示可操作状态、强调启用状态，以及控制禁用时的显示方式。

Show hand cursor when enabled

启用后，行为可用时鼠标指针显示为手型，用于提示按钮、链接、跳转块和交互卡片可点击。

Use bold border when enabled

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

Hide when disabled

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