跳至主要内容
Mingcedar
中
Mingcedar / Mingcedar Studio
文档手册

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

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

能力索引文档修订：2026-10-21

能力索引: 完整功能入口与脚本方法索引

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

按任务选择入口

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

  • 初次使用：先读“推荐上手路线”，再按行为章节的字段与例子操作。
  • 熟手：按行为名称、内置模板或函数名定位，优先核对输入类型和运行位置。
  • 开发者：只使用本手册列出的运行时脚本方法，并区分浏览器原生方法。请求已接受不等于现场写入或下载已完成。

运行位置与调用边界

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

  • 支持现代 ECMAScript 2022；不支持脚本文档的 import/export 和顶层 await。
  • 组件初始化放 window.hqVisuDesignerPageReady = function(ctx) { ... }；回调中的 ctx 提供 presentation、page、hqVisuDesigner。
  • 页面脚本不会自动成为跨页全局脚本。不要用无限循环轮询 Tag；定时器和网络调用需要明确频率、退出及失败处理。

Tag 读取：标量、JSON、日期时间和质量

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

  • ReadTagBoolean(name, fallback)、ReadTagInteger(name, fallback)、ReadTagDouble(name, fallback)、ReadTagString(name, fallback)：按目标类型读取。
  • ReadTagJson(name, fallback)：读取解析后的 JSON 值。ReadTagDateTime(name, fallback)：返回 Date 或 fallback；普通时间戳按项目时区显示，PLC 的 DATE_AND_TIME/DTL/LDT 是无时区日历值，不能推定为 UTC 时刻再直接做本地时区转换。
  • ReadCalculatedTag(name, fallback)：按保存名读取只读计算 Tag，不加 PLC 前缀；无数据时默认 null。
  • ReadTagQuality(name, fallback)、ReadTagQualityGood(name)：读取 good/bad 质量或判断 good；质量与工艺真假是两件事。
  • ReadTagBoolean("PLC_LINE01.PUMP01.STATUS[3]", false)：精确 tag[bit] 语法，位号 0–31，方括号内不加空格。
  • ReadTag(name) 是较底层的通用读取入口；业务脚本优先使用上述带类型的方法。
JavaScriptJavaScript
const report = ReadTagJson("PLC_LINE01.REPORT01.SUMMARY", null);
const updatedAt = ReadTagDateTime("PLC_LINE01.REPORT01.UPDATED_AT", null);
const hasTime = updatedAt instanceof Date; // 显示前先确认 Tag 的日期时间类型语义

Tag 写入：类型、位操作和完成结果

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

  • WriteTagBoolean(name, value, options?)、WriteTagInteger(name, value, options?)、WriteTagDouble(name, value, options?)：布尔、整数和浮点数须匹配目标类型。
  • WriteTagString(name, value, options?)、WriteTagJson(name, value, options?)：JSON 写入传对象、数组等兼容值，不用预先 JSON.stringify。
  • WriteTagDateTime(name, value, options?)：可传 Date，运行时按目标 Tag 元数据序列化；字符串须符合宿主日期时间约定。
  • WriteTagBit(parentName, bitIndex, action, options?)：action 为 Set、Reset 或 Toggle；传父整数 Tag 与独立位号，不向 name[bit] 发普通写入。
  • WriteTag 是通用写入入口；项目脚本优先采用具体 WriteTag 类型方法。options 的填写规则由运行平台定义；它不能绕过访问权限。
  • hqVisuDesigner.writeVariable(name, value)：设置运行时变量，不能等同于 PLC 写入。

输入模板、页面参数与浏览器存储

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

  • GetPageParameter(key, fallback)：首个值；GetPageParameterValues(key)：同名重复值数组；GetPageParameters()：按原顺序返回全部参数。
  • 对应小写入口：hqVisuDesigner.getPageParameter / getPageParameterValues / getPageParameters。
  • ReadBrowserStorage(key, fallback, storageType?)、WriteBrowserStorage(key, value, storageType?)、RemoveBrowserStorage(key, storageType?)：默认 local，传 "session" 使用 sessionStorage；仅适用于同源浏览器存储。小写等价入口为 hqVisuDesigner.readBrowserStorage / writeBrowserStorage / removeBrowserStorage。
  • ReadBrowserStorage 的 fallback 决定解码类型：{} 读取对象，0 读取数值，false 读取布尔，否则默认字符串。WriteBrowserStorage 即使失败也可能返回传入值，不能用返回值断言成功；RemoveBrowserStorage 返回布尔值。存储可能不可用，错误线索为 hqVisuDesignerLastStorageError；不要存密码，也不能替代服务器持久化。
  • Quick Methods 的 Template Input / Get / <组件名> 按当前页实际输入模板动态生成。
  • HQVISU_PAGE_PARAMETERS（数组）与 HQVISU_PAGE_RESOURCE_SCOPE（对象）是供审阅的静态输入/资源范围声明；不会自动读取 cookie、给变量赋值或代替 GetPageParameter，也不授予 Tag 访问权限。

