所属产品: Mingcedar Studio DESIGNER

完整功能入口与脚本方法索引 | Mingcedar Studio

按功能区、行为、内置模板和脚本方法查找配置入口，并说明各方法适用的运行位置。

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

<div class="manual-doc-article manual-doc-article-section"><h2 id="capability-reference">能力索引: 完整功能入口与脚本方法索引</h2>

按功能区、行为、内置模板和脚本方法查找配置入口，并说明各方法适用的运行位置。

<h3 id="capability-reference-item-1">按任务选择入口</h3>

<p>Behavior Browser 管理行为，Templates 管理控件与模板，Page Script 管理同页共享函数和初始化。初次使用先完成单页制作、导出与运行验证；PowerPoint 原生特效范围见安装与导出章节。</p>

<ul>

<li>初次使用：先读“推荐上手路线”，再按行为章节的字段与例子操作。</li>

<li>熟手：按行为名称、内置模板或函数名定位，优先核对输入类型和运行位置。</li>

<li>开发者：只使用本手册列出的运行时脚本方法，并区分浏览器原生方法。请求已接受不等于现场写入或下载已完成。</li>

</ul>

</article>

<h3 id="capability-reference-item-2">运行位置与调用边界</h3>

<p>Page Script 的顶层声明和函数供当前页复用；Setup Script 准备当前行为的数据；Condition、Value、Display Text 返回同步结果。设备写入应由用户点击或按下/释放操作触发；Hover Script、Page Script 和 Setup Script 不用于发起 PLC 写入。异步逻辑放在交互脚本的 async 函数内，需要同步结果的字段不能返回 Promise。</p>

<ul>

<li>支持现代 ECMAScript 2022；不支持脚本文档的 import/export 和顶层 await。</li>

<li>组件初始化放 window.hqVisuDesignerPageReady = function(ctx) { ... }；回调中的 ctx 提供 presentation、page、hqVisuDesigner。</li>

<li>页面脚本不会自动成为跨页全局脚本。不要用无限循环轮询 Tag；定时器和网络调用需要明确频率、退出及失败处理。</li>

</ul>

</article>

<h3 id="capability-reference-item-3">Tag 读取：标量、JSON、日期时间和质量</h3>

<p>名称可由字符串、页面变量或模板参数生成，函数返回数据值。动态名称须在宿主允许的读范围内；显式设置 fallback，区分无效数据与正常值。</p>

<ul>

<li>ReadTagBoolean(name, fallback)、ReadTagInteger(name, fallback)、ReadTagDouble(name, fallback)、ReadTagString(name, fallback)：按目标类型读取。</li>

<li>ReadTagJson(name, fallback)：读取解析后的 JSON 值。ReadTagDateTime(name, fallback)：返回 Date 或 fallback；普通时间戳按项目时区显示，PLC 的 DATE_AND_TIME/DTL/LDT 是无时区日历值，不能推定为 UTC 时刻再直接做本地时区转换。</li>

<li>ReadCalculatedTag(name, fallback)：按保存名读取只读计算 Tag，不加 PLC 前缀；无数据时默认 null。</li>

<li>ReadTagQuality(name, fallback)、ReadTagQualityGood(name)：读取 good/bad 质量或判断 good；质量与工艺真假是两件事。</li>

<li>ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)：精确 tag[bit] 语法，位号 0–31，方括号内不加空格。</li>

<li>ReadTag(name) 是较底层的通用读取入口；业务脚本优先使用上述带类型的方法。</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar"><span>JavaScript</span><span class="manual-code-tools"><small>JavaScript</small><button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button><span class="manual-code-status" role="status"></span></span></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><span class="line"><span style="color:#D73A49">const</span><span style="color:#005CC5"> report</span><span style="color:#D73A49"> =</span><span style="color:#6F42C1"> ReadTagJson</span><span style="color:#24292E">(</span><span style="color:#032F62">"PLC_LINE01.REPORT01.SUMMARY"</span><span style="color:#24292E">, </span><span style="color:#005CC5">null</span><span style="color:#24292E">);</span></span>

