Mingcedar

所属产品: Mingcedar Studio DESIGNER

脚本方法使用说明 | Mingcedar Studio

脚本用于标准配置无法完成的计算、校验和组合动作。简单操作优先使用 Tag 绑定、模板和内置行为。

首次发布 最近更新

<section id="preface" class="docs-block docs-block-intro"> <span class="section-kicker">脚本</span> <h2>使用前说明</h2> <p>脚本用于标准配置无法完成的计算、校验和组合动作。简单操作优先使用 Tag 绑定、模板和内置行为。</p> <div class="docs-task-grid"> <article id="preface-item-1" class="docs-task-card"> <span>脚本</span> <strong>先判断是否需要脚本</strong> <p>跳页、单值写入、变量切换和诊断窗使用标准行为；条件组合、连续步骤或动态目标使用脚本。</p> </article><article id="preface-item-2" class="docs-task-card"> <span>脚本</span> <strong>脚本应保持职责清晰</strong> <p>用标准行为表达常规动作，将脚本留给复杂条件和页面联动，便于维护。</p> </article><article id="preface-item-3" class="docs-task-card"> <span>脚本</span> <strong>阅读顺序</strong> <p>先了解四种脚本的运行时机，再查阅 Tag 读写、页面对象方法和组合示例。</p> </article> </div> </section> <section id="script-placement" class="docs-block"> <span class="section-kicker">入口</span> <h2>先决定脚本入口</h2> <p>脚本入口决定运行时机和可用上下文。</p> <div class="docs-detail-list"> <article id="script-placement-item-1" class="docs-detail-row"> <strong>页面脚本的配置范围</strong> <p>脚本按页面维护，没有可编辑的项目级脚本文档。当前页逻辑放在 Page Script，跨页复用使用宿主 runtime 或模板。</p> <ul> <li>页面逻辑放当前页 Page Script</li><li>跨页复用优先交给宿主 runtime 或模板</li><li>单页流程不应作为全局公共逻辑维护</li> </ul> <pre class="docs-code-block"><code>function openAlarmPage() {

hqVisuDesigner.openPage(&quot;Alarm&quot;);

}</code></pre> </article><article id="script-placement-item-2" class="docs-detail-row"> <strong>Page Script：当前页逻辑</strong> <p>Page Script 处理当前页初始化、局部变量、数据整理、表格和交互逻辑。</p> <ul> <li>适合页面打开后的初始化</li><li>适合当前页数据整理</li><li>适合当前页表格和局部交互逻辑</li> </ul> <pre class="docs-code-block"><code>window.hqVisuDesignerPageReady = function(ctx) {

var rows = window.tableRows || [];

hqVisuDesigner.setComponentText(&quot;RowCountText&quot;, String(rows.length));

};</code></pre> </article><article id="script-placement-item-3" class="docs-detail-row"> <strong>Setup Script：准备行为使用的数据</strong> <p>Setup Script 读取 Tag、计算中间值，供 Condition、Value 或 Display Text 使用。旧配置名为 Definition；设备写入由点击行为触发。</p> <ul> <li>读取 Tag 并计算中间值</li><li>由 Condition / Value / Display Text 返回结果</li><li>同页共用的变量和函数放在 Page Script</li> </ul> <pre class="docs-code-block"><code>var running = ReadTagInteger(&quot;PLC_LINE01.PUMP01.RUN&quot;, 0);

var alarm = ReadTagBoolean(&quot;PLC_LINE01.PUMP01.ALARM&quot;, false);

var ready = running === 1 &amp;&amp; !alarm;</code></pre> </article><article id="script-placement-item-4" class="docs-detail-row"> <strong>Click Script 与 Hover Script：对象级动作</strong> <p>Click Script 处理点击、跳页、写值和弹窗；Hover Script 处理悬停提示、预览和样式变化。页面初始化使用 Page Script。</p> <ul> <li>点击动作优先放 Click Script</li><li>悬停反馈优先放 Hover Script</li><li>对象脚本不承担页面初始化职责</li> </ul> <pre class="docs-code-block"><code>// Click Script

hqVisuDesigner.openPage(&quot;Alarm&quot;);

// Hover Script -&gt; Mouse Over

object.style.opacity = &quot;0.75&quot;;</code></pre> </article><article id="script-placement-item-5" class="docs-detail-row"> <strong>表达式字段：必须同步返回结果</strong> <p>表达式字段须同步返回布尔值、文本、颜色或数字。fetch、Promise 和定时器放在 Page Script、对象脚本或 hqVisuDesignerPageReady 中，将结果存入页面变量。设备写入由用户操作触发。</p> <ul> <li>布尔字段：返回 true / false</li><li>数值字段：返回 number</li><li>文本和颜色字段：返回 string</li><li>异步逻辑不直接作为表达式返回值</li> </ul> <pre class="docs-code-block"><code>// Page Script

