所属产品: Mingcedar Studio DESIGNER

变量、Tag 与模板参数：字段填写规则 | Mingcedar Studio

先确认字段需要 Tag 名称、变量名称、数值还是文本。等号前缀 = 是部分配置字段的表达式标记，不是通用脚本语法，也不会自动授予 Tag 访问权限。

首次发布 2026-10-25T12:48:42.617815547Z 最近更新 2026-10-25T12:48:42.617814796Z

<div class="manual-doc-article manual-doc-article-section"><h2 id="variables-tags-template-expressions">数据绑定: 变量、Tag 与模板参数：字段填写规则</h2>

先确认字段需要 Tag 名称、变量名称、数值还是文本。等号前缀 = 是部分配置字段的表达式标记，不是通用脚本语法，也不会自动授予 Tag 访问权限。

<h3 id="variables-tags-template-expressions-item-1">1. 区分 Tag 名称、运行时变量和模板参数</h3>

<p>Tag 由 Mingcedar 提供数据；运行时变量保存当前页面的状态；模板参数在实例配置阶段替换占位符。保存 Tag 名称的变量仍是字符串，读取方法才返回 Tag 的值。本文示例使用产线 PLC_LINE01、设备 PUMP01 和 TANK01；应替换为项目中已经配置的名称。</p>

<ul>

<li>Tag 完整名称：<code>PLC_LINE01.PUMP01.SPEED</code>。</li>

<li>计算 Tag 名称：<code>Line01TotalFlow</code>，按宿主保存的名称填写。</li>

<li>运行时变量：<code>selectedSpeedTag</code> 保存地址字符串，<code>speedValue</code> 保存数值。</li>

<li>模板占位符：<code><PLC></code>、<code><PUMP_CODE></code>，在实例中填写后替换。</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">// Page Script：保存目标名称</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> selectedSpeedTag </span><span style="color:#D73A49">=</span><span style="color:#032F62"> "PLC_LINE01.PUMP01.SPEED"</span><span style="color:#24292E">;</span></span>

<span class="line"><span style="color:#6A737D">// 行为 Setup Script：按行为求值周期读取当前值</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> speedValue </span><span style="color:#D73A49">=</span><span style="color:#6F42C1"> ReadTagDouble</span><span style="color:#24292E">(selectedSpeedTag, </span><span style="color:#005CC5">0</span><span style="color:#24292E">);</span></span></code></pre></div>

</article>

<h3 id="variables-tags-template-expressions-item-2">2. Tag Text 与写入行为的目标字段</h3>

<p>Tag Text 的 Target tag，以及 Write Tag、Write Tag Bit 的 Target Tag，填写读取或写入的目标名称。完整固定名称可直接填写；地址字符串变量可填变量名。访问对象属性或需要计算地址时，使用 = 明确声明表达式。控件已经负责读写，目标字段无需再调用 ReadTag 或 WriteTag。</p>

<ul>

<li>固定目标：<code>PLC_LINE01.PUMP01.SPEED</code>。</li>

<li>地址变量：<code>selectedSpeedTag</code>；该变量必须已定义并返回字符串。</li>

<li>对象属性：<code>=bindingConfig.speedTag</code>，避免与固定 Tag 路径混淆。</li>

<li>Write Tag Bit 填父 Tag 名称，并在 Bit Index 中单独填写 0 到 31。</li>

</ul>

</article>

<h3 id="variables-tags-template-expressions-item-3">3. Input 和图表中的 = 表达式</h3>

<p>Input 的 PLC Tag 字段，以及图表各系列的 Tag、Gauge 的 Tag 和 JSON Tag，直接填写固定名称时按名称使用。需要由页面变量决定名称时，填写 =selectedSpeedTag。此处表达式应返回 Tag 名称字符串，不能返回 Tag 当前数值或 JSON 对象。</p>

<ul>

<li>Input 固定目标：<code>PLC_LINE01.PUMP01.SPEED_SETPOINT</code>。</li>

<li>Input 动态目标：<code>=selectedSetpointTag</code>。</li>

<li>图表动态目标：<code>=selectedSpeedTag</code>。</li>

<li>JSON Tag：<code>PLC_LINE01.REPORT01.CHART_DATA</code>；动态名称可填 <code>=selectedJsonTag</code>。</li>

</ul>

</article>

<h3 id="variables-tags-template-expressions-item-4">4. 变量名字段与数值字段</h3>

<p>Input 的 Runtime Variable 模式填写待写入的变量名，例如 speedSetpointDraft；动态变量名可填写 =selectedVariableName，表达式必须返回有效变量名字符串。Set Variable on Click 的 Variable 字段填写赋值目标名称，写入内容放在 Value 中。</p>

<ul>

<li>固定变量名不加引号：<code>speedSetpointDraft</code>。</li>

<li>Input 动态变量名：页面先定义 <code>var selectedVariableName = "speedSetpointDraft";</code>，字段填 <code>=selectedVariableName</code>。</li>

<li>Value 或 Condition 是表达式字段，直接填写 <code>speedValue</code>、<code>speedValue > 1200</code> 等表达式。</li>

<li>在 JavaScript 中使用 <code>ReadTagDouble(selectedSpeedTag, 0)</code>；不要把 <code>"=selectedSpeedTag"</code> 作为 API 的名称参数。</li>

</ul>

</article>

<h3 id="variables-tags-template-expressions-item-5">5. 固定文本与表格数据</h3>