<span class="line"><span style="color:#D73A49">const</span><span style="color:#005CC5"> updatedAt</span><span style="color:#D73A49"> =</span><span style="color:#6F42C1"> ReadTagDateTime</span><span style="color:#24292E">(</span><span style="color:#032F62">"PLC_LINE01.REPORT01.UPDATED_AT"</span><span style="color:#24292E">, </span><span style="color:#005CC5">null</span><span style="color:#24292E">);</span></span>

<span class="line"><span style="color:#D73A49">const</span><span style="color:#005CC5"> hasTime</span><span style="color:#D73A49"> =</span><span style="color:#24292E"> updatedAt </span><span style="color:#D73A49">instanceof</span><span style="color:#6F42C1"> Date</span><span style="color:#24292E">; </span><span style="color:#6A737D">// 显示前先确认 Tag 的日期时间类型语义</span></span></code></pre></div>

</article>

<h3 id="capability-reference-item-4">Tag 写入：类型、位操作和完成结果</h3>

<p>仅在真实用户动作中调用。宿主检查权限、确认和原因，并处理写入；返回可能异步，不代表 PLC 已生效。</p>

<ul>

<li>WriteTagBoolean(name, value, options?)、WriteTagInteger(name, value, options?)、WriteTagDouble(name, value, options?)：布尔、整数和浮点数须匹配目标类型。</li>

<li>WriteTagString(name, value, options?)、WriteTagJson(name, value, options?)：JSON 写入传对象、数组等兼容值，不用预先 JSON.stringify。</li>

<li>WriteTagDateTime(name, value, options?)：可传 Date，运行时按目标 Tag 元数据序列化；字符串须符合宿主日期时间约定。</li>

<li>WriteTagBit(parentName, bitIndex, action, options?)：action 为 Set、Reset 或 Toggle；传父整数 Tag 与独立位号，不向 name[bit] 发普通写入。</li>

<li>WriteTag 是通用写入入口；项目脚本优先采用具体 WriteTag 类型方法。options 的填写规则由运行平台定义；它不能绕过访问权限。</li>

<li>hqVisuDesigner.writeVariable(name, value)：设置运行时变量，不能等同于 PLC 写入。</li>

</ul>

</article>

<h3 id="capability-reference-item-5">输入模板、页面参数与浏览器存储</h3>

<p>template.getValue(componentName) 读取当前页输入模板的草稿显示值；组件名称须唯一，找不到时会报错，数字输入应显式 Number(...) 并校验。页面跳转参数是文本，与模板的 <Name> 替换参数、运行时变量、PLC Tag 分属不同作用域。</p>

<ul>

<li>GetPageParameter(key, fallback)：首个值；GetPageParameterValues(key)：同名重复值数组；GetPageParameters()：按原顺序返回全部参数。</li>

<li>对应小写入口：hqVisuDesigner.getPageParameter / getPageParameterValues / getPageParameters。</li>

<li>ReadBrowserStorage(key, fallback, storageType?)、WriteBrowserStorage(key, value, storageType?)、RemoveBrowserStorage(key, storageType?)：默认 local，传 "session" 使用 sessionStorage；仅适用于同源浏览器存储。小写等价入口为 hqVisuDesigner.readBrowserStorage / writeBrowserStorage / removeBrowserStorage。</li>

<li>ReadBrowserStorage 的 fallback 决定解码类型：{} 读取对象，0 读取数值，false 读取布尔，否则默认字符串。WriteBrowserStorage 即使失败也可能返回传入值，不能用返回值断言成功；RemoveBrowserStorage 返回布尔值。存储可能不可用，错误线索为 hqVisuDesignerLastStorageError；不要存密码，也不能替代服务器持久化。</li>

<li>Quick Methods 的 Template Input / Get / <组件名> 按当前页实际输入模板动态生成。</li>

