所属产品: Mingcedar Studio DESIGNER
动画字段支持哪些写法 | Mingcedar Studio
动画字段分成数值表达式、布尔表达式、颜色值和模板变量。先分清字段类型，再填写表达式，后面的参数才容易稳定。
<section id="animation-syntax" class="docs-block docs-block-intro docs-block-current"> <span class="section-kicker">语法</span> <h2>动画字段支持哪些写法</h2> <p>动画字段分成数值表达式、布尔表达式、颜色值和模板变量。先分清字段类型，再填写表达式，后面的参数才容易稳定。</p> <div class="docs-detail-list"> <article id="animation-syntax-item-1" class="docs-detail-row"> <strong>数值表达式</strong> <p>Move、Rotate、Scale 的输入值、位移、角度和缩放比例都可以写数值表达式。表达式必须能立即算出数字，不能直接放入异步请求。</p> <ul> <li>固定数值：120</li><li>Tag 数值：ReadTagDouble("<PLC>.<TAG>", 0)</li><li>对象尺寸：shape.width、shape.height</li><li>计算表达式：shape.width * 2、shape.height * 0.5</li> </ul> <pre class="docs-code-block"><code>ReadTagDouble("<PLC>.<TAG>", 0)
shape.width
shape.height * 0.5</code></pre> </article><article id="animation-syntax-item-2" class="docs-detail-row"> <strong>Setup Script 与结果字段的分工</strong> <p>颜色和文本行为通过 Setup Script 准备数据，再由输出表达式返回结果。Fill color / Border color 对应旧名 Fill / Stroke。几何编辑器没有 Setup Script，直接使用读取方法或 Page Script 函数。</p> <ul> <li>Setup Script：准备变量和函数</li><li>Condition：返回布尔值</li><li>Display Text / Fill color / Border color：返回字符串</li><li>Source value / Angle / Offset / Scale：返回数字</li><li>Visibility：返回布尔值</li> </ul> <pre class="docs-code-block"><code>// Setup Script
var running = ReadTagBoolean("<PLC>.<RUN_TAG>", false);
var color = running ? "#22C55E" : "#64748B";
// Script Color / Fill color
color</code></pre> </article><article id="animation-syntax-item-3" class="docs-detail-row"> <strong>布尔表达式</strong> <p>State Color、Blink Color 的 Condition 和 Script Color 的 Visibility 需要布尔结果。可直接读取布尔 Tag，或通过比较及组合条件得到 true / false。</p> <ul> <li>二值 Tag：ReadTagBoolean("<PLC>.<TAG>", false)</li><li>状态码比较：state === 1</li><li>组合条件：running === true && alarm === false</li> </ul> <pre class="docs-code-block"><code>var running = ReadTagBoolean("<PLC>.<RUN_TAG>", false);
var alarm = ReadTagBoolean("<PLC>.<ALARM_TAG>", false);
running === true && alarm === false</code></pre> </article><article id="animation-syntax-item-4" class="docs-detail-row"> <strong>颜色值</strong> <p>颜色值可使用十六进制格式。普通颜色行为通过颜色选择器维护；Script Color 的 Fill color 和 Border color 填写返回颜色字符串的表达式。</p> <ul> <li>固定颜色："#22C55E"</li><li>脚本颜色：state === 1 ? "#22C55E" : "#EF4444"</li><li>模板颜色："<FILL_COLOR>"</li> </ul> <pre class="docs-code-block"><code>var state = ReadTagInteger("<PLC>.<STATE_TAG>", 0);
state === 1 ? "#22C55E" : "#EF4444"</code></pre> </article><article id="animation-syntax-item-5" class="docs-detail-row"> <strong>字段结果类型清单</strong> <p>Condition、Visibility 返回布尔值；几何字段返回数字；Display Text 和颜色字段返回字符串。模板参数先替换为字符串，数值须显式转换。</p> <ul> <li>布尔值：Condition、Visibility</li><li>数字：几何输入、位移、角度和缩放值</li><li>字符串：Display Text、Fill color、Border color</li><li>模板参数：写在字符串中，按需要转换类型</li> </ul> <pre class="docs-code-block"><code>// Condition
ReadTagBoolean("<PLC>.<RUN_TAG>", false)
// At limit maximum
shape.width * 2
// Script Color / Fill color
ReadTagBoolean("<PLC>.<ALARM_TAG>", false) ? "#dc2626" : "#16a34a"</code></pre> </article><article id="animation-syntax-item-6" class="docs-detail-row"> <strong>模板变量</strong> <p>模板变量格式为 <NAME>，变量名以字母或下划线开头。模板变量放入脚本表达式时，应写在字符串里。</p> <ul> <li>Tag 字符串："<PLC>.<RUN_TAG>"</li><li>颜色字符串："<FILL_COLOR>"</li><li>模板变量参与 JavaScript 表达式时应放入字符串</li> </ul> <pre class="docs-code-block"><code>ReadTagBoolean("<PLC>.<RUN_TAG>", false)</code></pre> </article><article id="animation-syntax-item-7" class="docs-detail-row"> <strong>跨页复用放在哪里</strong> <p>PPT 插件不提供全局脚本文档。当前页所需的换算函数、格式化函数、颜色规则和常量放在 Page Script；确实需要跨页高级复用时，使用宿主 runtime、自写 SDK 或模板能力。</p> <ul> <li>同页换算：formatPressure(value)</li><li>同页颜色：getStateColor(state)</li><li>同页常量：const QUALITY_BAD_COLOR = "#EF4444"</li><li>跨页高级能力交给宿主或 SDK</li> </ul> </article><article id="animation-syntax-item-8" class="docs-detail-row"> <strong>Page Script 顶层变量和函数</strong> <p>当前页动画字段可引用 Page Script 顶层 var、let、const 和 function，用于共享量程、Tag 名和换算函数。</p> <ul> <li>顶层变量：const levelMax = 100</li><li>顶层 Tag 名称：var levelTag = "<PLC>.<LEVEL_TAG>"</li><li>顶层函数：function readLevel() { ... }</li><li>动画字段：readLevel() 或 levelMax</li> </ul> <pre class="docs-code-block"><code>const levelMax = 100;
var levelTag = "<PLC>.<LEVEL_TAG>";
function readLevel() {
return ReadTagDouble(levelTag, 0);
}
// Scale / Source value
readLevel()
// Scale / Source maximum
levelMax</code></pre> </article><article id="animation-syntax-item-9" class="docs-detail-row"> <strong>页面准备回调与初始动画</strong> <p>window.hqVisuDesignerPageReady 会在页面运行时准备完成后执行，适合做组件初始化、文本设置和显示控制。用于初始动画计算的值，应放在当前页 Page Script 顶层。</p> <ul> <li>初始动画值优先引用顶层变量或函数</li><li>ready 回调适合调用 hqVisuDesigner.setComponentText 等运行时方法</li><li>页面脚本文档只初始化一次</li> </ul> <pre class="docs-code-block"><code>var pumpVisible = true;
window.hqVisuDesignerPageReady = function() {
hqVisuDesigner.writeVariable("pumpVisible", pumpVisible);
hqVisuDesigner.refreshView();
};</code></pre> </article><article id="animation-syntax-item-10" class="docs-detail-row"> <strong>位语法</strong> <p>位读取用 TAG[bit]，如 PLC_LINE01.PUMP01.TAG[0] 或 <PLC>.<TAG>[1]。bit 为 0–31，且须在父 Tag 位宽内。写位使用 Write Tag Bit，Target Tag 填父 Tag，Bit Index 填位号。</p> <ul> <li>读取位语法：`TAG[bit]`</li><li>读取位：ReadTagBoolean("<PLC>.<TAG>[1]", false)</li><li>写位目标："<PLC>.<TAG>"</li><li>Bit Index：0 到 31</li><li>Bit Action：Set、Reset、Toggle</li> </ul> <pre class="docs-code-block"><code>ReadTagBoolean("<PLC>.<TAG>[1]", false)</code></pre> </article><article id="animation-syntax-item-11" class="docs-detail-row"> <strong>异步逻辑放置位置</strong> <p>表达式须同步返回结果。fetch、Promise 或定时器放在 Page Script 或 hqVisuDesignerPageReady，将结果存入页面变量供表达式读取。设备写入由真实用户操作发起。</p> <ul> <li>表达式字段：立即返回值</li><li>Page Script / hqVisuDesignerPageReady：处理异步准备</li><li>动画字段：读取变量、Tag 或函数结果</li><li>外部数据建议由 Mingcedar 接口或脚本层整理后再进入页面</li> </ul> </article><article id="animation-syntax-item-12" class="docs-detail-row"> <strong>行为条件与数据质量</strong> <p>按钮和 Script Color 的 Condition 控制是否执行；State Color 的 Condition 选择 TRUE / FALSE 状态。Quality Override 控制质量边框或隐藏。Active、Enabled 仅用于部分旧配置或特定编辑器。</p> <ul> <li>Condition：按行为类型填写执行条件或状态条件</li><li>Quality Override：启用 Follow data quality (border / hide)</li><li>Hide when quality is bad：质量异常时隐藏对象</li><li>业务状态仍由状态 Tag 或规则表达</li> </ul> <pre class="docs-code-block"><code>var enabled = ReadTagBoolean("<PLC>.<ENABLE_TAG>", false);
var qualityGood = ReadTagQualityGood("<PLC>.<VALUE_TAG>");
// Script Color / Condition
enabled && qualityGood</code></pre> </article> </div> </section>