<p>Table 的 Rows 和 Headers 等数据字段可以使用数组、页面数组变量或返回数组的函数。= 可明确要求求值；普通标题与变量同名时，可用引号明确表示文字。表格的数组数据与 JSON Chart 的 Tag 名称是不同类型。</p>

<ul>

<li>Headers：<code>["设备编号", "运行状态"]</code>。</li>

<li>动态行数据：<code>pumpRows</code> 或 <code>=buildPumpRows()</code>，结果应为数组。</li>

<li>固定标题：<code>"泵站运行记录"</code>。</li>

</ul>

</article>

<h3 id="variables-tags-template-expressions-item-6">6. 模板参数与页面变量同时使用</h3>

<p>模板参数 PLC 填 PLC_LINE01，Page Script 定义设备编码。模板在设计阶段替换 <PLC>，运行时再读取页面变量，最后得到 Tag 名称。内置模板的表达式使用 Page Script 中的变量，不能依赖其他行为的 Setup Script 局部变量。以下示例按注释分别填写到对应位置，含 = 的行仅用于配置字段，不作为 JavaScript 语句粘贴。</p>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> selectedPumpCode </span><span style="color:#D73A49">=</span><span style="color:#032F62"> "PUMP01"</span><span style="color:#24292E">;</span></span>

<span class="line"><span style="color:#6A737D">// Input 或图表的 Tag 字段</span></span>

<span class="line"><span style="color:#D73A49">=</span><span style="color:#032F62">"<PLC>."</span><span style="color:#D73A49"> +</span><span style="color:#24292E"> selectedPumpCode </span><span style="color:#D73A49">+</span><span style="color:#032F62"> ".SPEED"</span></span>

<span class="line"><span style="color:#6A737D">// Script Text 的 Setup Script</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> speedTagName </span><span style="color:#D73A49">=</span><span style="color:#032F62"> "<PLC>."</span><span style="color:#D73A49"> +</span><span style="color:#24292E"> selectedPumpCode </span><span style="color:#D73A49">+</span><span style="color:#032F62"> ".SPEED"</span><span style="color:#24292E">;</span></span>

<span class="line"><span style="color:#D73A49">var</span><span style="color:#24292E"> speedValue </span><span style="color:#D73A49">=</span><span style="color:#6F42C1"> ReadTagDouble</span><span style="color:#24292E">(speedTagName, </span><span style="color:#005CC5">0</span><span style="color:#24292E">);</span></span>

<span class="line"><span style="color:#6A737D">// Script Text 的 Display Text</span></span>

<span class="line"><span style="color:#24292E">speedValue.</span><span style="color:#6F42C1">toFixed</span><span style="color:#24292E">(</span><span style="color:#005CC5">0</span><span style="color:#24292E">) </span><span style="color:#D73A49">+</span><span style="color:#032F62"> " rpm"</span></span></code></pre></div>

</article>

<h3 id="variables-tags-template-expressions-item-7">7. 动态目标与页面访问范围</h3>

<p>目标由变量决定时，仍需符合导出检查和 Mingcedar 的读写权限。导出工具无法确定动态写入目标时，应在 Page Script 使用 HQVISU_DECLARE_TAGS 声明与表达式对应的有限候选名称，并保证它们在宿主中存在且获准访问。声明不会绕过宿主权限。以下示例按注释分别填写到对应位置，含 = 的行仅用于配置字段，不作为 JavaScript 语句粘贴。</p>

<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"> selectedSetpointTag </span><span style="color:#D73A49">=</span><span style="color:#032F62"> "PLC_LINE01.PUMP01.SPEED_SETPOINT"</span><span style="color:#24292E">;</span></span>

<span class="line"><span style="color:#6F42C1">HQVISU_DECLARE_TAGS</span><span style="color:#24292E">({</span></span>

<span class="line"><span style="color:#24292E"> expression: </span><span style="color:#032F62">"selectedSetpointTag"</span><span style="color:#24292E">,</span></span>

<span class="line"><span style="color:#24292E"> read: [</span><span style="color:#032F62">"PLC_LINE01.PUMP01.SPEED_SETPOINT"</span><span style="color:#24292E">, </span><span style="color:#032F62">"PLC_LINE01.PUMP02.SPEED_SETPOINT"</span><span style="color:#24292E">],</span></span>

<span class="line"><span style="color:#24292E"> write: [</span><span style="color:#032F62">"PLC_LINE01.PUMP01.SPEED_SETPOINT"</span><span style="color:#24292E">, </span><span style="color:#032F62">"PLC_LINE01.PUMP02.SPEED_SETPOINT"</span><span style="color:#24292E">]</span></span>

<span class="line"><span style="color:#6A737D">// Input 的 PLC Tag 字段</span></span>

<span class="line"><span style="color:#D73A49">=</span><span style="color:#24292E">selectedSetpointTag</span></span></code></pre></div>

</article>

<h3 id="variables-tags-template-expressions-item-8">8. 求值失败与目标切换</h3>

<p>显式表达式求值失败、返回非字符串或仍包含未替换占位符时，不会将表达式原文作为另一个 Tag 目标。先检查变量作用域、返回类型、模板参数和名称大小写。</p>

<ul>

<li>Input 的目标或绑定模式改变后，旧目标尚未提交的输入会被取消；请按新目标重新输入。</li>

<li>已经发送的写入请求不会因随后切换目标而撤回。</li>

<li>图表动态目标改变时，实时曲线清除旧目标样本，避免混合不同来源。</li>

<li>运行时变量属于当前页面；跨页面传递上下文使用页面参数。</li>

</ul>

</article>

</div>