function pressureColor() {

var pressure = ReadTagDouble(&quot;PLC_LINE01.PUMP01.PRESSURE&quot;, 0);

return pressure &gt; 8 ? &quot;#dc2626&quot; : &quot;#16a34a&quot;;

}

// Script Color / Fill

pressureColor()</code></pre> </article> </div> <div class="docs-note-grid"> <figure id="script-placement-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ScriptWorkspaceForm.png" alt="页面脚本入口" loading="lazy" decoding="async"> <figcaption> <strong>页面脚本入口</strong> <p>页面级逻辑优先放入 Page Script，避免分散在大量对象脚本中。</p> </figcaption> </figure><figure id="script-placement-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/MouseBehaviorEditorForm.png" alt="点击脚本入口" loading="lazy" decoding="async"> <figcaption> <strong>点击脚本入口</strong> <p>按钮或对象动作优先放点击脚本，职责会更清晰。</p> </figcaption> </figure><figure id="script-placement-image-3" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/MouseBehaviorEditorForm.png" alt="悬停脚本入口" loading="lazy" decoding="async"> <figcaption> <strong>悬停脚本入口</strong> <p>悬停类交互和提示行为更适合放在这里。</p> </figcaption> </figure> </div> </section><section id="config-methods" class="docs-block"> <span class="section-kicker">配置</span> <h2>页面与项目配置方法：优先从配置读取数据</h2> <p>当前页的数据优先来自 Page Script 变量、函数、内部 JSON Tag 和默认 alarm.js。它们适合保存页面参数、表格数据、显示规则和报警范围。</p> <div class="docs-detail-list"> <article id="config-methods-item-1" class="docs-detail-row"> <strong>Page Script 变量和函数</strong> <p>当前页的表格行、筛选条件、显示开关、标题和阈值放在 Page Script。Table 的 Rows 可引用数组变量或函数，无需单独建立 JSON 文档。</p> <ul> <li>适合当前页独有配置</li><li>常用于表格数据和局部规则</li><li>Rows 可填变量名或函数名</li> </ul> <pre class="docs-code-block"><code>var tableRows = [

[&quot;Pump 1&quot;, &quot;Running&quot;],

[&quot;Pump 2&quot;, &quot;Stop&quot;]

];

var panelTitle = &quot;泵站运行概览&quot;;</code></pre> </article><article id="config-methods-item-2" class="docs-detail-row"> <strong>内部 JSON Tag</strong> <p>Python 或宿主脚本将报表、分页等结构化结果写入内部 JSON Tag，页面通过 ReadTagJson(...) 读取，沿用 Tag 通道。</p> <ul> <li>适合报表行、分页结果和结构化状态</li><li>由 Python 写内部 Tag</li><li>PPT 页面只负责 ReadTagJson 读取</li> </ul> <pre class="docs-code-block"><code>var rows = ReadTagJson(&quot;PLC_LINE01.REPORT01.ROWS&quot;, []);

var updatedAt = ReadTagDateTime(&quot;PLC_LINE01.REPORT01.UPDATED_AT&quot;, null);</code></pre> </article><article id="config-methods-item-3" class="docs-detail-row"> <strong>默认 alarm.js</strong> <p>每页默认有一个受保护的 alarm.js，用来维护当前页报警窗口开关和范围。编辑核心对象 `HQVISU_PAGE_ALARM` 即可。</p> <ul> <li>适合当前页报警窗口开关</li><li>适合当前页报警范围</li><li>每页独立，跟随页面导出</li> </ul> <pre class="docs-code-block"><code>HQVISU_PAGE_ALARM = {

showWindow: true,

tags: [],

deviceCodes: [],

objectIdentifiers: [],

groupCodes: [],

areaCodes: []

};</code></pre> </article><article id="config-methods-item-4" class="docs-detail-row"> <strong>getPageAlarm(fallbackValue)</strong> <p>读取当前页的 PPT 报警设置。它不是运行端报警规则本身，而是当前页面随导出包携带的报警窗口开关和报警范围配置。当前页没有 alarm 配置时，会返回传入的回退值或默认结构。</p> <ul> <li>适合读取当前页是否允许显示报警窗口</li><li>适合读取页面携带的报警范围</li><li>导出后来自 HQVISU_PAGE_ALARM</li><li>没有配置时要给回退值，避免空对象报错</li> </ul> <pre class="docs-code-block"><code>var alarmConfig = getPageAlarm({

showWindow: true,

tags: [],

deviceCodes: [],

objectIdentifiers: [],

groupCodes: [],

areaCodes: []

});

