模板使用说明 | Mingcedar Studio

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

• Search：按模板名称或分类搜索定位
• Save：将选中的可复用内容保存到模板库
• Import / Export：便于模板资产迁移和共享
• Delete：清理已经不用的模板

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

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

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

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

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

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

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

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

选中完整对象组，打开 MX Design → Templates → Library，点击 Save selection。核对选区并填写模板名，如“泵状态卡片”。

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

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

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

选中实例根组，打开 MX Design → Templates → Edit Instance。核对来源，调整 X、Y、Width、Height 和实例参数，再配置行为与脚本。

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

仅当前实例的位置、尺寸或绑定不同：修改实例。同类模板都需调整布局、字段或按钮：修改模板源。

模板实例支持 X、Y、Width、Height，可在模板编辑器中调整实例在页面上的位置和尺寸。

模板源保存可复用的结构、输入项和默认内容；模板实例保存当前页面的位置、尺寸、参数值以及变量或 Tag 绑定。

Template variables 填替换值，如 PLC_LINE01。目标字段可直接用 <PLC>.PUMP01.SPEED_SETPOINT；JavaScript 字符串才加引号，如 ReadTagDouble("<PLC>.PUMP01.SPEED", 0)。动态名称使用 = 表达式。

• 实例参数：PLC 填 PLC_LINE01，不再次添加尖括号。
• 固定 Tag 目标：<PLC>.PUMP01.SPEED_SETPOINT。
• 动态目标：="<PLC>." + selectedPumpCode + ".SPEED_SETPOINT"。
• 脚本字符串：ReadTagDouble("<PLC>.PUMP01.SPEED", 0)。

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

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

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

模板参数仅替换当前实例中的对应占位符。Batch Replace 的范围为当前选区或当前页面；需要修改其他页面时分别执行，并检查预览。不要将其视为自动覆盖整个演示文稿的替换操作。

Plain Input 暂存输入，不填写 PLC Tag，也不自动写设备。脚本通过 template.getValue("Input Template") 读取，参数为输入实例名。

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

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

Runtime Variable 保存当前页输入。固定目标填 speedSetpointDraft，不加引号；动态目标填 =selectedVariableName，须返回有效变量名。Set Variable on Click 的 Variable 仍填赋值目标名，两者规则不同。

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

PLC Tag 固定目标填 PLC_LINE01.PUMP01.SPEED_SETPOINT，模板目标填 <PLC>.PUMP01.SPEED_SETPOINT，动态目标填 =selectedSetpointTag 并返回完整名称。此字段不填读取或写入调用；计算 Tag 不可写入。

• 适合设定值和参数值
• 适合明确要写 PLC 的输入项
• 固定目标：PLC_LINE01.PUMP01.SPEED_SETPOINT；动态目标：=selectedSetpointTag。
• 关键操作建议配合确认和权限规则一起考虑

PLC Tag 模式识别数字、布尔和字符串。自定义上下限须用 Plain Input 配合按钮校验后写入；单位、范围提示和确认框不执行校验。

范围校验、原因填写和组合写入由 Plain Input 配合按钮或 Click Script 完成。Keypad OK 不会调用另一按钮的校验。

Input 固定目标、Runtime Variable 名称和模板占位符不加引号；= 表示求值后使用返回名称。JavaScript 名称参数加引号，如 template.getValue("SpeedSetpointInput")。

• 固定 PLC Tag：PLC_LINE01.PUMP01.SPEED_SETPOINT。
• 模板 PLC Tag：<PLC>.PUMP01.SPEED_SETPOINT。
• Runtime Variable：speedSetpointDraft；动态变量名：=selectedVariableName。
• 脚本读取输入框：template.getValue("SpeedSetpointInput")。
• 脚本读取 Tag：ReadTagDouble("PLC_LINE01.PUMP01.SPEED", 0)。

需先校验再写入时，使用 Plain Input 和独立按钮。PLC Tag Input 按自身规则提交，另一按钮不能拦截 Keypad OK。

Target Input Name 填当前页 Input 实例名。未关联有效实例时，数字键、Back、Clear 和 OK 无目标。

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

Plain Input 的 Keypad OK 仅提交输入；脚本再用 template.getValue("输入模板实例名") 读取，校验后决定是否写 Tag。

PLC Tag Input 即使设为 External，Keypad OK 仍会提交。External 仅关闭自动提交；自定义范围校验应使用 Plain Input 和校验按钮。

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

数值设定、数字配方号、工艺参数设定、数字批次号适合 keypad 模板。当前输入模板使用普通文本输入，不提供密码掩码，不应用它收集密码。

Table name 为显示标题，Table text ID 为标题翻译键，均非脚本查找名。Headers 为列标题，Header text IDs 为列标题翻译键，Rows 为二维数组。

Headers、Rows 接受数组、Page Script 数组变量或返回数组的函数，如 =buildPumpRows()。固定文字加引号；Tag 名称字符串不能直接作为行数据。

• 直接表头：['设备', '状态']
• 直接行：[['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

把 Tag 读取放进 Page Script 函数，每次表格求值时返回最新二维数组。Rows 使用函数名或显式 = 调用。仅在页面脚本顶层读取一次并存入数组，不会自动重新读取 Tag。

function buildTableRows() {
  return [
    ["Pump 1", ReadTagString("PLC_LINE01.PUMP01.STATUS_TEXT", "")],
    ["Pump 2", ReadTagString("PLC_LINE01.PUMP02.STATUS_TEXT", "")]
  ];
}

// Table 模板的 Rows 配置框填：buildTableRows
// 或者：=buildTableRows()

后端或聚合数据可写入 JSON Tag。Page Script 用 ReadTagJson("PLC_LINE01.REPORT01.ROWS", []) 读取，再转换为 Table 所需二维数组。

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

Rows 接受数组、数组变量、函数或 =buildPumpRows() 表达式。复杂整理放在 Page Script 函数中；一次读取的数组不会持续更新。

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

controlName 是当前页 Input 实例名或控件名，不是 Tag 名。匹配不区分大小写，名称应唯一。脚本参数加引号，如 template.getValue("Input Template")。

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

先排除空白，再检查数字是否有限且在业务范围内：Number('') 为 0，Number.isNaN() 不能排除 Infinity。示例范围为 0～100，须按项目修改。

var setpointText = template.getValue("Input Template");
var trimmed = String(setpointText == null ? "" : setpointText).trim();
var setpoint = Number(trimmed);

if (trimmed !== "" && Number.isFinite(setpoint) && setpoint >= 0 && setpoint <= 100) {
  WriteTagDouble("PLC_LINE01.PUMP01.SETPOINT", setpoint);
}

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

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

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