模板使用说明 | HQ VISU Designer

模板库支持搜索模板、按模板组查看模板卡片、保存模板、导入模板、导出模板和删除模板。它是项目中的复用资产库，不是一次性暂存区。

• Search：模板多了以后先靠搜索定位
• Save：把当前选中的可复用内容沉淀进库里
• Import / Export：便于模板资产迁移和共享
• Delete：清理已经不用的模板

当一个结构已经稳定、未来会重复使用，而且复制后需要反复调整字段时，就应保存成模板。仍在频繁变化、字段和结构尚未确定的页面，不建议过早模板化。

先在模板库中确认目标模板，再双击或拖拽插入，插入后进入 Template Edit 调整实例尺寸和实例配置。模板插入后不建议先大量复制，再逐个补充配置。

最适合放进模板库的通常是设备卡片、状态块、诊断弹窗、操作弹窗、通用按钮组、输入 + 按键组合区和标准表格区。这些内容复用频率高，结构变化也容易影响多个页面。

保存前先确认选中对象只包含需要长期复用的内容。对象命名、默认文本、Tag 片段、模板变量和图层顺序都应保持清晰；仅用于当前页面的说明、占位标记和辅助对象不应进入模板。

模板名建议直接说明用途，例如“设备状态卡片”“参数输入区”“诊断弹窗”。模板组建议按业务或页面模块划分，例如设备、报警、配方、报表。名称越稳定，后续搜索、替换和团队交接越容易。

模板不是空白结构，它来自已经完成的页面内容。建议先在 PPT 中完成外框、标题、状态块、输入区、按钮区和说明文字，再考虑模板化。模板负责沉淀成熟结构，不用于替代页面结构设计。

模板边界应保持清晰。确实需要一起复用、移动、缩放和维护的对象，才适合放入同一个组。参考线、当前页说明文字、仅当前页需要的提示不应进入模板组。模板本质上是带模板元数据的组，因此分组边界就是模板边界。

• 会一起出现、一起移动、一起维护的对象放进同一组
• 组名应体现用途，避免直接沿用默认对象名
• 只属于当前页的文字、辅助线和说明不应进入模板

保存模板时，先在 PPT 中选中完整对象组，再打开 Template Library 执行 Save。保存范围来自当前选区，不是整页，也不会自动选择部分内容。保存前应确认选区准确。模板名建议直接写用途，例如“泵状态卡片”“设备输入区”“配方弹窗”，避免使用难以识别的默认对象名。

• 保存前先确认只选中了需要复用的对象组
• 模板名应直接说明用途，便于后续搜索
• 如果模板库中有模板组，建议按业务分类保存

模板不是保存后即完成。合格的模板应能够从模板库重新插入页面，并保持结构完整、尺寸合理、默认文本干净。建议保存后立即双击或拖拽插入一次，检查结构、尺寸和默认内容。

• 双击或拖拽将模板重新插回页面
• 检查对象组是否完整
• 检查默认文字、默认大小、默认位置是否合理
• 检查是否包含上一页的残留文字和值

模板插入到页面后，不建议立即连接行为、脚本或 Tag。更可靠的顺序是先打开 Template Edit，调整 X、Y、Width、Height 以及当前实例需要的实例级配置。模板源是原始结构，页面中实际使用的是实例；实例位置和参数未确认时，后续逻辑配置容易返工。

• 先调整 X / Y，确认位置
• 再调整 Width / Height，确认占位
• 再补充实例参数、变量、Tag 或文本
• 确认实例配置后，再继续配置行为和脚本

如果只是当前页这一份位置、尺寸或绑定变量不同，应修改实例；如果所有同类内容都需要一起调整，例如布局变化、字段增加或按钮结构变化，则应回到模板源重新整理。该判断决定本次修改属于当前页面调整，还是复用体系调整。

当前所有模板实例都支持 X、Y、Width、Height。也就是说，不论模板内容是什么，至少都能通过模板编辑器控制它在页面上的位置和占位范围。

模板源决定模板的原始结构、输入项和默认内容；模板实例决定当前页面中的摆放方式、配置内容，以及具体连接的变量或 Tag。模板源提供可复用结构，模板实例提供当前页面的落地参数。

模板变量在配置字段中按 JavaScript 字符串书写。需要使用 `<PLC>`、`<MUBAN>`、`<TITLE>` 这类模板变量时，应写成 `'<PLC>'` 或 `"<PLC>"`；组合点名同样写成 `'<PLC>.<TAG>'` 或 `"<PLC>.<TAG>"`。单引号和双引号都支持，未加引号的 `<PLC>` 不属于支持写法。