<li>HQVISU_PAGE_PARAMETERS（数组）与 HQVISU_PAGE_RESOURCE_SCOPE（对象）是供审阅的静态输入/资源范围声明；不会自动读取 cookie、给变量赋值或代替 GetPageParameter，也不授予 Tag 访问权限。</li>

</ul>

</article>

<h3 id="capability-reference-item-6">组件查找与更新</h3>

<p>方法位于 hqVisuDesigner，nameOrId 填当前页唯一组件名或 Shape ID。更新后在运行页检查与既有行为的协同。</p>

<ul>

<li>findComponent(nameOrId)：查找导出组件元素；getComponentData(nameOrId)：读取该组件的导出配置。</li>

<li>setComponentText(nameOrId, value)、setComponentFill(nameOrId, color)、setComponentBorder(nameOrId, color)：更新文字、填充和边框。</li>

<li>setComponentVisible(nameOrId, visible)：控制显隐；setComponentLayout(nameOrId, {x, y, width, height, angle})：按页面坐标更新布局。</li>

<li>refreshView()：要求运行时重新应用当前状态；不要以高频手动刷新替代正常数据订阅。</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar"><span>JavaScript</span><span class="manual-code-tools"><small>JavaScript</small><button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button><span class="manual-code-status" role="status"></span></span></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><span class="line"><span style="color:#D73A49">const</span><span style="color:#005CC5"> title</span><span style="color:#D73A49"> =</span><span style="color:#24292E"> hqVisuDesigner.</span><span style="color:#6F42C1">getComponentData</span><span style="color:#24292E">(</span><span style="color:#032F62">"PumpTitle"</span><span style="color:#24292E">);</span></span>

<span class="line"><span style="color:#24292E">hqVisuDesigner.</span><span style="color:#6F42C1">setComponentLayout</span><span style="color:#24292E">(</span><span style="color:#032F62">"PumpTitle"</span><span style="color:#24292E">, { x: </span><span style="color:#005CC5">40</span><span style="color:#24292E">, y: </span><span style="color:#005CC5">24</span><span style="color:#24292E">, width: </span><span style="color:#005CC5">300</span><span style="color:#24292E">, height: </span><span style="color:#005CC5">36</span><span style="color:#24292E">, angle: </span><span style="color:#005CC5">0</span><span style="color:#24292E"> });</span></span></code></pre></div>

</article>

<h3 id="capability-reference-item-7">导航、弹窗与诊断</h3>

<p>页面名称或 Page Code 应来自当前画面包的页面映射；跨画面使用宿主管理的 screenCode。导航方法可能由宿主异步处理，不能根据调用本身判断跳转成功。</p>

<ul>

<li>hqVisuDesigner.openPage(page, options?)：同包跳页；options 可携带 parameters、frameTarget、navigationMode，详见“脚本作用域与传参”。</li>

<li>hqVisuDesigner.openScreen(screenCode)：跨画面包；hqVisuDesigner.openWebsite(url, optionsOrNewWindow?)：打开有效外链。</li>

<li>hqVisuDesigner.openAndon(page, options?)：运行时提供的全屏/Andon 导航入口；普通配置优先使用 Open Link 的显示方式。</li>

<li>HQ.popup.open(pageCode, options?) 与 HQ.popup.close({result: value})：运行时弹窗接口；打开返回等待关闭的 Promise，参数写法与关闭后的返回值见弹窗章节。</li>

<li>hqVisuDesigner.openDiagnosis({PLC, ID, DiagnosisControl, GroupRightIndex})：请求宿主打开诊断窗口；诊断内容和权限由宿主管理。</li>

</ul>

</article>

<h3 id="capability-reference-item-8">语言、当前用户与时间</h3>

<p>翻译来自运行时语言字典，当前用户来自宿主身份。时间方法读取操作员浏览器的本地时间，不能视为 PLC 时间或服务器审计时间。</p>

<ul>

