HQ VISU HQ INDUSTRIAL SYSTEMS
中
HQ / HQ VISU Designer
文档手册

模板制作与传参：从可复用组件到页面通信

“传参”并不是一个统一入口。做模板前先判断值在什么时候确定、要用到哪里：设备地址随模板实例确定，就用模板变量；操作员在运行页临时输入，就用 Input 值或 Runtime Variable；从当前页面打开另一页或弹窗时携带上下文，才用页面参数。选对机制后，模板复制、页面跳转和运行时联动才不会互相干扰。

模板

模板: 模板制作与传参：从可复用组件到页面通信

从零制作一个可复用模板，掌握占位符命名、实例填值、Input 取值、报警模板配置和跨页面传参。重点是先分清不同值的生命周期，再选择对应机制。

先判断你要传的是哪一种值

“传参”并不是一个统一入口。做模板前先判断值在什么时候确定、要用到哪里：设备地址随模板实例确定，就用模板变量；操作员在运行页临时输入，就用 Input 值或 Runtime Variable；从当前页面打开另一页或弹窗时携带上下文，才用页面参数。选对机制后，模板复制、页面跳转和运行时联动才不会互相干扰。

  • 模板实例变量：插入模板后填写，例如 <PLC>、<RUN_TAG>；适合同一设备画面复用到不同点位。
  • Input 模板值：由操作员在运行页输入，通过 template.getValue("实例名") 读取。
  • Runtime Variable：当前运行页面内共享的临时状态，适合同页组件联动。
  • 页面 / 弹窗参数：打开目标页时发送，由目标页 GetPageParameter* 读取。
  • PLC Tag：设备数据绑定；不同页面可以读取同一 Tag，但它不是页面传参。

1. 从零制作一个带参数的模板

先在 PowerPoint 中画好设备外观、文字、动画和交互，再把需要一起复用的对象组合成一个组。把每个实例会变化的部分改成尖括号占位符；固定标题、固定颜色和固定结构无需变量化。占位符可以放在普通文本、Tag 字段以及脚本字符串中。脚本里应把它写在字符串字面量内，便于保存模板和导出时稳定替换。

  • 普通文本：设备 <DEVICE_NO>。
  • Tag 路径：<PLC>.<RUN_TAG>。
  • 脚本字符串：ReadTagBoolean("<PLC>.<RUN_TAG>", false)。
  • 位引用：<STATUS_TAG>[3]；位号放在占位符外。
  • 只把确实因实例而变化的内容做成变量，避免 Template Edit 出现大量无意义字段。
// 运行状态与报警状态都随实例变化
var running = ReadTagBoolean("<PLC>.<RUN_TAG>", false);
var alarming = GetAlarmTags([
  "<PLC>.<ALARM_TAG>"
]);

return running && !alarming;

2. 占位符命名和路径写法

变量名用一对尖括号包住。为了团队协作和跨项目稳定，公开模板建议使用简短的 ASCII 大写名称，例如 <PLC>、<DEVICE_NO>、<RUN_TAG>。当前版本也能识别中文变量名，但点号、横杠和空格不能放进变量名内部；Tag 路径应拆成多个变量和固定分隔符。

  • 推荐：<PLC>、<DB_01>、<设备编号>。
  • 正确路径：<PLC>.<RUN_TAG>；错误：<PLC.RUN_TAG>。
  • 正确位引用：<STATUS_TAG>[3]；错误：<STATUS_TAG[3]>。
  • 不使用：<RUN-TAG>、<RUN TAG>。
  • 变量名大小写不同会被视为不同字段；同一含义统一写法。
// 实例填写 PLC=LINE01，RUN_TAG=PUMP01.RUN
ReadTagBoolean("<PLC>.<RUN_TAG>", false)
// 导出后对应 LINE01.PUMP01.RUN

3. 保存模板并检查 Captured variables

选中要复用的对象组，在 Templates 中点击 Save。填写 Template name、Group 和 Sort order 后，重点检查 Captured variables：缺少的变量通常说明源对象中的写法不正确；重复但大小写不同的变量应先回到源对象统一。变量顺序就是以后 Template Edit 的填写顺序，可把 PLC、设备编号和常用 Tag 放在前面。

  • Template name：写清设备或用途，例如 Pump faceplate。
  • Group：按工艺、设备或项目分类，方便后续搜索。
  • Sort order：数值越小，在模板库中越靠前。
  • Captured variables：逐项核对名称、数量和顺序。
  • 保存后从模板库重新插入一份，不要只在模板源文件中验证。

4. 插入实例并填写模板变量

从模板库双击或拖拽插入后，选中模板实例根组并点击 Template Edit。先确认顶部的 Instance、Template、Group，再检查 X、Y、Width、Height，最后逐项填写 Template variables。填写只影响当前实例；复制整个实例时，这组值会随实例一起复制。

  • 不要只选中组内的子图形；Template Edit 需要模板实例根组。
  • 实例值填写替换结果，不要再次加尖括号，例如 PLC 填 LINE01。
  • 普通文本、行为 Tag 和脚本字符串中的同名占位符会使用同一个实例值。
  • 空值可以暂存，但用于 Tag 的变量必须在正式导出前补全。
  • 保存后重新打开 Template Edit，确认值、位置和尺寸都保持不变。