• 推荐：'<PLC>' 或 "<PLC>"
• 组合点名：'<PLC>.<TAG>' 或 "<PLC>.<TAG>"
• 不支持：<PLC>、<PLC>.<TAG>
• 导出替换后仍保持合法字符串，例如 '<PLC>' -> 'DK'

如果只是当前页这一个实例位置不同、尺寸不同，就改实例；如果是所有同类模板结构都要变，例如多一列、多一个按钮、字段布局整体改变，就该回模板源调整。

先插入模板，再打开 Template Edit，依次调整 X、Y、Width、Height 和实例级配置。确认实例配置完整后，再继续连接脚本或 Tag。

建议先维护影响范围最大的变量，例如 PLC、设备编码、DB、画面标题，再维护单个对象的 Tag、文本和单位。这样可以先建立实例的主要数据边界，再处理细节字段。

模板变量只替换当前模板实例中声明的占位内容，不会自动改写页面上所有同名文本。需要跨页面或跨多个实例整理变量时，应使用 Batch Replace，并在替换前确认作用范围。

如果只是希望先收集一个输入值，后续再由脚本决定处理方式，优先使用 Plain Input。这个模式不填写 PLC Tag，也不自动写设备；输入框当前值通过 template.getValue("输入模板实例名") 读取。例如实例名为 Input Template，就写 template.getValue("Input Template")。

• 适合先输入、后确认的场景
• 适合需要脚本二次判断的场景
• 适合页面暂存输入，不直接写设备

var recipeName = template.getValue("Input Template");
if (recipeName !== "") {
  WriteTagString("Device.RECIPE", recipeName);
}

如果输入值主要用于页面内联动、模板联动、局部状态切换，而不是直接下发给 PLC，适合使用 Runtime Variable。配置 Runtime Variable 字段时填变量名本身，例如 recipeName 或 selectedPump，不写成 "recipeName"，也不写脚本表达式。

• 适合页面内联动
• 适合局部筛选和局部状态切换
• 适合暂存值，后续再统一处理
• 配置框示例：recipeName，不是 "recipeName"

如果输入框的目标就是 PLC Tag，应使用 PLC Tag 模式。PLC Tag 字段填完整点名本身，例如 Device.TAGNAME，不写成 "Device.TAGNAME"，也不写 ReadTagString("Device.TAGNAME")。模板会按输入值类型走对应写入链。

• 适合设定值和参数值
• 适合明确要写 PLC 的输入项
• 配置框示例：Device.TAGNAME，不是 "Device.TAGNAME"
• 关键操作建议配合确认和权限规则一起考虑

PLC Tag 模式会按输入内容识别数字、布尔或字符串。参数设定类输入建议在页面上同时给出单位、范围和当前值；需要严格限制上下限时，应在输入前后结合脚本或写值确认规则处理。

输入模板只负责收集或提交一个值。需要二次确认、权限判断、原因填写或组合写入时，建议让输入模板先保存值，再由按钮行为、Keypad 的 OK 或 Click Script 统一触发后续动作。

固定点名可以按字段原有格式填写；只要点名中包含模板变量，就应写成字符串。Runtime Variable 字段填运行时变量名本身，例如 recipeName；脚本方法参数按 JavaScript 字符串规则加引号，例如 template.getValue("Input Template")。

• 固定 PLC Tag：Device.TAGNAME
• 模板 PLC Tag：'<PLC>.TAGNAME' 或 "<PLC>.TAGNAME"
• Runtime Variable：recipeName
• 脚本读取输入框：template.getValue("Input Template")
• 脚本读取 Tag：ReadTagString("Device.TAGNAME", "")

如果用户输入后需要再确认一次，就让输入模板先保存值，由按钮、keypad 的 OK 或脚本统一触发；如果输入完成就应该立刻提交，再考虑直接绑定写入。对工业项目来说，越关键的写入越不建议“输入即提交”。

keypad 模板使用前，需要明确关联的 input 模板。目标输入模板未配置时，数字键、Back、Clear 和 OK 都没有明确落点。Target Input Name 应填写当前页输入模板实例名，并与实例名称保持一致。

数字键负责追加字符；Back 删除最后一个字符；Clear 清空当前输入；OK 会把当前值通过目标输入模板提交。keypad 可作为可复用的输入动作面板使用。

