动画功能详解 | Mingcedar Studio

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

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

ReadTagDouble("<PLC>.<TAG>", 0)
shape.width
shape.height * 0.5

颜色和文本行为通过 Setup Script 准备数据，再由输出表达式返回结果。Fill color / Border color 对应旧名 Fill / Stroke。几何编辑器没有 Setup Script，直接使用读取方法或 Page Script 函数。

• Setup Script：准备变量和函数
• Condition：返回布尔值
• Display Text / Fill color / Border color：返回字符串
• Source value / Angle / Offset / Scale：返回数字
• Visibility：返回布尔值

// Setup Script
var running = ReadTagBoolean("<PLC>.<RUN_TAG>", false);
var color = running ? "#22C55E" : "#64748B";

// Script Color / Fill color
color

State Color、Blink Color 的 Condition 和 Script Color 的 Visibility 需要布尔结果。可直接读取布尔 Tag，或通过比较及组合条件得到 true / false。

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

var running = ReadTagBoolean("<PLC>.<RUN_TAG>", false);
var alarm = ReadTagBoolean("<PLC>.<ALARM_TAG>", false);
running === true && alarm === false

颜色值可使用十六进制格式。普通颜色行为通过颜色选择器维护；Script Color 的 Fill color 和 Border color 填写返回颜色字符串的表达式。

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

var state = ReadTagInteger("<PLC>.<STATE_TAG>", 0);
state === 1 ? "#22C55E" : "#EF4444"

Condition、Visibility 返回布尔值；几何字段返回数字；Display Text 和颜色字段返回字符串。模板参数先替换为字符串，数值须显式转换。

• 布尔值：Condition、Visibility
• 数字：几何输入、位移、角度和缩放值
• 字符串：Display Text、Fill color、Border color
• 模板参数：写在字符串中，按需要转换类型

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

// At limit maximum
shape.width * 2

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

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

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

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

PPT 插件不提供全局脚本文档。当前页所需的换算函数、格式化函数、颜色规则和常量放在 Page Script；确实需要跨页高级复用时，使用宿主 runtime、自写 SDK 或模板能力。

• 同页换算：formatPressure(value)
• 同页颜色：getStateColor(state)
• 同页常量：const QUALITY_BAD_COLOR = "#EF4444"
• 跨页高级能力交给宿主或 SDK

当前页动画字段可引用 Page Script 顶层 var、let、const 和 function，用于共享量程、Tag 名和换算函数。

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

const levelMax = 100;
var levelTag = "<PLC>.<LEVEL_TAG>";

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

// Scale / Source value
readLevel()

// Scale / Source maximum
levelMax

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

• 初始动画值优先引用顶层变量或函数
• ready 回调适合调用 hqVisuDesigner.setComponentText 等运行时方法
• 页面脚本文档只初始化一次

var pumpVisible = true;

window.hqVisuDesignerPageReady = function() {
  hqVisuDesigner.writeVariable("pumpVisible", pumpVisible);
  hqVisuDesigner.refreshView();
};

位读取用 TAG[bit]，如 PLC_LINE01.PUMP01.TAG[0] 或 <PLC>.<TAG>[1]。bit 为 0–31，且须在父 Tag 位宽内。写位使用 Write Tag Bit，Target Tag 填父 Tag，Bit Index 填位号。

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

ReadTagBoolean("<PLC>.<TAG>[1]", false)

表达式须同步返回结果。fetch、Promise 或定时器放在 Page Script 或 hqVisuDesignerPageReady，将结果存入页面变量供表达式读取。设备写入由真实用户操作发起。

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

按钮和 Script Color 的 Condition 控制是否执行；State Color 的 Condition 选择 TRUE / FALSE 状态。Quality Override 控制质量边框或隐藏。Active、Enabled 仅用于部分旧配置或特定编辑器。

• Condition：按行为类型填写执行条件或状态条件
• Quality Override：启用 Follow data quality (border / hide)
• Hide when quality is bad：质量异常时隐藏对象
• 业务状态仍由状态 Tag 或规则表达

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

// Script Color / Condition
enabled && qualityGood