<li>GetText(key, fallback?)：命中翻译时返回译文；缺失时返回显式 fallback；未提供 fallback 时返回 key。getText/gettext 为兼容别名，推荐统一使用 GetText。</li>

<li>hqVisuDesigner.currentLanguage()：当前语言；hqVisuDesigner.useLanguage(language)：切换语言并刷新状态；hqVisuDesigner.getText 与 GetText 对应。</li>

<li>GetCurrentUsername()：读取宿主当前用户名；它是显示上下文，不是权限校验。</li>

<li>GetCurrentTime(format?) 默认 HH:mm:ss；GetCurrentDate(format?) 默认 yyyy-MM-dd；GetCurrentDateTime(format?) 默认 yyyy-MM-dd HH:mm:ss；GetCurrentDateObject() 返回 Date。</li>

<li>FormatDateTime(value, format?)：支持 yyyy/YYYY、MM、dd/DD、HH、mm、ss。非法日期会回退当前时间，所以业务上应先校验输入，不能以格式化成功判断数据正确。</li>

<li>对应小写入口：currentUsername、currentTime、currentDate、currentDateTime、currentDateObject、formatDateTime 均位于 hqVisuDesigner。</li>

</ul>

<div class="manual-code" data-code-language="javascript"><div class="manual-code-toolbar"><span>JavaScript</span><span class="manual-code-tools"><small>JavaScript</small><button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: JavaScript">复制代码</button><span class="manual-code-status" role="status"></span></span></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code><span class="line"><span style="color:#D73A49">const</span><span style="color:#005CC5"> caption</span><span style="color:#D73A49"> =</span><span style="color:#6F42C1"> GetText</span><span style="color:#24292E">(</span><span style="color:#032F62">"screen.pump.ready"</span><span style="color:#24292E">, </span><span style="color:#032F62">"就绪"</span><span style="color:#24292E">);</span></span>

<span class="line"><span style="color:#D73A49">const</span><span style="color:#005CC5"> operator</span><span style="color:#D73A49"> =</span><span style="color:#6F42C1"> GetCurrentUsername</span><span style="color:#24292E">();</span></span>

<span class="line"><span style="color:#24292E">hqVisuDesigner.</span><span style="color:#6F42C1">setComponentText</span><span style="color:#24292E">(</span><span style="color:#032F62">"OperatorText"</span><span style="color:#24292E">, </span><span style="color:#032F62">`${</span><span style="color:#24292E">caption</span><span style="color:#032F62">} / ${</span><span style="color:#24292E">operator</span><span style="color:#032F62">} / ${</span><span style="color:#6F42C1">GetCurrentTime</span><span style="color:#032F62">()</span><span style="color:#032F62">}`</span><span style="color:#24292E">);</span></span></code></pre></div>

</article>

<h3 id="capability-reference-item-9">报警查询与页面报警栏</h3>

<p>GetAlarm 系列查询当前活跃报警是否存在匹配，返回布尔结果，不查询历史报警。完整 Tag 名与组编码不要混用。</p>

<ul>

<li>GetAlarmTags(["PLC_LINE01.PUMP01.ALARM"])：完整 Tag 名。</li>

<li>GetAlarmPlcCodes(["PLC_LINE01"])：PLC/设备编码。</li>

<li>GetAlarmFunctionGroupCodes、GetAlarmDeviceGroupCodes、GetAlarmSignalGroupCodes：使用带设备前缀的组编码数组。</li>

<li>HQVISU_PAGE_ALARM 配置当前页报警栏；getPageAlarm(fallback?) 读取配置。showWindow 控制显示，tags/plcCodes/functionGroupCodes/deviceGroupCodes/signalGroupCodes 控制范围。</li>

<li>hqVisuDesigner.getAlarmTags / getAlarmPlcCodes / getAlarmFunctionGroupCodes / getAlarmDeviceGroupCodes / getAlarmSignalGroupCodes 是对应入口。</li>

