所属产品: Mingcedar Studio DESIGNER

脚本：页面脚本 / hqVisuDesigner API | Mingcedar Studio

用 JavaScript 给当前页面增加运行逻辑：Page Script 顶层变量、常量、类和函数可供本页动画与表达式引用；运行时用 ReadTag 系列读取 Tag，用 hqVisuDesigner 操作组件和跳转页面，hqVisuDesignerPageReady 在页面就绪时执行初始化。读单个位使用 "标签名[位号]" 方括号写法。

首次发布 2026-10-25T12:48:42.604953134Z 最近更新 2026-10-25T12:48:42.604952362Z

<div class="manual-doc-article manual-doc-article-section"><h2 id="script-page-hqvisudesigner-api">功能: 脚本：页面脚本 / hqVisuDesigner API</h2>

脚本用于给当前页面增加运行逻辑，全部使用 JavaScript。插件不提供跨整个 PPT 的 Global Script / 全局脚本文档；功能区 Scripts 分组只有当前页 Page Script 入口，alarm.js 也是当前页固定的受保护文档。Page Script 顶层声明可供同一页行为引用，但不会自动出现在其他页面。ReadTag 系列读取 Tag，hqVisuDesigner 用于修改组件文本、颜色、显隐、布局和页面跳转。WriteTag 系列只允许在真实用户点击、按下或释放动作中调用，不能放在 Page Script、Setup Script 或 Hover Script。行为里的 Setup Script / Condition / Value / Text 与页面脚本使用同一套现代 ECMAScript 2022 语法边界；表达式位只返回一个同步结果。

</article>

<h3 id="script-page-hqvisudesigner-api-item-2">Script Workspace 从新建到保存</h3>

打开 Scripts → Page Script，在左侧选择文档，或点击 New 填写 Folder、Name。在 Code 写脚本；取消 Enabled 可保留文档但不导出。Save 校验并保存当前页全部启用文档。

<ul>

<li>Scope：先确认正在编辑的是当前目标页面。</li>

<li>New 或 Ctrl+N：创建新脚本文档。</li>

<li>Folder：可选，用斜杠分隔文件夹路径。</li>

<li>Name：脚本文档名，不填写 .js 扩展名。</li>

<li>Enabled：取消后文档保留，但不导出也不参与 Save 校验。</li>

<li>Script Library 或 Ctrl+J：在当前光标处插入方法或模板。</li>

<li>Save 或 Ctrl+S：校验并保存整个脚本工作区。</li>

<li>Help 或 F1：查看脚本帮助。</li>

</ul>

</article>

<h3 id="script-page-hqvisudesigner-api-item-3">Quick Methods 方法库</h3>

在脚本编辑器打开 Quick Methods：左侧筛选类别，中间选择方法，右侧查看用途、示例和参数。搜索后点击 Insert 插入片段；可用方法以当前窗口为准。

</article>

<h3 id="script-page-hqvisudesigner-api-item-4">删除文档和 alarm.js 的区别</h3>

选中自建文档，点击 Delete 并确认。受保护的 alarm.js 不能删除；停用页面报警显示须编辑其中的报警配置。

<ul>

<li>删除前确认其他脚本和行为没有引用该文档里的函数或变量。</li>

<li>Delete 只对可删除的自建文档生效。</li>

<li>alarm.js 不可删除，应修改其配置内容。</li>

<li>误删或不想保存当前改动时点击 Cancel，不要点击 Save。</li>

</ul>

</article>

<h3 id="script-page-hqvisudesigner-api-item-5">使用方法：常用方法和写法</h3>

初始化时在 Page Script 设置 window.hqVisuDesignerPageReady，页面运行时就绪后调用一次。常用方法如下：

<ul>

<li>读标签 ReadTag 系列：ReadTagBoolean / ReadTagInteger / ReadTagDouble / ReadTagString，第二个参数是读不到时的回退值</li>

<li>日期时间：GetCurrentDate() 返回 yyyy-MM-dd，GetCurrentDateTime() 返回 yyyy-MM-dd HH:mm:ss，FormatDateTime(value, "yyyy/MM/dd HH:mm:ss") 可把时间值格式化成指定显示格式；搜索关键字包括时间、日期、time、date、datetime</li>

<li>读单个位（重点）：在完整标签名后面加方括号位号，例如 "PLC_LINE01.PUMP01.STATUS[3]"，用 ReadTagBoolean 读；位号 0 起算、范围 0-31、方括号里不能有空格</li>

<li>标签质量：ReadTagQuality(name, "bad") 取质量文本，ReadTagQualityGood(name) 直接判断是否为 good（质量只有 good / bad，不是工艺值）</li>

<li>WriteTag 系列：用于真实用户点击、按下或释放动作脚本；Page Script、Setup Script 和 Hover Script 不能写设备。是否生效仍由运行平台和设备确认。</li>

<li>操作组件 hqVisuDesigner：setComponentText(名或ID, 值)、setComponentFill、setComponentBorder、setComponentVisible、setComponentLayout、findComponent</li>

<li>跳转 hqVisuDesigner：openPage("页名") 同包跳页、openWebsite(url, 是否新窗口) 开外链</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar">JavaScriptJavaScript<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>// 页面脚本：页面就绪时初始化