Move 读取一个数值，把这个数值按输入范围换算成百分比，再把百分比映射到 At limit minimum 和 At limit maximum 之间，最终让对象沿水平或垂直方向移动。

• 0% 对应 At limit minimum
• 100% 对应 At limit maximum
• 中间值按比例移动

Source value 返回数值；Limit minimum / Limit maximum 是实际换算范围；MOVEMENT OUTPUT 中的 At limit minimum / At limit maximum 为位移；Move axis 指定方向。

• Source value：数值表达式
• Source minimum / Source maximum：源范围及别名
• Limit minimum / Limit maximum：实际夹取和归一化范围
• At limit minimum / At limit maximum：端点位移
• Move axis：Horizontal 或 Vertical

源范围仅提供 ValueMin / ValueMax 别名；输入限制默认独立为 0、100。要跟随源范围，分别将 Limit minimum / Limit maximum 设为 ValueMin / ValueMax。

• 实际映射以 Limit minimum / Limit maximum 为准
• 未启用隐藏时，超限输入限制在端点
• Hide outside input limits 控制超限时隐藏

Offset 不是百分比，而是画布距离。可以写固定数字，也可以使用当前对象尺寸。

• 向右移动一个对象宽度：shape.width
• 向左移动一个对象宽度：-shape.width
• 向下移动半个对象高度：shape.height * 0.5
• 向上移动两个对象高度：-shape.height * 2

Source value = ReadTagDouble("<PLC>.<POSITION_TAG>", 0)
Source minimum = 0
Source maximum = 100
At limit minimum = 0
At limit maximum = shape.width
Move axis = Horizontal

先确定来源 Tag 和量程，再确定移动方向，最后填写 Offset。配置完成后，再决定是否开启超限隐藏和质量边框。

• 第一步：确认输入值和量程
• 第二步：选择 Horizontal 或 Vertical
• 第三步：填写 At limit minimum / At limit maximum
• 第四步：按需要开启 Hide outside input limits
• 第五步：按需要开启 Quality Border

滑块、行程、位置指示适合 Move。液位柱、进度条和填充条通常不应使用 Move，因为它们表达的是长度变化，应使用 Scale。

Rotate 读取当前角度，把对象围绕指定 Pivot 旋转。它适合风机、指针、阀门和方向件。

• Rotation input 决定当前角度
• Maximum angle 限制最大角度
• Pivot 决定旋转中心

Rotation input 返回角度（度）；Maximum angle 的绝对值定义正负两侧的允许范围；PIVOT POINT 选择旋转支点。当前界面提供五个预设支点，不提供自定义 X / Y 输入框。

• Rotation input：同步角度表达式
• Maximum angle：例如 90 表示 -90° 到 +90°
• PIVOT POINT：Center、Top、Bottom、Left、Right

Rotate 负责角度或旋转表达，不负责判断设备是否处于运行状态。风机、指针和阀门常见做法是：Rotate 表达方向或角度，State Color 表达运行、停止、报警或手自动状态。

• 角度来源：Rotation input
• 运行状态：State Color 或 Multi-State Color
• 数据质量：Quality Border

角度字段可以直接读取 Tag，也可以根据百分比换算成角度。

• 直接角度：ReadTagDouble("<PLC>.<ANGLE_TAG>", 0)
• 百分比换算：ReadTagDouble("<PLC>.<SPEED_TAG>", 0) * 3.6
• 读取原始角度：shape.rotation

Rotation input = ReadTagDouble("<PLC>.<ANGLE_TAG>", 0)
Maximum angle = 360
Pivot = Center

先确认对象的机械中心，再选择 Pivot。对象中心选错时，即使角度正确，旋转也会显得不稳定。

• 第一步：确认对象原始方向
• 第二步：选择 Pivot
• 第三步：填写 Rotation input
• 第四步：填写 Maximum angle
• 第五步：按需要开启质量边框

风机、指针和阀门适合 Rotate。对象只是左右移动时应使用 Move；对象长度变化时应使用 Scale。

Scale 把输入值换算成一个比例，让对象从指定边缘向外增长或缩短。它适合液位、进度条、负载条和填充条。