if (alarmConfig.showWindow) {

hqVisuDesigner.setComponentVisible(&quot;PageAlarmPanel&quot;, true);

}</code></pre> </article><article id="config-methods-item-5" class="docs-detail-row"> <strong>PPT 报警设置字段说明</strong> <p>showWindow 控制报警窗口；tags 为完整点名，deviceCodes 为设备或 PLC 编码，objectIdentifiers 为对象标识，groupCodes 为信号组，areaCodes 为区域范围。空数组表示该维度不附加条件，不表示自动选择全部点位。</p> <ul> <li>只指定几个点位时，优先填 tags</li><li>按设备限定范围时，填 deviceCodes</li><li>按对象或设备单元限定范围时，填 objectIdentifiers</li><li>按信号类别限定范围时，填 groupCodes</li><li>按区域或产线限定范围时，填 areaCodes</li> </ul> <pre class="docs-code-block"><code>{

&quot;showWindow&quot;: true,

&quot;tags&quot;: [],

&quot;deviceCodes&quot;: [],

&quot;objectIdentifiers&quot;: [],

&quot;groupCodes&quot;: [],

&quot;areaCodes&quot;: []

}</code></pre> </article><article id="config-methods-item-6" class="docs-detail-row"> <strong>GetCurrentUsername()</strong> <p>读取当前宿主用户。它适合做轻量级个性化显示，例如页面欢迎语、当前操作人展示和当前用户标记。它不是权限系统本身，权限判断应以宿主机规则为准。</p> <ul> <li>适合欢迎语和当前用户显示</li><li>适合轻量日志标记</li><li>权限校验仍然应以宿主机规则为准</li> </ul> <pre class="docs-code-block"><code>var username = GetCurrentUsername();

hqVisuDesigner.setComponentText(&quot;CurrentUser&quot;, username || &quot;Guest&quot;);</code></pre> </article> </div> <div class="docs-note-grid"> <figure id="config-methods-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/TextEditorForm.png" alt="页面脚本代码面板" loading="lazy" decoding="async"> <figcaption> <strong>页面脚本代码面板</strong> <p>页面配置读取、报警读取和局部逻辑通常会集中出现在这里。</p> </figcaption> </figure> </div> </section><section id="tag-methods" class="docs-block"> <span class="section-kicker">Tag</span> <h2>标签读写方法：先明确类型，再决定写入方式</h2> <p>Tag 方法可以分成三组：读值、读质量、写值。理解这三组后，大多数对象逻辑都能按职责连接起来。</p> <div class="docs-detail-list"> <article id="tag-methods-item-1" class="docs-detail-row"> <strong>ReadTagBoolean：读取布尔量</strong> <p>ReadTagBoolean(name, fallback) 读取开关量、反馈、允许状态或状态位。数据缺失或不可用时返回 fallback，通常设为 false。</p> <ul> <li>适合开关量、启停反馈和允许状态</li><li>位读取也使用该方法</li><li>回退值只用于页面默认显示，不代表真实采集值</li> </ul> <pre class="docs-code-block"><code>var running = ReadTagBoolean(&quot;PLC_LINE01.PUMP01.RUN&quot;, false);

var ready = ReadTagBoolean(&quot;PLC_LINE01.PUMP01.STATUS[0]&quot;, false);</code></pre> </article><article id="tag-methods-item-2" class="docs-detail-row"> <strong>ReadTagInteger：读取整数与状态码</strong> <p>ReadTagInteger(name, fallback) 读取状态码、模式、步骤、计数或整型设定值，可用于状态文本和颜色映射。fallback 通常设为 0。</p> <ul> <li>适合模式号、状态码、步骤号和计数</li><li>适合 Discrete Color 和 Multi-State Color 的输入</li><li>不要把状态码先读成字符串再自行转换</li> </ul> <pre class="docs-code-block"><code>var mode = ReadTagInteger(&quot;PLC_LINE01.PUMP01.MODE&quot;, 0);

var count = ReadTagInteger(&quot;PLC_LINE01.PUMP01.COUNT&quot;, 0);</code></pre> </article><article id="tag-methods-item-3" class="docs-detail-row"> <strong>ReadTagDouble：读取模拟量</strong> <p>ReadTagDouble(name, fallback) 读取温度、压力、液位等连续数值，适用于 Move、Rotate、Scale 和 Range Color。fallback 通常设为 0.0。</p> <ul> <li>适合连续数值和工程量</li><li>适合几何动画和区间颜色输入</li><li>显示单位和格式化建议在文本表达中处理</li> </ul> <pre class="docs-code-block"><code>var pressure = ReadTagDouble(&quot;PLC_LINE01.PUMP01.PRESSURE&quot;, 0.0);

