所属产品: Mingcedar Studio DESIGNER

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

制作可复用模板，配置占位符、实例值、Input、报警和跨页参数。

首次发布 2026-10-25T12:48:42.611738836Z 最近更新 2026-10-26T19:56:55.624489526Z

<div class="manual-doc-article manual-doc-article-section"><h2 id="template-authoring-and-parameterization">模板: 模板制作与传参：从可复用组件到页面通信</h2>

制作可复用模板，配置占位符、实例值、Input、报警和跨页参数。

<h3 id="template-authoring-and-parameterization-item-1">参数类型与适用场景</h3>

<p>按确定值的时机选择机制：实例设备地址用模板变量；运行页临时输入用 Input 或 Runtime Variable；打开页面或弹窗时的上下文用页面参数。</p>

<ul>

<li>模板实例变量：插入模板后填写，例如 <PLC>、<RUN_TAG>；适合同一设备画面复用到不同点位。</li>

<li>Input 模板值：由操作员在运行页输入，通过 template.getValue("实例名") 读取。</li>

<li>Runtime Variable：当前运行页面内共享的临时状态，适合同页组件联动。</li>

<li>页面 / 弹窗参数：打开目标页时发送，由目标页 GetPageParameter* 读取。</li>

<li>PLC Tag：设备数据绑定；不同页面可以读取同一 Tag，但它不是页面传参。</li>

</ul>

<li><a href="/ppt/manual/design-reuse-guide/">动手练习：复用方式与参数</a></li>

</ul>

</article>

<h3 id="template-authoring-and-parameterization-item-2">1. 从零制作一个带参数的模板</h3>

<p>绘制外观、文字并配置行为，将需共同复用的对象组合。把实例差异改为尖括号占位符，固定内容保留。占位符可用于文本、Tag 字段和脚本字符串；脚本中须放在字符串字面量内。</p>

<ul>

<li>脚本字符串：ReadTagBoolean("<PLC>.<RUN_TAG>", false)。</li>

<li>位引用：<STATUS_TAG>[3]；位号放在占位符外。</li>

<li>只把确实因实例而变化的内容做成变量，避免 Template Edit 出现大量无意义字段。</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar"><span>JavaScript</span><span class="manual-code-tools"><small>JavaScript</small><button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button><span class="manual-code-status" role="status"></span></span></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><span class="line"><span style="color:#6A737D">// 运行状态与报警状态都随实例变化</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> running </span><span style="color:#D73A49">=</span><span style="color:#6F42C1"> ReadTagBoolean</span><span style="color:#24292E">(</span><span style="color:#032F62">"<PLC>.<RUN_TAG>"</span><span style="color:#24292E">, </span><span style="color:#005CC5">false</span><span style="color:#24292E">);</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> alarming </span><span style="color:#D73A49">=</span><span style="color:#6F42C1"> GetAlarmTags</span><span style="color:#24292E">([</span></span>

<span class="line"><span style="color:#D73A49">return</span><span style="color:#24292E"> running </span><span style="color:#D73A49">&&</span><span style="color:#D73A49"> !</span><span style="color:#24292E">alarming;</span></span></code></pre></div>

</article>

<h3 id="template-authoring-and-parameterization-item-3">2. 占位符命名和路径写法</h3>

<p>变量名用一对尖括号包住。共享模板建议使用简短的 ASCII 大写名称，例如 <PLC>、<DEVICE_NO>、<RUN_TAG>。变量名也可使用中文，但不能包含点号、横杠或空格；Tag 路径应由变量与固定分隔符组成。</p>

<ul>

<li>正确位引用：<STATUS_TAG>[3]；错误：<STATUS_TAG[3]>。</li>

<li>变量名大小写不同会被视为不同字段；同一含义统一写法。</li>

</ul>

<span class="line"><span>ReadTagBoolean("<PLC>.<RUN_TAG>", false)</span></span>

<span class="line"><span>// 导出后对应 LINE01.PUMP01.RUN</span></span></code></pre></div>

</article>

<h3 id="template-authoring-and-parameterization-item-4">3. 保存模板并检查 Captured variables</h3>

<p>选中对象组，打开 Templates → Library → Save selection，填写名称、分组和排序。核对 Captured variables：缺失时修正源对象写法，大小写重复时统一名称；列表顺序决定 Template Edit 填写顺序。</p>

<ul>

<li>Template name：写清设备或用途，例如 Pump faceplate。</li>

<li>Group：按工艺、设备或项目分类，方便后续搜索。</li>

<li>Sort order：数值越小，在模板库中越靠前。</li>

<li>Captured variables：逐项核对名称、数量和顺序。</li>

<li>保存后从模板库重新插入一份，不要只在模板源文件中验证。</li>

</ul>

</article>

<h3 id="template-authoring-and-parameterization-item-5">4. 插入实例并填写模板变量</h3>

<p>插入模板后，选中实例根组，打开 Templates → Edit Instance。核对 Instance、Template、Group 和位置尺寸，再填 Template variables。修改仅影响当前实例；复制实例会同时复制这些值。</p>

<ul>

<li>不要只选中组内的子图形；Template Edit 需要模板实例根组。</li>

<li>实例值填写替换结果，不要再次加尖括号，例如 PLC 填 LINE01。</li>

<li>普通文本、行为 Tag 和脚本字符串中的同名占位符会使用同一个实例值。</li>

<li>空值可以暂存，但用于 Tag 的变量必须在正式导出前补全。</li>

<li>保存后重新打开 Template Edit，确认值、位置和尺寸都保持不变。</li>

</ul>

<span class="line"><span>ALARM_TAG = PUMP01.ALARM</span></span>