当目标输入模板为 Plain Input 时，Keypad 的 OK 通常只完成目标输入模板的提交动作，后续可由脚本读取 template.getValue("输入模板实例名") 再决定是否写 Tag。适合参数输入、配方名输入和需要统一确认的操作。

当目标输入模板为 PLC Tag 时，Keypad 的 OK 会通过目标输入模板进入写入链。此类配置适合明确的设定值输入，关键参数建议配合确认、权限和范围提示一起使用。

如果输入值会直接影响设备，建议把输入和确认分成两步，让用户先在输入模板中看到值，再通过 OK 或单独确认按钮提交。这样比边输边写更安全，也更符合现场操作习惯。

数值设定、配方输入、密码输入、工艺参数设定、批次号输入，这类需要标准数字输入流程的场景都很适合 keypad 模板。

最常用的是 Table Name、Table Text ID、Headers、Header Text IDs、Rows。Headers 控表头显示，Rows 控内容，Text ID 则适合和多语言或统一文案体系衔接。

直接写数组时，应按 JavaScript 数组写法填写，数组中的文字需要加引号；引用页面脚本里已经准备好的变量或函数时，只填名称本身，不加引号，也不要加括号。

• 直接表头：['设备', '状态']
• 直接行：[['Pump 1', 'Running'], ['Pump 2', 'Stop']]
• 引用变量：Rows 填 tableRows
• 引用函数：Rows 填 buildTableRows，不写 buildTableRows()

Rows 既可以直接写数组，也可以写变量名，还可以写函数名。推荐把稍复杂的数据放在 Page Script 里准备好，然后在 Rows 配置框里填变量名 tableRows。

• 直接数组适合快速静态表格
• 变量名适合页面脚本提前准备数据
• 函数名适合需要运行时重新计算表格数据的场景

var tableRows = [
  ["Pump 1", "Running"],
  ["Pump 2", "Stop"]
];

// Table 模板的 Rows 配置框填：tableRows

可以。推荐在 Page Script 里调用 ReadTagString / ReadTagInteger / ReadTagDouble，把结果整理成二维数组，再让 table 模板按变量名渲染。这样表格层只负责显示，脚本负责读 Tag 和组织数据。

var tableRows = [
  ["Pump 1", ReadTagString("Device.TAGNAME", "")],
  ["Pump 2", ReadTagString("Device.TAGNAME_2", "")]
];

// Table 模板的 Rows 配置框填：tableRows

当行数据来自后端、脚本或聚合结果时，建议由运行端或页面脚本整理为 JSON Tag，再在 Page Script 中使用 ReadTagJson("Device.ReportRows", []) 读取，最后把结果转换为 Table 需要的二维数组。

Headers 适合直接声明当前表头；Header Text IDs 适合接入统一语言键。项目需要多语言时，优先维护稳定 Text ID，再把默认表头作为兜底显示。

Rows 配置框只适合放数组、变量名或函数名；较复杂的 Tag 读取、判断和格式化逻辑应放在 Page Script 中，保持表格配置清晰。

当页面需要维护多行、多列内容，且这些内容未来会随配置、Tag 或脚本变化时，表格模板可以显著降低维护成本。它特别适合设备清单、诊断列表、参数表和状态列表。

controlName 是输入模板实例名或控件名，要和页面里的名字完全一致，包括空格和大小写。比如输入模板实例叫 Input Template，就写 template.getValue("Input Template")。这是脚本代码，名字作为字符串参数传入，所以这里必须加引号。

var value = template.getValue("Input Template");
qtedit.setComponentText("InputPreview", value);

它读取的是输入模板当前可见值，非常适合操作确认、二次校验、组合写值、配方提交和脚本里自己决定何时写 Tag。它特别适合 Plain Input 模式，因为 Plain Input 本身只负责收值。

var setpointText = template.getValue("Input Template");
var setpoint = Number(setpointText);

if (!Number.isNaN(setpoint)) {
  WriteTagDouble("Device.SETPOINT", setpoint);
}

当输入模板只是采集值、不直接写 Tag，或需要先校验、转换、提交，或需要组合多个输入框值时，template.getValue() 就很关键。

如果输入模板已经直接绑定 PLC Tag，且业务上不需要再做脚本判断，那很多时候不需要额外在脚本里读值。把事情交给配置完成，通常更可靠。

脚本里只使用手册写明的方法。不要推测模板底层结构，也不要将模板作为可任意遍历的普通对象处理。这样后续升级和交接更可控。