• At limit minimum 对应最低比例
• At limit maximum 对应最高比例
• Moving edge 决定移动边，对边固定

Source value 通过 Limit minimum / Limit maximum 映射到 SCALE OUTPUT 两个端点的缩放因子。Moving edge 指定移动边，对边固定。

• At limit minimum / At limit maximum：例如 0 / 1 或 0.5 / 1.5
• Moving edge = Top：顶边移动、底边固定
• Moving edge = Right：右边移动、左边固定
• Moving edge = Left：左边移动、右边固定

Scale 适合对一个独立填充对象做比例变化。液位、进度条和负载条通常应拆成背景容器和前景填充对象，再让前景对象按固定边增长。不要直接缩放包含文字、边框和图标的复杂组合，否则文字和边框也会跟随变形。

• 背景容器保持固定
• 前景填充对象参与 Scale
• 文字和单位建议单独放置
• 复杂设备组不直接整体 Scale

Scale 的输入值使用数值表达式，比例字段使用数值或计算表达式。

• 液位：At limit minimum = 0，At limit maximum = 1
• 轻微变化：At limit minimum = 0.8，At limit maximum = 1.2
• 输入值：ReadTagDouble("<PLC>.<LEVEL_TAG>", 0)

Source value = ReadTagDouble("<PLC>.<LEVEL_TAG>", 0)
Source minimum = 0
Source maximum = 100
At limit minimum = 0
At limit maximum = 1
Moving edge = Top

先确定对象应从哪一边增长，再设置 Moving edge。液位类对象通常固定底部，进度条通常固定左侧。

• 第一步：确认增长方向
• 第二步：设置 Moving edge
• 第三步：填写输入量程
• 第四步：填写 At limit minimum / At limit maximum
• 第五步：按需要叠加 Range Color

Scale 适合长度或填充比例变化。对象整体移动时使用 Move；对象转动时使用 Rotate。

Blink Color 在条件成立时，让对象在 ON 和 OFF 两组显示状态之间切换。条件不成立时，可以使用 False 状态。

• ON 状态：条件成立时的闪烁亮态
• OFF 状态：条件成立时的闪烁暗态
• False 状态：条件不成立时的普通状态

Setup Script 准备数据，Condition 返回布尔值；Action 中的 TRUE、FALSE 控制是否应用对应状态。各输出通道按 Blink ON、Blink OFF、Condition FALSE 三列配置。

• Condition：布尔表达式
• Fill color / Border color：按状态配置颜色
• Visibility：按状态配置显示或隐藏
• FALSE 默认关闭，需要静止外观时启用
• 当前编辑器没有 Blink Interval 输入框

闪烁用于需要关注的报警或异常状态。当前编辑器不提供速度或间隔设置。应限制同时闪烁的对象数量，并用静止文字或状态色补充说明。

• 报警或异常状态按项目规范配置
• 常规运行和停止可使用 State Color
• Condition FALSE 需同时启用 FALSE
• 数据质量通过 Quality Override 单独表达

Condition 可以读取布尔 Tag，也可以组合状态码和质量判断。

// Setup Script
var alarm = ReadTagBoolean("<PLC>.<ALARM_TAG>", false);
var qualityGood = ReadTagQualityGood("<PLC>.<ALARM_TAG>");

// Condition
alarm && qualityGood

先填写触发条件，再配置 Blink ON 和 Blink OFF。需要条件为假时保持静止外观，应启用 FALSE 并设置 Condition FALSE；最后检查质量覆盖。

• 填写 Condition
• 启用需要的输出通道
• 配置 Blink ON / Blink OFF
• 按需要启用 FALSE 并配置 Condition FALSE
• 核对 Good / Bad 质量显示

报警灯、故障块、超限提醒适合 Blink。运行、停止、自动、手动等普通状态优先使用 State Color 或 Multi-State Color。

Range Color 读取一个数值，把它落入预设 Limits 的区间，再根据区间选择颜色、边框和显隐状态。

• 适合连续值
• 适合低、中、高、危险等区间
• 默认 4 个分割点形成 5 个区间