组件查找与更新

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

  • findComponent(nameOrId)：查找导出组件元素；getComponentData(nameOrId)：读取该组件的导出配置。
  • setComponentText(nameOrId, value)、setComponentFill(nameOrId, color)、setComponentBorder(nameOrId, color)：更新文字、填充和边框。
  • setComponentVisible(nameOrId, visible)：控制显隐；setComponentLayout(nameOrId, {x, y, width, height, angle})：按页面坐标更新布局。
  • refreshView()：要求运行时重新应用当前状态；不要以高频手动刷新替代正常数据订阅。
JavaScriptJavaScript
const title = hqVisuDesigner.getComponentData("PumpTitle");
hqVisuDesigner.setComponentText("PumpTitle", "Line 01 / Pump 01");
hqVisuDesigner.setComponentLayout("PumpTitle", { x: 40, y: 24, width: 300, height: 36, angle: 0 });

导航、弹窗与诊断

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

  • hqVisuDesigner.openPage(page, options?)：同包跳页；options 可携带 parameters、frameTarget、navigationMode，详见“脚本作用域与传参”。
  • hqVisuDesigner.openScreen(screenCode)：跨画面包；hqVisuDesigner.openWebsite(url, optionsOrNewWindow?)：打开有效外链。
  • hqVisuDesigner.openAndon(page, options?)：运行时提供的全屏/Andon 导航入口；普通配置优先使用 Open Link 的显示方式。
  • HQ.popup.open(pageCode, options?) 与 HQ.popup.close({result: value})：运行时弹窗接口；打开返回等待关闭的 Promise，参数写法与关闭后的返回值见弹窗章节。
  • hqVisuDesigner.openDiagnosis({PLC, ID, DiagnosisControl, GroupRightIndex})：请求宿主打开诊断窗口；诊断内容和权限由宿主管理。

语言、当前用户与时间

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

  • GetText(key, fallback?)：命中翻译时返回译文；缺失时返回显式 fallback；未提供 fallback 时返回 key。getText/gettext 为兼容别名，推荐统一使用 GetText。
  • hqVisuDesigner.currentLanguage()：当前语言；hqVisuDesigner.useLanguage(language)：切换语言并刷新状态；hqVisuDesigner.getText 与 GetText 对应。
  • GetCurrentUsername()：读取宿主当前用户名；它是显示上下文，不是权限校验。
  • GetCurrentTime(format?) 默认 HH:mm:ss；GetCurrentDate(format?) 默认 yyyy-MM-dd；GetCurrentDateTime(format?) 默认 yyyy-MM-dd HH:mm:ss；GetCurrentDateObject() 返回 Date。
  • FormatDateTime(value, format?)：支持 yyyy/YYYY、MM、dd/DD、HH、mm、ss。非法日期会回退当前时间，所以业务上应先校验输入，不能以格式化成功判断数据正确。
  • 对应小写入口：currentUsername、currentTime、currentDate、currentDateTime、currentDateObject、formatDateTime 均位于 hqVisuDesigner。
JavaScriptJavaScript
const caption = GetText("screen.pump.ready", "就绪");
const operator = GetCurrentUsername();
hqVisuDesigner.setComponentText("OperatorText", `${caption} / ${operator} / ${GetCurrentTime()}`);

报警查询与页面报警栏

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

  • GetAlarmTags(["PLC_LINE01.PUMP01.ALARM"])：完整 Tag 名。
  • GetAlarmPlcCodes(["PLC_LINE01"])：PLC/设备编码。
  • GetAlarmFunctionGroupCodes、GetAlarmDeviceGroupCodes、GetAlarmSignalGroupCodes：使用带设备前缀的组编码数组。
  • HQVISU_PAGE_ALARM 配置当前页报警栏；getPageAlarm(fallback?) 读取配置。showWindow 控制显示，tags/plcCodes/functionGroupCodes/deviceGroupCodes/signalGroupCodes 控制范围。
  • hqVisuDesigner.getAlarmTags / getAlarmPlcCodes / getAlarmFunctionGroupCodes / getAlarmDeviceGroupCodes / getAlarmSignalGroupCodes 是对应入口。
  • 内置 Alarm 模板是页面中的报警控件，与页面报警栏分别配置；报警确认、历史和权限依赖宿主，不能从存在一个显示模板推定都支持。