<li>内置 Alarm 模板是页面中的报警控件，与页面报警栏分别配置；报警确认、历史和权限依赖宿主，不能从存在一个显示模板推定都支持。</li>

</ul>

</article>

<h3 id="capability-reference-item-10">声音与浏览器数据下载</h3>

<p>PlaySound(fileName, loop?) 播放根目录声音，如 PlaySound("alarm.mp3", false)。布尔返回值仅表示请求是否接受，仍受浏览器声音权限限制。不要在持续求值的表达式中重复调用。</p>

<ul>

<li>hqVisuDesigner.playSound 与 PlaySound 对应。页面脚本可以尝试自动播放，浏览器仍可能阻止；应验证实际操作员浏览器的声音许可。</li>

<li>ExportJson(value, fileName?)：导出可序列化值；ExportTable(componentNameOrId, fileName?, format?)：导出当前内置表格的显示文本。</li>

<li>ExportTags(nameOrNames, fileName?, format?)：导出已经可读的 Tag 当前值与质量。格式支持 csv/json/xlsx，excel 是 xlsx 的别名。</li>

<li>导出从真实用户点击发起；返回文件名表示发起下载，不保证落盘。表格、Tag 范围、默认格式和失败处理见“运行时数据导出”。</li>

<li>hqVisuDesigner.exportJson / exportTable / exportTags 是对应入口；这些下载与制作端 Export HTML 的画面包导出不同。</li>

</ul>

</article>

<h3 id="capability-reference-item-11">Quick Methods 中的浏览器与 JavaScript 片段</h3>

<p>Quick Methods 也提供标准 JavaScript 写法。这些片段是脚本辅助，不是额外的设备协议或宿主服务。fetch 仍受网络、CORS、认证和浏览器权限限制；alert/confirm/prompt 宜放在用户动作中。</p>

<ul>

<li>浏览器控制台记录、fetch、setTimeout、setInterval、requestAnimationFrame、document.getElementById。</li>

<li>alert、confirm、prompt；if/else、for、while、switch、try/catch；命名函数、箭头函数、async 函数。</li>

<li>三元、??、?.、模板字符串；includes/filter；Math.min/max/abs/round、范围映射；对象解构；动态 Tag 名与位名称拼接。</li>

<li>方法库会按表达式、Setup Script、交互脚本等位置筛选可插入片段；可搜索函数或类别，不要把完整语句粘贴进只接受一个表达式的字段。</li>

</ul>

</article>

<h3 id="capability-reference-item-12">脚本接口使用范围</h3>

<p>画面脚本仅使用本手册公开方法；运行时中的平台集成成员不属于画面交互接口。</p>

<ul>

<li>读取 Tag、更新组件或写入设备时，使用对应的文档化方法，并核对权限与运行结果。</li>

<li>不要直接修改运行时状态对象来模拟设备写入或权限变更。</li>

<li>平台接入与页面生命周期成员不属于普通画面脚本的调用范围。</li>

</ul>

</article>

<h3 id="capability-reference-item-13">功能区入口核对表</h3>

<p>按入口查找对应章节。这里也列出复用的 PowerPoint 原生命令；原生命令的可用性遵循 PowerPoint 选择状态。</p>

<ul>

<li>Ungroup (PowerPoint context menu)</li>

<li>Browse</li>

<li>Insert Shapes</li>

<li>Format Painter</li>

<li>Straight Connector</li>

<li>Straight Connector Arrow</li>

<li>Align Left</li>

<li>Align Center</li>

<li>Align Right</li>

<li>Align Top</li>

<li>Align Middle</li>

<li>Align Bottom</li>

<li>Distribute H</li>

<li>Distribute V</li>

<li>Rotate Left 90°</li>

<li>Rotate Right 90°</li>

<li>Bring Forward</li>

<li>Bring To Front</li>

<li>Group</li>

<li>Ungroup</li>

<li>Page Ratio</li>

<li>Page Script</li>

<li>Library</li>

<li>Edit Instance</li>