Range value 返回数值；Range actions 的 Upper limit 为区间上限，Fill、Border、Visibility 决定各区间显示。支持 1–24 个区间，N 个区间对应 N−1 个递增上限；仅一个区间时无需设置上限。

• Range value：数值表达式
• Upper limit：递增有限数值
• Fill / Border：各区间颜色
• Visibility：各区间显隐

四个递增上限 L1、L2、L3、L4 形成五段：值 ≤ L1、L1 < 值 ≤ L2、L2 < 值 ≤ L3、L3 < 值 ≤ L4、值 > L4。上限属于当前区间，最终区间不包含最后上限。

• Limits 示例：20, 40, 60, 80
• 形成区间：≤20、(20,40]、(40,60]、(60,80]、>80
• 先确定单位和工程量程，再确定区间颜色

Range value 通常读取模拟量 Tag。以下各段分别填写到标注字段；Upper limit 按递增顺序填写。

// Setup script
var temperature = ReadTagDouble("PLC_LINE01.OVEN01.TEMPERATURE", 0);

// Range value
temperature

// Upper limit: 20, 40, 60, 80
// Final (+∞): values above 80

先确认数值单位和量程，再确定区间边界。边界写完后，再设置每个区间的颜色和显隐。

• 第一步：确认 Tag 和单位
• 第二步：填写 Range value
• 第三步：填写 Limits
• 第四步：设置每个区间颜色
• 第五步：按需要开启质量边框

温度、压力、负载、液位等连续值适合 Range。固定状态码使用 Discrete Color；复杂优先级状态使用 Multi-State Color。

Blink 最适合报警和强提醒。它不用于表达连续过程，而用于提示用户关注少数关键对象。

当对象本质上是在页面里沿某个方向移动时，例如滑块、行程位置、水平推进件，应使用 Move 表达位置变化。

Rotate 适合指针、风机、阀门和方向件。配置重点是旋转中心与对象机械特征一致。

Scale 最适合液位、进度条、增长条、长度变化件。它真正关心的是哪一边固定、哪一边变化。

Range 本身可以是颜色区间，也可以和几何范围映射配合。它最适合让用户快速判断数值落在哪个段位，而不是只看一个单一数字。

如果对象整体坐标发生变化，例如滑块向右移动、行程块沿轨道移动、位置标记上移，应选择 Move。

如果对象一边固定，另一边增长或收缩，例如液位柱向上增长、进度条向右增长，应选择 Scale。

液位由背景容器和前景填充对象组成。前景使用 Scale，Moving edge 设为 Top；Move 会移动整个对象，不适合液位填充。

优先给报警、运动方向、旋转设备、液位变化和进度变化这类静态表达不够直观的信息加动画。普通状态色、普通文字和普通按钮通常不需要额外动画。

如果对象已经通过颜色清晰表达状态，通常不需要再配置同等强度的动画。颜色和动画应分层表达：颜色负责基础状态，动画只强化重点状态。

如果一整页大量对象同时闪烁、旋转或缩放，用户注意力会被分散，关键状态反而不突出。建议只在报警、方向、旋转设备和关键过程变化上配置动画。

当前几何编辑器没有 Post Operations 输入区。可复用的换算函数放 Page Script，文本、边框和显隐交给相应行为；设备写入使用真实用户触发的交互入口。

• Page Script 提供同页换算函数
• 几何输入直接返回数值
• 颜色和文本使用相应行为
• 设备写入不放入动画表达式

风机通常最适合用 Rotate 表达运行，同时配置基础运行状态色。旋转表达设备正在转动，颜色表达设备是否处于运行态。

报警灯最适合 Blink，旁边再配 Script Text 或 Tag Text 显示报警内容。这样用户既知道有问题，也知道具体是什么问题。

液位通常最适合 Scale 从底边往上长，再叠一个 Range Color 或状态区间颜色。这样既有形态变化，也有区间感知。

滑块、行程件和推进块更适合 Move。必要时可以再根据位置区间改变颜色，但不要把本该位移的对象做成整体缩放。