动画字段支持哪些写法 | HQ VISU Designer

Move、Rotate、Scale 的输入值、位移、角度和缩放比例都可以写数值表达式。表达式必须能立即算出数字，不能直接放入异步请求。

• 固定数值：120
• Tag 数值：ReadTagDouble("<device-code>.<tag-code>", 0)
• 对象尺寸：shape.width、shape.height
• 计算表达式：shape.width * 2、shape.height * 0.5

ReadTagDouble("<device-code>.<tag-code>", 0)
shape.width
shape.height * 0.5

Definition 是当前行为的准备区，适合读取 Tag、定义变量、计算中间值和准备函数。真正决定结果的是后面的 Condition、Value、Text、Fill、Stroke、Visibility、Offset、Angle 或 Scale 字段。Definition 中只声明变量但最终字段没有引用时，页面显示不会变化。

• Definition：准备变量和函数
• Condition / Enabled：返回布尔值
• Text / Fill / Stroke：返回字符串
• Input Value / Angle / Offset / Scale：返回数字
• Visibility：返回布尔值

// Definition
var running = ReadTagBoolean("<device-code>.<run-tag>", false);
var color = running ? "#22C55E" : "#64748B";

// Fill
color

Blink、Active、Enabled 和超限控制类字段通常需要布尔结果。建议写明确比较，不要只写一个含义不清的变量。

• 二值 Tag：ReadTagBoolean("<device-code>.<tag-code>", false)
• 状态码比较：state === 1
• 组合条件：running === true && alarm === false

var running = ReadTagBoolean("<device-code>.<run-tag>", false);
var alarm = ReadTagBoolean("<device-code>.<alarm-tag>", false);
running === true && alarm === false

颜色字段使用十六进制颜色值。普通颜色行为通常通过颜色选择器维护；Script Color 的 Fill 和 Stroke 可以返回颜色字符串。

• 固定颜色："#22C55E"
• 脚本颜色：state === 1 ? "#22C55E" : "#EF4444"
• 模板颜色："<FILL_COLOR>"

var state = ReadTagInteger("<device-code>.<state-tag>", 0);
state === 1 ? "#22C55E" : "#EF4444"

填写动画字段前，应先确认该字段需要的结果类型。Condition、Enabled、Active 和 Visibility 返回布尔值；Input Value、Offset、Angle、Scale、Limit、Clamp 返回数字；Fill、Stroke、Text 返回字符串；模板变量参与表达式时，应按字符串处理。字段类型明确后，后续排查会更直接。

• 布尔值：Condition、Enabled、Active、Visibility
• 数字：Input Value、Offset、Angle、Scale、Limit、Clamp
• 字符串：Fill、Stroke、Text
• 模板变量：在表达式中作为字符串使用

// Active
ReadTagBoolean("<PLC>.<RUN_TAG>", false)

// Offset Max
shape.width * 2

// Fill
ReadTagBoolean("<PLC>.<ALARM_TAG>", false) ? "#dc2626" : "#16a34a"

模板变量格式为 <NAME>，变量名以字母或下划线开头。模板变量放入脚本表达式时，应写在字符串里。

• Tag 字符串："<PLC>.<RUN_TAG>"
• 颜色字符串："<FILL_COLOR>"
• 模板变量参与 JavaScript 表达式时应放入字符串

ReadTagBoolean("<PLC>.<RUN_TAG>", false)

多个页面都要使用的换算函数、格式化函数、颜色规则和项目级常量，可以放在 Global Script。当前页面独有的 Tag 名称、表格数据、弹窗范围和运行时状态仍应放在 Page Script，避免跨页面内容相互依赖。

• 项目级换算：formatPressure(value)
• 项目级颜色：getStateColor(state)
• 项目级常量：const QUALITY_BAD_COLOR = "#EF4444"
• 页面独有内容仍放 Page Script

当前页 Page Script 顶层声明的 var、let、const 和 function 可以被当前页动画字段引用。适合把量程、偏移量、Tag 名称和换算函数放在这里，再让 Move、Rotate、Scale、Script Color、Condition 等字段直接引用。

• 顶层变量：const levelMax = 100
• 顶层 Tag 名称：var levelTag = "<device-code>.<level-tag>"
• 顶层函数：function readLevel() { ... }
• 动画字段：readLevel() 或 levelMax

const levelMax = 100;
var levelTag = "<device-code>.<level-tag>";

function readLevel() {
  return ReadTagDouble(levelTag, 0);
}

// Scale / Input Value
readLevel()

// Scale / Input Max
levelMax

window.qteditPageReady 会在页面运行时准备完成后执行，适合做组件初始化、文本设置、显示控制和运行后刷新。用于初始动画计算的值，应优先放在 Page Script 或 Global Script 顶层。

• 初始动画值优先引用顶层变量或函数
• ready 回调适合调用 qtedit.setComponentText 等运行时方法
• 回调内更新状态后需要驱动行为时，可写入运行时变量并刷新视图

var pumpVisible = true;

window.qteditPageReady = function() {
  qtedit.writeVariable("pumpVisible", pumpVisible);
  qtedit.refreshView();
};

读取整数 Tag 的单个位时，在完整 Tag 点名后使用 [0] 到 [31] 的位序号，通用写法是 `TAG[bit]`，例如 `Device.TAG[0]` 或 `<device-code>.<tag-code>[1]`。写入单个位时使用 Write Tag Bit，目标 Tag 填父整数 Tag，位号填写在 Bit Index 中。

• 读取位语法：`TAG[bit]`
• 读取位：ReadTagBoolean("<device-code>.<tag-code>[1]", false)
• 写位目标："<device-code>.<tag-code>"
• Bit Index：0 到 31
• Bit Action：Set、Reset、Toggle

ReadTagBoolean("<device-code>.<tag-code>[1]", false)

表达式字段需要同步返回结果，不适合直接放 fetch、Promise 或定时器。需要异步读取外部数据时，应放在 Page Script 或 qteditPageReady 中处理，再把结果写入运行时变量或内部 JSON Tag，动画字段只读取已经准备好的结果。

• 表达式字段：立即返回值
• Page Script / qteditPageReady：处理异步准备
• 动画字段：读取变量、Tag 或函数结果
• 外部数据建议由 HQControl 接口或脚本层整理后再进入页面

`Active` 或 `Enabled` 用于决定行为当前是否参与计算；Quality Border 用于表达数据质量 GOOD / BAD。二者职责不同：Active 控制行为是否启用，Quality Border 告诉用户当前数据是否可信。需要在质量异常时隐藏对象，可结合 `Hide when quality BAD` 使用。

• Active / Enabled：控制行为是否启用
• Quality Border：表达数据质量
• Hide when quality BAD：质量异常时隐藏对象
• 业务状态仍应由实际 Tag 或状态规则表达

var enabled = ReadTagBoolean("<PLC>.<ENABLE_TAG>", false);
var qualityGood = ReadTagQualityGood("<PLC>.<VALUE_TAG>");

// Active
enabled && qualityGood