var level = ReadTagDouble(&quot;PLC_LINE01.PUMP01.LEVEL&quot;, 0);</code></pre> </article><article id="tag-methods-item-4" class="docs-detail-row"> <strong>ReadTagString：读取文本</strong> <p>ReadTagString(name, fallback) 读取配方名、批次号等文本，可直接显示或用于 Script Text 拼接。fallback 通常为空字符串。</p> <ul> <li>适合名称、模式文案、批次号和备注</li><li>文本为空时应准备清晰回退显示</li><li>不建议用字符串读取替代布尔、整数或浮点读取</li> </ul> <pre class="docs-code-block"><code>var recipe = ReadTagString(&quot;PLC_LINE01.PUMP01.RECIPE&quot;, &quot;&quot;);

var batchNo = ReadTagString(&quot;PLC_LINE01.PUMP01.BATCH_NO&quot;, &quot;&quot;);</code></pre> </article><article id="tag-methods-item-5" class="docs-detail-row"> <strong>ReadTagJson：读取结构化数据</strong> <p>ReadTagJson(name, fallback) 读取对象或数组。fallback 须符合页面所需结构，如空数组或空对象。</p> <ul> <li>JSON 数组：表格行、趋势摘要、分页结果</li><li>JSON 对象：页面配置、设备摘要、统计结果</li><li>默认值应与页面使用方式一致</li> </ul> <pre class="docs-code-block"><code>var rows = ReadTagJson(&quot;PLC_LINE01.REPORT01.ROWS&quot;, []);

var config = ReadTagJson(&quot;PLC_LINE01.REPORT01.PAGE_CONFIG&quot;, {});</code></pre> </article><article id="tag-methods-item-6" class="docs-detail-row"> <strong>ReadTagDateTime：读取时间值</strong> <p>ReadTagDateTime(name, fallback) 读取更新、确认、批次等时间。fallback 可为 null 或默认时间；按页面语言和项目要求格式化。</p> <ul> <li>适合更新时间、确认时间和事件时间</li><li>无时间值时可以返回 null</li><li>格式化应放在文本表达或页面函数中</li> </ul> <pre class="docs-code-block"><code>var updatedAt = ReadTagDateTime(&quot;PLC_LINE01.PUMP01.UpdatedAt&quot;, null);

var confirmedAt = ReadTagDateTime(&quot;PLC_LINE01.PUMP01.CONFIRMED_AT&quot;, null);</code></pre> </article><article id="tag-methods-item-7" class="docs-detail-row"> <strong>Tag 点名和位读取语法</strong> <p>完整点名为 device.tag，不含空格。整数位读取使用 TAG[bit]，如 PLC_LINE01.PUMP01.STATUS[0]。bit 为 0–31，且须小于父 Tag 位宽；16 位数据仅支持 0–15，[0] 为最低位。可用于 ReadTagBoolean、State Color 或布尔表达式。</p> <ul> <li>完整点名：`PLC_LINE01.PUMP01.STATUS`</li><li>语法模板：`TAG[bit]` / `PLC_LINE01.PUMP01.TAG[0]`</li><li>读取最低位：`PLC_LINE01.PUMP01.STATUS[0]`</li><li>读取第 31 位：`PLC_LINE01.PUMP01.STATUS[31]`</li><li>模板写法：`&#39;&lt;PLC&gt;.&lt;STATUS_TAG&gt;[3]&#39;`</li><li>位索引范围为 0 到 31</li> </ul> <pre class="docs-code-block"><code>var ready = ReadTagBoolean(&quot;PLC_LINE01.PUMP01.STATUS[0]&quot;, false);

var fault = ReadTagBoolean(&quot;PLC_LINE01.PUMP01.STATUS[3]&quot;, false);</code></pre> </article><article id="tag-methods-item-8" class="docs-detail-row"> <strong>ReadTagQuality：读取质量状态</strong> <p>ReadTagQuality(name, fallback) 返回数据质量，不代表业务或报警状态。可据此显示灰态、边框、提示或隐藏对象。</p> <ul> <li>质量状态不是工艺值</li><li>质量异常不等同于业务报警</li><li>只返回 good 或 bad；建议 fallback 使用 bad</li><li>质量文本适合用于提示和诊断显示</li> </ul> <pre class="docs-code-block"><code>var quality = ReadTagQuality(&quot;PLC_LINE01.PUMP01.PRESSURE&quot;, &quot;bad&quot;);