<li>Update Template</li>

<li>Batch Replace</li>

<li>Export HTML</li>

<li>History</li>

<li>Refresh</li>

<li>License</li>

<li>About</li>

<li>Status: Add-in Version</li>

<li>Status: PowerPoint Version</li>

<li>Status: License</li>

</ul>

</article>

<p>按界面显示名称查找行为；每个行为都有对应的操作章节。</p>

<ul>

<li>Blink Color</li>

<li>Range Color</li>

<li>Script Color</li>

<li>Discrete Color</li>

<li>State Color</li>

<li>Multi-State Color</li>

<li>Rotate</li>

<li>Scale</li>

<li>Set Variable on Click</li>

<li>Open Diagnosis</li>

<li>Open Page as Popup</li>

<li>Close Current Popup</li>

<li>Write Tag</li>

<li>Write Tag Bit</li>

<li>Click Script</li>

<li>Hover Script</li>

<li>Press/Release Script</li>

<li>Script Text</li>

<li>Localized Text</li>

</ul>

</article>

<p>输入、数据表格、键盘、报警、视频和图表模板；自制模板库提供另一种复用方式。</p>

<ul>

<li>Input</li>

<li>Table</li>

<li>Keyboard</li>

<li>Alarm</li>

<li>Video</li>

<li>Line Chart</li>

<li>Bar Chart</li>

<li>Gauge</li>

<li>JSON Chart</li>

</ul>

</article>

<h3 id="capability-reference-item-16">Quick Methods 搜索类别</h3>

<p>以下为方法库中的实际标题，按类别合并去重。输入模板条目随当前页组件动态生成。</p>

<ul>

<li>Alarm: Device Groups · Function Groups · PLC · Signal Groups · Tags</li>

<li>Animation Frame: Run Next Frame</li>

<li>Array: Contains · Filter</li>

<li>Browser Storage: Read · Remove · Write</li>

<li>Component: Find · Get Data · Set Border · Set Fill · Set Layout · Set Text · Set Visibility</li>

<li>Console: Log</li>

<li>Control Flow: For Each Item · If · If Else · Switch · Try Catch · While</li>

<li>Date And Time: Current Date · Current Date Object · Current Date Time · Current Time · Format</li>

<li>Export: JSON · Table CSV · Table Excel · Table JSON · Tags</li>

<li>Expression: Nullish Fallback · Optional Property · Template String · Ternary</li>

<li>Function: Arrow Function · Async Fetch JSON · Component Highlight · Named Function</li>

<li>Language: Current · Get Text · Switch</li>

<li>Lifecycle: Page Runtime Ready</li>

<li>Navigation: Open Page · Open Screen · Open Website</li>

<li>Network: Fetch JSON</li>

<li>Number: Absolute · Clamp · Map Range · Round 2 Decimals</li>

<li>Object: Destructure</li>

<li>Page Alarm: Configure · Read</li>

<li>Page Parameters: Declare Inputs And Read Scope · Read All · Read Repeated Values · Read Value</li>

<li>Sound: Play</li>

<li>Tag Quality: Is Good · Read</li>

<li>Tag Read: Bit Boolean · Boolean · Calculated Tag · Date Time · Double · Integer · JSON · String</li>

<li>Tag Reference: Build And Read · Build And Read Bit · Build Bit Name · Build Name</li>

<li>Template Input: Get / </li>

<li>Timer: Run Once · Run Repeatedly</li>

<li>User: Current Username</li>

<li>Condition: Combined · Invert Boolean · Numeric Compare · Range Compare</li>

<li>Definition: Number Variable · Read Multiple Tags · Stable Defaults · Text Variable</li>

<li>Dialog: Alert · Confirm · Prompt</li>

<li>Host: Open Diagnosis</li>

<li>Runtime Variable: Write</li>

<li>Tag Write: Boolean · Date Time · Double · Integer · Integer Bit · JSON · String</li>

</ul>

</article>

</div></div>