声音与浏览器数据下载

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

  • hqVisuDesigner.playSound 与 PlaySound 对应。页面脚本可以尝试自动播放，浏览器仍可能阻止；应验证实际操作员浏览器的声音许可。
  • ExportJson(value, fileName?)：导出可序列化值；ExportTable(componentNameOrId, fileName?, format?)：导出当前内置表格的显示文本。
  • ExportTags(nameOrNames, fileName?, format?)：导出已经可读的 Tag 当前值与质量。格式支持 csv/json/xlsx，excel 是 xlsx 的别名。
  • 导出从真实用户点击发起；返回文件名表示发起下载，不保证落盘。表格、Tag 范围、默认格式和失败处理见“运行时数据导出”。
  • hqVisuDesigner.exportJson / exportTable / exportTags 是对应入口；这些下载与制作端 Export HTML 的画面包导出不同。

Quick Methods 中的浏览器与 JavaScript 片段

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

  • 浏览器控制台记录、fetch、setTimeout、setInterval、requestAnimationFrame、document.getElementById。
  • alert、confirm、prompt；if/else、for、while、switch、try/catch；命名函数、箭头函数、async 函数。
  • 三元、??、?.、模板字符串；includes/filter；Math.min/max/abs/round、范围映射；对象解构；动态 Tag 名与位名称拼接。
  • 方法库会按表达式、Setup Script、交互脚本等位置筛选可插入片段；可搜索函数或类别，不要把完整语句粘贴进只接受一个表达式的字段。

脚本接口使用范围

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

  • 读取 Tag、更新组件或写入设备时，使用对应的文档化方法，并核对权限与运行结果。
  • 不要直接修改运行时状态对象来模拟设备写入或权限变更。
  • 平台接入与页面生命周期成员不属于普通画面脚本的调用范围。

功能区入口核对表

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

  • Ungroup (PowerPoint context menu)
  • Browse
  • Insert Shapes
  • Format Painter
  • Straight Connector
  • Straight Connector Arrow
  • Align Left
  • Align Center
  • Align Right
  • Align Top
  • Align Middle
  • Align Bottom
  • Distribute H
  • Distribute V
  • Rotate Left 90°
  • Rotate Right 90°
  • Bring Forward
  • Bring To Front
  • Group
  • Ungroup
  • Page Ratio
  • Nav Path
  • Page Script
  • Library
  • Edit Instance
  • Update Template
  • Batch Replace
  • Export HTML
  • This Page
  • History
  • Refresh
  • License
  • About
  • Status: Add-in Version
  • Status: PowerPoint Version
  • Status: License

行为目录

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

  • Blink Color
  • Range Color
  • Script Color
  • Discrete Color
  • State Color
  • Multi-State Color
  • Move
  • Rotate
  • Scale
  • Set Variable on Click
  • Open Diagnosis
  • Open Link
  • Open Page as Popup
  • Close Current Popup
  • Write Tag
  • Write Tag Bit
  • Click Script
  • Hover Script
  • Press/Release Script
  • Script Text
  • Tag Text
  • Localized Text

内置模板

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

  • Input
  • Table
  • Keyboard
  • Alarm
  • Video
  • Line Chart
  • Bar Chart
  • Gauge
  • JSON Chart

Quick Methods 搜索类别

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

  • Alarm: Device Groups · Function Groups · PLC · Signal Groups · Tags
  • Animation Frame: Run Next Frame
  • Array: Contains · Filter
  • Browser Storage: Read · Remove · Write
  • Component: Find · Get Data · Set Border · Set Fill · Set Layout · Set Text · Set Visibility
  • Console: Log
  • Control Flow: For Each Item · If · If Else · Switch · Try Catch · While
  • DOM: Find By ID
  • Date And Time: Current Date · Current Date Object · Current Date Time · Current Time · Format
  • Export: JSON · Table CSV · Table Excel · Table JSON · Tags
  • Expression: Nullish Fallback · Optional Property · Template String · Ternary
  • Function: Arrow Function · Async Fetch JSON · Component Highlight · Named Function
  • Language: Current · Get Text · Switch
  • Lifecycle: Page Runtime Ready
  • Navigation: Open Page · Open Screen · Open Website
  • Network: Fetch JSON
  • Number: Absolute · Clamp · Map Range · Round 2 Decimals
  • Object: Destructure
  • Page Alarm: Configure · Read
  • Page Parameters: Declare Inputs And Read Scope · Read All · Read Repeated Values · Read Value
  • Sound: Play
  • Tag Quality: Is Good · Read
  • Tag Read: Bit Boolean · Boolean · Calculated Tag · Date Time · Double · Integer · JSON · String
  • Tag Reference: Build And Read · Build And Read Bit · Build Bit Name · Build Name
  • Template Input: Get /
  • Timer: Run Once · Run Repeatedly
  • User: Current Username
  • Condition: Combined · Invert Boolean · Numeric Compare · Range Compare
  • Definition: Number Variable · Read Multiple Tags · Stable Defaults · Text Variable
  • Dialog: Alert · Confirm · Prompt
  • Host: Open Diagnosis
  • Runtime Variable: Write
  • Tag Write: Boolean · Date Time · Double · Integer · Integer Bit · JSON · String

再次点击图片或按 Esc 关闭