标签读写方法：先明确类型，再决定写入方式 | Mingcedar Studio

ReadTagBoolean(name, fallback) 读取开关量、反馈、允许状态或状态位。数据缺失或不可用时返回 fallback，通常设为 false。

• 适合开关量、启停反馈和允许状态
• 位读取也使用该方法
• 回退值只用于页面默认显示，不代表真实采集值

var running = ReadTagBoolean("PLC_LINE01.PUMP01.RUN", false);
var ready = ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[0]", false);

ReadTagInteger(name, fallback) 读取状态码、模式、步骤、计数或整型设定值，可用于状态文本和颜色映射。fallback 通常设为 0。

• 适合模式号、状态码、步骤号和计数
• 适合 Discrete Color 和 Multi-State Color 的输入
• 不要把状态码先读成字符串再自行转换

var mode = ReadTagInteger("PLC_LINE01.PUMP01.MODE", 0);
var count = ReadTagInteger("PLC_LINE01.PUMP01.COUNT", 0);

ReadTagDouble(name, fallback) 读取温度、压力、液位等连续数值，适用于 Move、Rotate、Scale 和 Range Color。fallback 通常设为 0.0。

• 适合连续数值和工程量
• 适合几何动画和区间颜色输入
• 显示单位和格式化建议在文本表达中处理

var pressure = ReadTagDouble("PLC_LINE01.PUMP01.PRESSURE", 0.0);
var level = ReadTagDouble("PLC_LINE01.PUMP01.LEVEL", 0);

ReadTagString(name, fallback) 读取配方名、批次号等文本，可直接显示或用于 Script Text 拼接。fallback 通常为空字符串。

• 适合名称、模式文案、批次号和备注
• 文本为空时应准备清晰回退显示
• 不建议用字符串读取替代布尔、整数或浮点读取

var recipe = ReadTagString("PLC_LINE01.PUMP01.RECIPE", "");
var batchNo = ReadTagString("PLC_LINE01.PUMP01.BATCH_NO", "");

ReadTagJson(name, fallback) 读取对象或数组。fallback 须符合页面所需结构，如空数组或空对象。

• JSON 数组：表格行、趋势摘要、分页结果
• JSON 对象：页面配置、设备摘要、统计结果
• 默认值应与页面使用方式一致

var rows = ReadTagJson("PLC_LINE01.REPORT01.ROWS", []);
var config = ReadTagJson("PLC_LINE01.REPORT01.PAGE_CONFIG", {});

ReadTagDateTime(name, fallback) 读取更新、确认、批次等时间。fallback 可为 null 或默认时间；按页面语言和项目要求格式化。

• 适合更新时间、确认时间和事件时间
• 无时间值时可以返回 null
• 格式化应放在文本表达或页面函数中

var updatedAt = ReadTagDateTime("PLC_LINE01.PUMP01.UpdatedAt", null);
var confirmedAt = ReadTagDateTime("PLC_LINE01.PUMP01.CONFIRMED_AT", null);

完整点名为 device.tag，不含空格。整数位读取使用 TAG[bit]，如 PLC_LINE01.PUMP01.STATUS[0]。bit 为 0–31，且须小于父 Tag 位宽；16 位数据仅支持 0–15，[0] 为最低位。可用于 ReadTagBoolean、State Color 或布尔表达式。

• 完整点名：`PLC_LINE01.PUMP01.STATUS`
• 语法模板：`TAG[bit]` / `PLC_LINE01.PUMP01.TAG[0]`
• 读取最低位：`PLC_LINE01.PUMP01.STATUS[0]`
• 读取第 31 位：`PLC_LINE01.PUMP01.STATUS[31]`
• 模板写法：`'<PLC>.<STATUS_TAG>[3]'`
• 位索引范围为 0 到 31

var ready = ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[0]", false);
var fault = ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false);

ReadTagQuality(name, fallback) 返回数据质量，不代表业务或报警状态。可据此显示灰态、边框、提示或隐藏对象。

• 质量状态不是工艺值
• 质量异常不等同于业务报警
• 只返回 good 或 bad；建议 fallback 使用 bad
• 质量文本适合用于提示和诊断显示

var quality = ReadTagQuality("PLC_LINE01.PUMP01.PRESSURE", "bad");
var text = quality === "good" ? "数据可用" : "数据待确认";

ReadTagQualityGood(name) 返回质量是否为 good，可用于 Condition、Visibility 或显示表达式。质量异常时显示回退提示，不将回退值当作实时值。

• 返回 true / false
• 适合控制显隐、禁用、颜色和边框
• 质量不是 good 时，应按数据不可确认处理

var qualityGood = ReadTagQualityGood("PLC_LINE01.PUMP01.PRESSURE");
var displayText = qualityGood ? ReadTagDouble("PLC_LINE01.PUMP01.PRESSURE", 0).toFixed(1) : "--";