var text = quality === &quot;good&quot; ? &quot;数据可用&quot; : &quot;数据待确认&quot;;</code></pre> </article><article id="tag-methods-item-9" class="docs-detail-row"> <strong>ReadTagQualityGood：判断质量是否 good</strong> <p>ReadTagQualityGood(name) 返回质量是否为 good，可用于 Condition、Visibility 或显示表达式。质量异常时显示回退提示，不将回退值当作实时值。</p> <ul> <li>返回 true / false</li><li>适合控制显隐、禁用、颜色和边框</li><li>质量不是 good 时，应按数据不可确认处理</li> </ul> <pre class="docs-code-block"><code>var qualityGood = ReadTagQualityGood(&quot;PLC_LINE01.PUMP01.PRESSURE&quot;);

var displayText = qualityGood ? ReadTagDouble(&quot;PLC_LINE01.PUMP01.PRESSURE&quot;, 0).toFixed(1) : &quot;--&quot;;</code></pre> </article><article id="tag-methods-item-10" class="docs-detail-row"> <strong>WriteTagBoolean：写入布尔值</strong> <p>WriteTagBoolean(name, value, options) 写入布尔命令；options 可携带权限、确认和审计上下文。也可使用 Write Tag 行为或 hqVisuDesigner.WriteTag(payload)。关键写入由用户操作触发，并核对宿主结果。</p> <ul> <li>适合启停、允许、复位和确认</li><li>value 应为 true / false</li><li>最终写入结果由运行端和宿主机确认</li> </ul> <pre class="docs-code-block"><code>WriteTagBoolean(&quot;PLC_LINE01.PUMP01.START&quot;, true);

WriteTagBoolean(&quot;PLC_LINE01.PUMP01.RESET&quot;, true);</code></pre> </article><article id="tag-methods-item-11" class="docs-detail-row"> <strong>WriteTagInteger：写入整数值</strong> <p>WriteTagInteger(name, value, options) 写入模式、步骤、枚举或整型设定值；options 提供权限和确认上下文。值须符合目标类型与现场约定，状态码使用整数。</p> <ul> <li>适合模式号、步骤号和枚举值</li><li>value 应为整数</li><li>写入前应确认目标 Tag 支持该取值范围</li> </ul> <pre class="docs-code-block"><code>WriteTagInteger(&quot;PLC_LINE01.PUMP01.MODE&quot;, 2);

WriteTagInteger(&quot;PLC_LINE01.PUMP01.STEP&quot;, 10);</code></pre> </article><article id="tag-methods-item-12" class="docs-detail-row"> <strong>WriteTagDouble：写入浮点值</strong> <p>`WriteTagDouble(name, value)` 用于写入设定值、比例、速度、温度、压力等连续数值。页面输入值应先完成范围、单位和格式处理，再提交写入。</p> <ul> <li>适合设定值和连续工程量</li><li>value 应为数字</li><li>输入框写值前应处理单位、上下限和空值</li> </ul> <pre class="docs-code-block"><code>WriteTagDouble(&quot;PLC_LINE01.PUMP01.SETPOINT&quot;, 12.5);

WriteTagDouble(&quot;PLC_LINE01.PUMP01.SPEED_SET&quot;, 80);</code></pre> </article><article id="tag-methods-item-13" class="docs-detail-row"> <strong>WriteTagString：写入文本值</strong> <p>`WriteTagString(name, value)` 用于写入配方名、批次号、备注和文本参数。写入前应确认文本长度、允许字符和目标系统处理方式，避免把显示文案误写为设备控制值。</p> <ul> <li>适合配方名、批次号和备注</li><li>value 应为字符串</li><li>文本输入应先处理空值和长度</li> </ul> <pre class="docs-code-block"><code>WriteTagString(&quot;PLC_LINE01.PUMP01.RECIPE&quot;, &quot;RCP-001&quot;);

WriteTagString(&quot;PLC_LINE01.PUMP01.REMARK&quot;, &quot;READY&quot;);</code></pre> </article><article id="tag-methods-item-14" class="docs-detail-row"> <strong>WriteTagJson：写入结构化数据</strong> <p>`WriteTagJson(name, value)` 用于写入结构化参数、组合输入结果、页面配置或报表条件。结构应保持稳定，字段名应与运行端或脚本约定一致。</p> <ul> <li>适合结构化参数和组合输入</li><li>value 可以是对象或数组</li><li>字段结构应稳定，便于运行端处理</li> </ul> <pre class="docs-code-block"><code>WriteTagJson(&quot;PLC_LINE01.PUMP01.PARAMS&quot;, {

speed: 80,

enabled: true

});</code></pre> </article><article id="tag-methods-item-15" class="docs-detail-row"> <strong>WriteTagDateTime：写入时间值</strong> <p>WriteTagDateTime(name, value) 写入操作、批次等时间。value 可为 new Date() 或运行端认可的时间值；须符合项目时区和记录规则。</p> <ul> <li>适合确认时间、操作时间和批次时间</li><li>value 可使用 Date 对象</li><li>关键记录仍应由运行端审计链路确认</li> </ul> <pre class="docs-code-block"><code>WriteTagDateTime(&quot;PLC_LINE01.PUMP01.CONFIRMED_AT&quot;, new Date());