</article>

<h3 id="template-authoring-and-parameterization-item-6">5. Input 取值与页面参数</h3>

<p>运行时输入使用 Input，不使用模板占位符。Plain Input 用 template.getValue("输入模板实例名") 读取；Runtime Variable 用于同页共享。跨页传递设备编号、模式等上下文时使用页面参数，目标页用 GetPageParameter 读取，再显式转换数字或布尔值。</p>

<ul>

<li>Plain Input：输入暂存在这个 Input 实例中，适合确认后由按钮脚本读取。</li>

<li>Runtime Variable：同页临时联动，不保证跨页面保留。</li>

<li>PLC Tag 模式：确认后按宿主权限和写入规则提交到设备 Tag。</li>

<li>页面参数：只在打开目标页或弹窗时携带，字段名由发送页和目标页共同约定。</li>

<li>需要完整的打开页与接收示例时，继续阅读“脚本作用域与参数传递”。</li>

</ul>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> setpoint </span><span style="color:#D73A49">=</span><span style="color:#24292E"> template.</span><span style="color:#6F42C1">getValue</span><span style="color:#24292E">(</span><span style="color:#032F62">"Speed input"</span><span style="color:#24292E">);</span></span>

<span class="line"><span style="color:#6A737D">// 目标页面读取调用方传入的参数</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> deviceCode </span><span style="color:#D73A49">=</span><span style="color:#6F42C1"> GetPageParameter</span><span style="color:#24292E">(</span><span style="color:#032F62">"deviceCode"</span><span style="color:#24292E">, </span><span style="color:#032F62">""</span><span style="color:#24292E">);</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> editMode </span><span style="color:#D73A49">=</span><span style="color:#6F42C1"> GetPageParameter</span><span style="color:#24292E">(</span><span style="color:#032F62">"editMode"</span><span style="color:#24292E">, </span><span style="color:#032F62">"false"</span><span style="color:#24292E">) </span><span style="color:#D73A49">===</span><span style="color:#032F62"> "true"</span><span style="color:#24292E">;</span></span></code></pre></div>

</article>

<h3 id="template-authoring-and-parameterization-item-7">6. 报警模板的显示列与筛选范围</h3>

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

<ul>

<li>Tags：完整 device-code.tag-code，例如 <PLC>.<ALARM_TAG>。</li>

<li>PLC codes：只填 device-code，例如 <PLC>。</li>

<li>Function groups：device-code.group-code。</li>

<li>Device groups：device-code.group-code。</li>

<li>Signal groups：device-code.group-code。</li>

<li>留空的筛选维度不额外限制范围；导出后用一条已知活动报警验证。</li>

</ul>

</article>

<h3 id="template-authoring-and-parameterization-item-8">7. 在模板脚本中判断活动报警</h3>

<p>报警判断方法返回 true / false，表示是否存在匹配范围的活动报警，可驱动图标、颜色或文字。参数接受数组或逗号、换行分隔文本；不查询历史或执行确认。</p>

<ul>

<li>GetAlarmTags(values)：按完整 Tag 范围判断。</li>

<li>GetAlarmPlcCodes(values)：按 PLC / 设备编码判断。</li>

<li>GetAlarmFunctionGroupCodes(values)：按功能组编码判断。</li>

<li>GetAlarmDeviceGroupCodes(values)：按设备组编码判断。</li>

<li>GetAlarmSignalGroupCodes(values)：按信号组编码判断。</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar"><span>JavaScript</span><span class="manual-code-tools"><small>JavaScript</small><button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button><span class="manual-code-status" role="status"></span></span></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> hasTagAlarm </span><span style="color:#D73A49">=</span><span style="color:#6F42C1"> GetAlarmTags</span><span style="color:#24292E">([</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> hasDeviceAlarm </span><span style="color:#D73A49">=</span><span style="color:#6F42C1"> GetAlarmDeviceGroupCodes</span><span style="color:#24292E">([</span></span>

<span class="line"><span style="color:#D73A49">return</span><span style="color:#24292E"> hasTagAlarm </span><span style="color:#D73A49">||</span><span style="color:#24292E"> hasDeviceAlarm;</span></span></code></pre></div>

</article>

<h3 id="template-authoring-and-parameterization-item-9">8. 导出前验证与常见错误</h3>

<p>至少用两个不同实例值验证文字、Tag、报警范围和交互互不串用，并检查 Input 保存位置、参数名和目标页默认值。未解析变量须补值或修正源模板，不能用固定文本掩盖。</p>

<ul>

<li>出现未解析的 <变量名>：检查实例是否漏填，以及变量是否位于支持替换的位置。</li>

<li>Captured variables 少一项：检查是否把点号、横杠、空格或位号写进变量名。</li>

<li>脚本中没有替换：确认占位符位于字符串字面量内。</li>

<li>跳页后值丢失：确认该值本应使用页面参数，而不是 Runtime Variable。</li>

<li>报警范围不对：核对完整 Tag、PLC 编码和各类 group-code 的字段区别。</li>

<li>模板更新后，重新插入新实例验证；旧实例是否需要替换按项目版本管理决定。</li>

</ul>

</article>

</div>

<strong>图示 1: 保存模板并确认变量</strong>

<p>保存模板前，核对名称、分组、排序和 Captured variables 的顺序。</p>

</figcaption>

</figure>

<strong>图示 2: 填写当前实例参数</strong>

<p>Template Edit 只修改当前实例；先确认来源和位置尺寸，再逐项填写模板参数。</p>

</figcaption>

</figure>

<strong>图示 3: 配置报警模板</strong>

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

</figcaption>

</figure>

</div>