WriteTagBoolean(name, value, options) 写入布尔命令；options 可携带权限、确认和审计上下文。也可使用 Write Tag 行为或 hqVisuDesigner.WriteTag(payload)。关键写入由用户操作触发，并核对宿主结果。

• 适合启停、允许、复位和确认
• value 应为 true / false
• 最终写入结果由运行端和宿主机确认

WriteTagBoolean("PLC_LINE01.PUMP01.START", true);
WriteTagBoolean("PLC_LINE01.PUMP01.RESET", true);

WriteTagInteger(name, value, options) 写入模式、步骤、枚举或整型设定值；options 提供权限和确认上下文。值须符合目标类型与现场约定，状态码使用整数。

• 适合模式号、步骤号和枚举值
• value 应为整数
• 写入前应确认目标 Tag 支持该取值范围

WriteTagInteger("PLC_LINE01.PUMP01.MODE", 2);
WriteTagInteger("PLC_LINE01.PUMP01.STEP", 10);

`WriteTagDouble(name, value)` 用于写入设定值、比例、速度、温度、压力等连续数值。页面输入值应先完成范围、单位和格式处理，再提交写入。

• 适合设定值和连续工程量
• value 应为数字
• 输入框写值前应处理单位、上下限和空值

WriteTagDouble("PLC_LINE01.PUMP01.SETPOINT", 12.5);
WriteTagDouble("PLC_LINE01.PUMP01.SPEED_SET", 80);

`WriteTagString(name, value)` 用于写入配方名、批次号、备注和文本参数。写入前应确认文本长度、允许字符和目标系统处理方式，避免把显示文案误写为设备控制值。

• 适合配方名、批次号和备注
• value 应为字符串
• 文本输入应先处理空值和长度

WriteTagString("PLC_LINE01.PUMP01.RECIPE", "RCP-001");
WriteTagString("PLC_LINE01.PUMP01.REMARK", "READY");

`WriteTagJson(name, value)` 用于写入结构化参数、组合输入结果、页面配置或报表条件。结构应保持稳定，字段名应与运行端或脚本约定一致。

• 适合结构化参数和组合输入
• value 可以是对象或数组
• 字段结构应稳定，便于运行端处理

WriteTagJson("PLC_LINE01.PUMP01.PARAMS", {
  speed: 80,
  enabled: true
});

WriteTagDateTime(name, value) 写入操作、批次等时间。value 可为 new Date() 或运行端认可的时间值；须符合项目时区和记录规则。

• 适合确认时间、操作时间和批次时间
• value 可使用 Date 对象
• 关键记录仍应由运行端审计链路确认

WriteTagDateTime("PLC_LINE01.PUMP01.CONFIRMED_AT", new Date());
WriteTagDateTime("PLC_LINE01.PUMP01.BATCH_START", new Date());

hqVisuDesigner.WriteTag(payload) 或全局 WriteTag(payload) 接收目标、值、权限、确认和审计信息。类型化写入方法也支持 options，均由宿主处理。

• 适合权限、确认、审计类写入
• 适合正式项目关键操作
• 字段越明确，宿主机越容易按规则接管

hqVisuDesigner.WriteTag({
  TagName: "PLC_LINE01.PUMP01.CMD",
  Value: 1,
  PermissionCode: "io:write",
  RequireConfirm: true,
  ConfirmText: "确认发送启动命令？"
});

页面提供 TagName、Value、PermissionCode、RequireConfirm、ConfirmText、RequireReason、AuditAction 等字段；运行端执行权限校验、确认、原因输入、审计并返回异步结果。关键写入须由用户操作触发，不能随页面加载下发。

• TagName：目标完整 Tag 点名
• Value：要写入的值
• PermissionCode：运行端权限码
• RequireConfirm / ConfirmText：确认提示
• RequireReason：要求填写原因
• AuditAction：审计动作名称

hqVisuDesigner.WriteTag({
  TagName: "PLC_LINE01.PUMP01.CMD_START",
  Value: true,
  PermissionCode: "io:write",
  RequireConfirm: true,
  ConfirmText: "确认启动设备？",
  RequireReason: true,
  AuditAction: "device-start"
});

ReadCalculatedTag(name, fallbackValue?) 及其 hqVisuDesigner 同名方法读取已发布计算 Tag，保留 0 和 false。不可用时返回 fallbackValue，省略则返回 null。

var totalFlow = ReadCalculatedTag("Line01TotalFlow", null);
var ready = ReadCalculatedTag("Line01Ready", false);

CALCULATED_TAG 填 Line01TotalFlow；Setup Script 保存名称并读取，Display Text 引用结果。计算 Tag 不可写入。

// Setup Script
var calculatedTagName = "<CALCULATED_TAG>";
var totalFlow = ReadCalculatedTag(calculatedTagName, null);

// Display Text
totalFlow === null ? "--" : totalFlow.toFixed(1) + " m³/h"

计算 Tag 不支持写入或位后缀，仅读取来源正确且质量为 good 的结果，不回退到同名普通 Tag。不可用时显示提示，并检查名称、发布、权限和订阅。