WriteTagDateTime(&quot;PLC_LINE01.PUMP01.BATCH_START&quot;, new Date());</code></pre> </article><article id="tag-methods-item-16" class="docs-detail-row"> <strong>hqVisuDesigner.WriteTag(payload)：显式传递写入上下文</strong> <p>hqVisuDesigner.WriteTag(payload) 或全局 WriteTag(payload) 接收目标、值、权限、确认和审计信息。类型化写入方法也支持 options，均由宿主处理。</p> <ul> <li>适合权限、确认、审计类写入</li><li>适合正式项目关键操作</li><li>字段越明确，宿主机越容易按规则接管</li> </ul> <pre class="docs-code-block"><code>hqVisuDesigner.WriteTag({

TagName: &quot;PLC_LINE01.PUMP01.CMD&quot;,

Value: 1,

PermissionCode: &quot;io:write&quot;,

RequireConfirm: true,

ConfirmText: &quot;确认发送启动命令？&quot;

});</code></pre> </article><article id="tag-methods-item-17" class="docs-detail-row"> <strong>hqVisuDesigner.WriteTag(payload) 常用字段</strong> <p>页面提供 TagName、Value、PermissionCode、RequireConfirm、ConfirmText、RequireReason、AuditAction 等字段；运行端执行权限校验、确认、原因输入、审计并返回异步结果。关键写入须由用户操作触发，不能随页面加载下发。</p> <ul> <li>TagName：目标完整 Tag 点名</li><li>Value：要写入的值</li><li>PermissionCode：运行端权限码</li><li>RequireConfirm / ConfirmText：确认提示</li><li>RequireReason：要求填写原因</li><li>AuditAction：审计动作名称</li> </ul> <pre class="docs-code-block"><code>hqVisuDesigner.WriteTag({

TagName: &quot;PLC_LINE01.PUMP01.CMD_START&quot;,

Value: true,

PermissionCode: &quot;io:write&quot;,

RequireConfirm: true,

ConfirmText: &quot;确认启动设备？&quot;,

RequireReason: true,

AuditAction: &quot;device-start&quot;

});</code></pre> </article><article id="tag-methods-item-18" class="docs-detail-row"> <strong>读取方法、类型和默认值</strong> <p>ReadCalculatedTag(name, fallbackValue?) 及其 hqVisuDesigner 同名方法读取已发布计算 Tag，保留 0 和 false。不可用时返回 fallbackValue，省略则返回 null。</p> <pre class="docs-code-block"><code>var totalFlow = ReadCalculatedTag(&quot;Line01TotalFlow&quot;, null);

var ready = ReadCalculatedTag(&quot;Line01Ready&quot;, false);</code></pre> </article><article id="tag-methods-item-19" class="docs-detail-row"> <strong>模板参数和变量组合</strong> <p>CALCULATED_TAG 填 Line01TotalFlow；Setup Script 保存名称并读取，Display Text 引用结果。计算 Tag 不可写入。</p> <pre class="docs-code-block"><code>// Setup Script

var calculatedTagName = &quot;&lt;CALCULATED_TAG&gt;&quot;;

var totalFlow = ReadCalculatedTag(calculatedTagName, null);

// Display Text

