文档手册

脚本：页面脚本 / 全局脚本 / qtedit API

脚本用于给画面包增加运行逻辑，全部使用 JavaScript。功能区 Scripts 分组有两个入口：Global Script 编辑整个 PPT 共享的全局脚本，用于跨页共用的变量和函数（导出后在浏览器端运行，所有页面都可调用）；Page Script 只编辑当前页脚本，用于本页逻辑。两个入口都可以各带一份 JSON 文档作为配置数据（全局导出到 json/global.json，页级导出到 json/pages/<页名>.json）。脚本运行时可使用一组运行时方法：ReadTag 系列读取 PLC 标签值，WriteTag 系列写值，qtedit.* 运行时对象用于修改组件文本/颜色/显隐、跳转页面、写运行时变量、强制刷新画面。这些方法与行为里的 Definition / Condition / Value / Text 表达式属于同一套运行时；区别在于脚本区编写整段逻辑，表达式位只返回一个结果值。

功能

功能: 脚本：页面脚本 / 全局脚本 / qtedit API

用 JavaScript 给画面增加运行逻辑：全局脚本放整个 PPT 共享的变量和函数，页面脚本只处理当前页；运行时用 ReadTag 系列读取 PLC 标签、用日期时间方法生成当前时间文本、用 qtedit.* 操作组件和跳转页面，qteditPageReady 在页面就绪时执行一次初始化。读单个位使用 "标签名[位号]" 方括号写法。

功能说明

使用方法：常用方法和写法

按位置选择入口，再使用下面几类运行时方法。生命周期：在页面脚本里挂载 window.qteditPageReady（页面就绪时执行一次）、在全局脚本里挂载 window.qteditGlobalReady（整包就绪时执行一次）完成初始化。

读标签 ReadTag 系列：ReadTagBoolean / ReadTagInteger / ReadTagDouble / ReadTagString，第二个参数是读不到时的回退值
日期时间：GetCurrentDate() 返回 yyyy-MM-dd，GetCurrentDateTime() 返回 yyyy-MM-dd HH:mm:ss，FormatDateTime(value, "yyyy/MM/dd HH:mm:ss") 可把时间值格式化成指定显示格式；搜索关键字包括时间、日期、time、date、datetime
读单个位（重点）：在标签名后面加方括号位号，写成 "Device.TAGNAME[位号]"，用 ReadTagBoolean 读；位号 0 起算、范围 0-31、方括号里不能有空格
标签质量：ReadTagQuality(name, "bad") 取质量文本，ReadTagQualityGood(name) 直接判断是否为 good（质量只有 good / bad，不是工艺值）
写标签 WriteTag 系列：WriteTagBoolean / WriteTagInteger / WriteTagDouble / WriteTagString（最终是否写成由宿主机决定，可能有权限、确认、原因、异步）
操作组件 qtedit.*：setComponentText(名或ID, 值)、setComponentFill、setComponentBorder、setComponentVisible、setComponentLayout、findComponent、getComponentData
跳转与变量 qtedit.*：openPage("页名") 同包跳页、openScreen("画面编号") 跨画面包、openWebsite(url, 是否新窗口) 开外链、writeVariable(名, 值) 写运行时变量、refreshView() 强制重新应用状态

// 页面脚本：页面就绪时初始化
window.qteditPageReady = function (ctx) {
  // 读一个整数标签里的第 0 位（方括号写法，无空格）
  var pumpRun = ReadTagBoolean("PLC1.PUMP.STATUS[0]", false);
  qtedit.setComponentText("Title 1", pumpRun ? "运行" : "停止");
  qtedit.setComponentFill("Lamp 1", pumpRun ? "#22C55E" : "#EF4444");
  qtedit.refreshView();
};

常用 JS 写法：日期时间、状态文本和安全默认值

这些片段适合放在 Page Script、Global Script、Click Script 或行为的 Definition 区域里。Condition / Value / Text 位置通常只放最后一句能立即返回的表达式；较长的判断、格式化和变量准备放在 Definition 或脚本体里。

三元表达式：condition ? trueValue : falseValue，适合把布尔值转成文本、颜色或数值。
安全默认值：ReadTagBoolean / ReadTagDouble 等第二个参数是回退值，读不到时不让脚本报错。
日期时间文本：当前日期用 GetCurrentDate()，当前日期时间用 GetCurrentDateTime()，已有时间值用 FormatDateTime(...) 改显示格式。
多条件判断：简单场景用三元表达式，复杂场景用 if / else 先算出变量，再写到组件或返回给行为。