PLC       = LINE01
RUN_TAG   = PUMP01.RUN
ALARM_TAG = PUMP01.ALARM
// <PLC>.<RUN_TAG> -> LINE01.PUMP01.RUN

5. Input 值和跨页面参数怎么用

Input 模板用于运行时输入，不要拿模板占位符代替操作员的临时值。Plain Input 的当前值通过 template.getValue("输入模板实例名") 读取；Runtime Variable 用于当前页多个对象共享；打开新页面或弹窗时，把需要的设备编号、模式或上下文作为页面参数发送，目标页再用 GetPageParameterString / Integer / Double / Boolean 读取。

  • Plain Input：输入暂存在这个 Input 实例中，适合确认后由按钮脚本读取。
  • Runtime Variable：同页临时联动，不保证跨页面保留。
  • PLC Tag 模式：确认后按宿主权限和写入规则提交到设备 Tag。
  • 页面参数：只在打开目标页或弹窗时携带，字段名由发送页和目标页共同约定。
  • 需要完整的打开页与接收示例时，继续阅读“脚本作用域与参数传递”。
// 读取 Input 模板实例
var setpoint = template.getValue("Speed input");

// 目标页面读取调用方传入的参数
var deviceCode = GetPageParameterString("deviceCode", "");
var editMode = GetPageParameterBoolean("editMode", false);

6. 报警模板的显示列与筛选范围

报警模板既要决定显示哪些列，也要限定显示哪些报警。先勾选 Time、Message、Level、PLC、Function Group、Device Group、Signal Group、Tags、Status、Acknowledged 中实际需要的列，再按项目编码填写筛选范围。多个值可用逗号或换行分隔，字段应填编码而不是界面显示名称。

  • Tags：完整 device-code.tag-code，例如 <PLC>.<ALARM_TAG>。
  • PLC codes：只填 device-code，例如 <PLC>。
  • Function groups：device-code.group-code。
  • Device groups：device-code.group-code。
  • Signal groups：device-code.group-code。
  • 留空的筛选维度不额外限制范围；导出后用一条已知活动报警验证。

7. 在模板脚本中判断活动报警

需要让图标、颜色或文字随报警状态变化时，可在行为脚本中使用报警判断方法。它们返回 true / false，表示当前是否存在与给定范围匹配的活动报警；可传数组，也可传逗号或换行分隔的文本。它们用于当前报警状态判断，不用于查询历史或执行确认。

  • GetAlarmTags(values)：按完整 Tag 范围判断。
  • GetAlarmPlcCodes(values)：按 PLC / 设备编码判断。
  • GetAlarmFunctionGroupCodes(values)：按功能组编码判断。
  • GetAlarmDeviceGroupCodes(values)：按设备组编码判断。
  • GetAlarmSignalGroupCodes(values)：按信号组编码判断。
var hasTagAlarm = GetAlarmTags([
  "<PLC>.<ALARM_TAG>"
]);

var hasDeviceAlarm = GetAlarmDeviceGroupCodes([
  "<PLC>.<DEVICE_GROUP>"
]);

return hasTagAlarm || hasDeviceAlarm;

8. 导出前验证与常见错误

正式交付前至少插入两个使用不同实例值的模板，确认它们的文字、Tag、报警范围和交互互不串用。再检查 Input 的保存位置、页面参数字段名和目标页默认值。导出检查提示未解析变量时，应回到对应实例补值或修正源模板，不要用固定文本掩盖问题。

  • 出现未解析的 <变量名>：检查实例是否漏填，以及变量是否位于支持替换的位置。
  • Captured variables 少一项：检查是否把点号、横杠、空格或位号写进变量名。
  • 脚本中没有替换：确认占位符位于字符串字面量内。
  • 跳页后值丢失：确认该值本应使用页面参数，而不是 Runtime Variable。
  • 报警范围不对：核对完整 Tag、PLC 编码和各类 group-code 的字段区别。
  • 模板更新后，重新插入新实例验证；旧实例是否需要替换按项目版本管理决定。
新版 Save as template 界面中的模板名称、分组、排序和 Captured variables
图示 1: 保存模板并确认变量

当前版本的 Save as template：保存前核对名称、分组、排序和 Captured variables 的顺序。

新版 Edit template instance 界面中的位置尺寸和模板变量
图示 2: 填写当前实例变量

Template Edit 只修改当前实例；先确认来源和位置尺寸，再逐项填写变量值。

新版 Alarm 模板编辑界面中的显示列和筛选范围
图示 3: 配置报警模板

选择需要的报警列，并按 Tag、PLC、功能组、设备组或信号组限定显示范围。