totalFlow === null ? &quot;--&quot; : totalFlow.toFixed(1) + &quot; m³/h&quot;</code></pre> </article><article id="tag-methods-item-20" class="docs-detail-row"> <strong>只读与质量要求</strong> <p>计算 Tag 不支持写入或位后缀，仅读取来源正确且质量为 good 的结果，不回退到同名普通 Tag。不可用时显示提示，并检查名称、发布、权限和订阅。</p> </article> </div> <div class="docs-note-grid"> <figure id="tag-methods-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/TextBehaviorEditorFormTagText.png" alt="文本绑定" loading="lazy" decoding="async"> <figcaption> <strong>文本绑定</strong> <p>文本类对象往往同时会配到读值方法和脚本文本逻辑。</p> </figcaption> </figure><figure id="tag-methods-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/IoClickWriteBehaviorEditorForm.png" alt="写值动作" loading="lazy" decoding="async"> <figcaption> <strong>写值动作</strong> <p>如果动作是通过行为编辑器配置的，底层仍然会走统一写入链。</p> </figcaption> </figure> </div> </section><section id="hqvisudesigner-runtime" class="docs-block"> <span class="section-kicker">hqVisuDesigner</span> <h2>页面对象修改：文字、颜色、显隐和跳转</h2> <p>读到 Tag 或输入值以后，页面通常要改文字、颜色、边框、显隐或跳转。这里按常用动作看，不要求先研究底层结构。</p> <div class="docs-detail-list"> <article id="hqvisudesigner-runtime-item-1" class="docs-detail-row"> <strong>findComponent / getComponentData</strong> <p>findComponent(nameOrId) 返回真实 DOM，用于改样式；getComponentData(nameOrId) 返回导出数据，用于读取原始位置、尺寸、角度和元信息。</p> <ul> <li>想直接改样式时先用 findComponent</li><li>想读导出数据时再用 getComponentData</li><li>对象名建议尽量稳定，方便脚本查找</li> </ul> <pre class="docs-code-block"><code>var titleEl = hqVisuDesigner.findComponent(&quot;Title 1&quot;);

var titleData = hqVisuDesigner.getComponentData(&quot;Title 1&quot;);

if (titleEl &amp;&amp; titleData) {

titleEl.style.color = &quot;#e11d48&quot;;

hqVisuDesigner.setComponentLayout(&quot;Title 1&quot;, { width: titleData.width });

}</code></pre> </article><article id="hqvisudesigner-runtime-item-2" class="docs-detail-row"> <strong>setComponentText / Fill / Border / Visible</strong> <p>这是最常用的一组页面修改方法。它们适合在页面脚本、点击脚本和质量判断中快速改变对象显示效果，而不需要自行处理 DOM 细节。</p> <ul> <li>改字用 setComponentText</li><li>改填充用 setComponentFill</li><li>改边框用 setComponentBorder</li><li>显隐控制用 setComponentVisible</li> </ul> <pre class="docs-code-block"><code>hqVisuDesigner.setComponentText(&quot;Title 1&quot;, &quot;READY&quot;);