window.hqVisuDesignerPageReady = function (ctx) {

// 读一个整数标签里的第 0 位（方括号写法，无空格）

const pumpRun = ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[0]", false);

hqVisuDesigner.setComponentText("Title 1", pumpRun ? "运行" : "停止");

hqVisuDesigner.setComponentFill("Lamp 1", pumpRun ? "#22C55E" : "#EF4444");

hqVisuDesigner.refreshView();

};</code></pre></div>

</article>

<h3 id="script-page-hqvisudesigner-api-item-6">常用 JS 写法：日期时间、状态文本和安全默认值</h3>

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

<ul>

<li>三元表达式：condition ? trueValue : falseValue，适合把布尔值转成文本、颜色或数值。</li>

<li>安全默认值：ReadTagBoolean / ReadTagDouble 等第二个参数是回退值，读不到时不让脚本报错。</li>

<li>日期时间文本：当前日期用 GetCurrentDate()，当前日期时间用 GetCurrentDateTime()，已有时间值用 FormatDateTime(...) 改显示格式。</li>

<li>多条件判断：简单场景用三元表达式，复杂场景用 if / else 先算出变量，再写到组件或返回给行为。</li>

</ul>

const today = GetCurrentDate(); // yyyy-MM-dd

const nowText = GetCurrentDateTime(); // yyyy-MM-dd HH:mm:ss

const displayTime = FormatDateTime(nowText, "yyyy/MM/dd HH:mm:ss");

// 布尔状态转文本（三元表达式）

const currentValue = ReadTagBoolean("PLC_LINE01.PUMP01.READY", false);

let text = currentValue ? "OK" : "异常";

// 数值分段

const speed = ReadTagDouble("PLC_LINE01.MOTOR01.SPEED", 0);

const levelText = speed >= 80 ? "高" : (speed >= 40 ? "中" : "低");

// 质量保护：质量不好时优先显示通讯异常

if (!ReadTagQualityGood("PLC_LINE01.MOTOR01.SPEED")) {

text = "通讯异常";

}

hqVisuDesigner.setComponentText("StatusText", `${text} / ${displayTime}`);

</article>

<h3 id="script-page-hqvisudesigner-api-item-7">常用 JS 语法：字符串拼接、数字格式化、数组和对象</h3>

在 Setup Script 或 Page Script 中用字符串拼接、数字格式化、数组查找和对象配置整理 Tag 值，再将结果返回给行为或写入组件。

<ul>

<li>字符串拼接：简单场景用 '速度: ' + speed，多变量推荐模板字符串 <code>速度: ${speed}</code>。</li>

<li>数字格式化：用 Number(value).toFixed(1) 控制小数位，避免显示太长。</li>

<li>数组：用数组维护状态映射、报警列表或多个组件名，再用循环统一处理。</li>

<li>对象：用对象保存配置表，例如状态码到文本、颜色和优先级的映射。</li>

</ul>

const speed = ReadTagDouble('PLC_LINE01.MOTOR01.SPEED', 0);

const unit = ' rpm';

const speedText = `速度: ${Number(speed).toFixed(1)}${unit}`;

const timeText = `更新时间: ${GetCurrentDateTime()}`;

// 对象映射：状态码转文本和颜色

const state = ReadTagInteger('PLC_LINE01.MOTOR01.STATE', 0);

const stateMap = {

0: { text: '停止', color: '#94A3B8' },

1: { text: '运行', color: '#22C55E' },

2: { text: '故障', color: '#EF4444' }

};

const stateInfo = stateMap[state] ?? { text: '未知', color: '#F59E0B' };

// 数组和循环：批量更新多个组件

const targetNames = ['SpeedText', 'SpeedTextCopy'];

targetNames.forEach((name) => hqVisuDesigner.setComponentText(name, speedText));

hqVisuDesigner.setComponentText('StateText', `${stateInfo.text} / ${timeText}`);

</article>

同页共用函数、常量和 Tag 前缀放在 Page Script 顶层；初始化逻辑放在 hqVisuDesignerPageReady。跨页高级复用使用宿主 runtime、自写 SDK 或模板。整数 Tag 的布尔位通过方括号位读驱动显示。

<ul>

<li>同页共享方法、常量和 Tag 前缀放当前页 Page Script</li>

<li>同包跳页用 hqVisuDesigner.openPage(...)；跨画面包走宿主 SDK，不要写 ../../other-screen/index.html 这种磁盘相对路径</li>

</ul>

</article>

<h3 id="script-page-hqvisudesigner-api-item-9">限制与常见问题</h3>

常见注意事项：① 位读必须用精确的 "标签名[位号]" 方括号写法、方括号里不能有空格，位号只支持 0-31；位写使用父整数 Tag + BitIndex，不能把 Tag[3] 当普通写入 Tag。② 写 Tag 只允许在真实用户点击动作中执行，且不要假设调用后必然同步成功。③ 异步方法只能放在脚本体位置；await 只能写在 async 函数内部，不支持顶层 await。④ import/export 属于模块语法，动画表达式与页面脚本文档不支持；高级能力走自写 SDK。

</article>

</div>

图示 1: 脚本工作区 Script Workspace

编辑当前页 JavaScript 文档；运行时用 ReadTag 与 hqVisuDesigner 驱动画面。

</figcaption>

</figure>

图示 2: Quick Methods 方法库

按类别或搜索定位方法，查看示例与参数后点击 Insert。

</figcaption>

</figure>

</div>