// 日期 / 时间 / time / date
var today = GetCurrentDate();                 // yyyy-MM-dd
var nowText = GetCurrentDateTime();           // yyyy-MM-dd HH:mm:ss
var displayTime = FormatDateTime(nowText, "yyyy/MM/dd HH:mm:ss");

// 布尔状态转文本
var currentValue = ReadTagBoolean("A1.Tset.1", false);
var text = currentValue ? "OK" : "异常";

// 数值分段
var speed = ReadTagDouble("Line01.MainMotor.SpeedPV", 0);
var levelText = speed >= 80 ? "高" : (speed >= 40 ? "中" : "低");

// 质量保护：质量不好时优先显示通讯异常
if (!ReadTagQualityGood("Line01.MainMotor.SpeedPV")) {
  text = "通讯异常";
}

qtedit.setComponentText("StatusText", text + " / " + displayTime);
qtedit.setComponentText("LevelText", levelText);

常用 JS 语法：字符串拼接、数字格式化、数组和对象

画面脚本里最常见的不是复杂算法，而是把 Tag 值整理成现场人员看得懂的文字。字符串拼接、模板字符串、数字格式化、数组查找和对象配置都可以放在 Definition、Page Script 或 Global Script 中，最后再把结果写到组件或返回给行为。

字符串拼接：简单场景用 '速度: ' + speed，多变量推荐模板字符串 速度: ${speed}。
数字格式化：用 Number(value).toFixed(1) 控制小数位，避免显示太长。
数组：用数组维护状态映射、报警列表或多个组件名，再用循环统一处理。
对象：用对象保存配置表，例如状态码到文本、颜色和优先级的映射。

// 字符串拼接和模板字符串
var speed = ReadTagDouble('Line01.MainMotor.SpeedPV', 0);
var unit = ' rpm';
var speedText = '速度: ' + Number(speed).toFixed(1) + unit;
var timeText = `更新时间: ${GetCurrentDateTime()}`;

// 对象映射：状态码转文本和颜色
var state = ReadTagInteger('Line01.MainMotor.State', 0);
var stateMap = {
  0: { text: '停止', color: '#94A3B8' },
  1: { text: '运行', color: '#22C55E' },
  2: { text: '故障', color: '#EF4444' }
};
var stateInfo = stateMap[state] || { text: '未知', color: '#F59E0B' };

// 数组和循环：批量更新多个组件
var targetNames = ['SpeedText', 'SpeedTextCopy'];
for (var i = 0; i < targetNames.length; i++) {
  qtedit.setComponentText(targetNames[i], speedText);
}

qtedit.setComponentText('StateText', `${stateInfo.text} / ${timeText}`);
qtedit.setComponentFill('StateLamp', stateInfo.color);

适用场景

两种典型场景。一是需要跨多页共用一段逻辑或一份配置：把函数、常量、配方名放进全局脚本，每页直接调用，不用每页重复写。二是某一页的初始化或联动逻辑：在页面脚本的 qteditPageReady 里读标签、拼好文本、设好组件初始颜色/显隐，或者在点击脚本里读当前值再写回（例如读取再加 10）。需要按钮/状态灯直接跟一个布尔位走时，用方括号位读把整数标签里的某一位当布尔量取出来驱动显示。

共享方法和配置放全局脚本；只影响本页的逻辑放页面脚本
同包跳页用 qtedit.openPage(...)，跨画面包用 qtedit.openScreen(...)，不要写 ../../xxx.html 这种磁盘相对路径

边界与易错点

常见注意事项：① 位读必须用精确的 "标签名[位号]" 方括号写法、方括号里不能有空格，位号只支持 0-31，超出或写错会读不到（按回退值处理）；位读是从整数标签里取一位，源标签得是整数。② 写标签不要假设"调了就成功、就同步"，宿主机可能加权限校验、确认框、原因输入或异步处理，写动作也可能返回 Promise。③ 异步方法（fetch、setTimeout、setInterval、requestAnimationFrame）只能放在脚本体位置（全局脚本、页面脚本、点击脚本、悬停脚本），不要塞进 Condition、Move、Rotate、Scale、Script Color 这种要立刻算出一个值的同步表达式位。④ 改了全局脚本或全局 JSON，必须整包重新导出，只导当前页带不上这些改动。

HQ VISU Designer 脚本工作区 — **图示 1: 脚本工作区 Script Workspace**
编辑全局脚本和页面脚本，并各带一份 JSON 配置；运行时用 ReadTag 和 qtedit.* 驱动画面。