hqVisuDesigner.setComponentFill(&quot;PumpBody&quot;, &quot;#16a34a&quot;);

hqVisuDesigner.setComponentBorder(&quot;PumpBody&quot;, &quot;#166534&quot;);

hqVisuDesigner.setComponentVisible(&quot;AlarmIcon&quot;, false);</code></pre> </article><article id="hqvisudesigner-runtime-item-3" class="docs-detail-row"> <strong>setComponentLayout：脚本直接改位置、尺寸和角度</strong> <p>当目标组件的位置、尺寸或角度需要根据运行状态计算时，可使用 setComponentLayout 调整布局。适用于拖动结果回写、特殊定位和多个条件共同决定布局的场景。</p> <ul> <li>x / y 控位置</li><li>width / height 控尺寸</li><li>angle 控角度</li><li>只改局部字段时也可以只传需要修改的字段</li> </ul> <pre class="docs-code-block"><code>hqVisuDesigner.setComponentLayout(&quot;Rectangle 1&quot;, {

x: 120,

y: 80,

width: 260,

height: 100,

angle: 0

});</code></pre> </article><article id="hqvisudesigner-runtime-item-4" class="docs-detail-row"> <strong>导航、语言和运行时刷新</strong> <p>同包跳转用 openPage，跨包用 openScreen，外部站点用 openWebsite。useLanguage 切换语言，refreshView 重新应用页面状态。</p> <ul> <li>同包跳转用 openPage</li><li>跨包跳转用 openScreen</li><li>外部网址用 openWebsite</li><li>语言切换用 useLanguage</li><li>重新应用页面状态用 refreshView</li> </ul> <pre class="docs-code-block"><code>hqVisuDesigner.openPage(&quot;Alarm&quot;);

hqVisuDesigner.openScreen(&quot;PUMP_OVERVIEW&quot;);

hqVisuDesigner.useLanguage(&quot;zh-CN&quot;);

hqVisuDesigner.refreshView();</code></pre> </article><article id="hqvisudesigner-runtime-item-5" class="docs-detail-row"> <strong>writeVariable：只保存页面运行时状态</strong> <p>页面需要记录当前 tab、当前选中设备或最近一次交互动作时，可以写入页面变量。该方法只适合页面联动，不等同于写 PLC，也不应代替正式 Tag 写值。</p> <ul> <li>适合切换 tab、筛选状态和当前选择</li><li>不适合设备控制</li><li>正式设备写入仍应使用 Write Tag 或写值动作</li> </ul> <pre class="docs-code-block"><code>hqVisuDesigner.writeVariable(&quot;currentTab&quot;, &quot;alarm&quot;);

hqVisuDesigner.writeVariable(&quot;selectedDevice&quot;, &quot;Pump01&quot;);</code></pre> </article><article id="hqvisudesigner-runtime-item-6" class="docs-detail-row"> <strong>浏览器存储：只保存界面偏好</strong> <p>ReadBrowserStorage、WriteBrowserStorage 和 RemoveBrowserStorage 保存区域选择、折叠状态等页面偏好。不要用浏览器存储保存设备控制状态、关键业务数据或长期审计记录。</p> <ul> <li>适合界面偏好和当前选择</li><li>不适合作为设备控制链路</li><li>不适合保存关键业务记录</li> </ul> <pre class="docs-code-block"><code>var area = ReadBrowserStorage(&quot;selectedArea&quot;, &quot;A01&quot;, &quot;local&quot;);

WriteBrowserStorage(&quot;selectedArea&quot;, area, &quot;local&quot;);

RemoveBrowserStorage(&quot;selectedArea&quot;, &quot;local&quot;);</code></pre> </article> </div> </section><section id="script-combos" class="docs-block"> <span class="section-kicker">组合</span> <h2>常用组合写法：按业务动作组合方法</h2> <p>实际项目中很少只调用一个方法。通常需要将读取配置、读取 Tag、修改页面、写变量和跳转组合起来，形成完整业务动作。</p> <div class="docs-detail-list"> <article id="script-combos-item-1" class="docs-detail-row"> <strong>页面打开后按配置刷新标题</strong> <p>这是典型页面脚本组合：先从当前页 Page Script 准备好的变量取值，再直接更新页面标题对象。相比将标题固定在 PPT 对象中，该方式更便于按页面上下文维护。</p> <pre class="docs-code-block"><code>window.hqVisuDesignerPageReady = function() {

var title = window.panelTitle || &quot;未命名页面&quot;;

hqVisuDesigner.setComponentText(&quot;PageTitle&quot;, title);

};</code></pre> </article><article id="script-combos-item-2" class="docs-detail-row"> <strong>质量异常时给对象描边并显示提示</strong> <p>这个组合适合设备状态提示。先用 ReadTagQualityGood 判断质量，再同时修改边框和提示图标显隐。</p> <pre class="docs-code-block"><code>var qualityGood = ReadTagQualityGood(&quot;PLC_LINE01.PUMP01.RUN&quot;);

hqVisuDesigner.setComponentBorder(&quot;PumpBody&quot;, qualityGood ? &quot;#0f172a&quot; : &quot;#f97316&quot;);

hqVisuDesigner.setComponentVisible(&quot;QualityBadge&quot;, !qualityGood);</code></pre> </article><article id="script-combos-item-3" class="docs-detail-row"> <strong>点击按钮后写值，并记录页面运行时状态</strong> <p>部分动作除了写 Tag，还需要页面同步记录本次操作已经触发。此时可以先写页面变量，再调用写值方法。</p> <pre class="docs-code-block"><code>hqVisuDesigner.writeVariable(&quot;lastAction&quot;, &quot;start&quot;);

WriteTagBoolean(&quot;PLC_LINE01.PUMP01.START&quot;, true);</code></pre> </article><article id="script-combos-item-4" class="docs-detail-row"> <strong>脚本里先拿模板输入值，再决定后续动作</strong> <p>template.getValue(...) 读取输入模板当前值，供脚本校验、写入或跳转。参数是带引号的实例名，如 template.getValue(&quot;Input Template&quot;)。</p> <pre class="docs-code-block"><code>var inputValue = template.getValue(&quot;Input Template&quot;);

if (inputValue !== &quot;&quot;) {

WriteTagString(&quot;PLC_LINE01.PUMP01.RECIPE&quot;, inputValue);

}</code></pre> </article> </div> <div class="docs-note-grid"> <figure id="script-combos-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/HyperlinkBehaviorEditorForm.png" alt="打开链接" loading="lazy" decoding="async"> <figcaption> <strong>页面跳转与外链</strong> <p>导航类脚本通常会和页面级方法一起组合使用。</p> </figcaption> </figure><figure id="script-combos-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/LanguageSettingsForm.png" alt="多语言文本" loading="lazy" decoding="async"> <figcaption> <strong>多语言切换</strong> <p>语言切换通常也会和页面刷新、脚本初始化配合使用。</p> </figcaption> </figure> </div> </section>