所属产品: Mingcedar Studio DESIGNER

脚本作用域与参数传递 | Mingcedar Studio

说明脚本作用域、执行限制，以及页面导航和弹窗的参数发送、读取、类型转换与排错。

首次发布 2026-10-25T12:48:42.606140597Z 最近更新 2026-10-26T19:56:55.620345098Z

<div class="manual-doc-article manual-doc-article-section"><h2 id="script-scope-and-parameter-passing">功能: 脚本作用域与参数传递</h2>

说明脚本作用域、执行限制，以及页面导航和弹窗的参数发送、读取、类型转换与排错。

<h3 id="script-scope-and-parameter-passing-item-1">脚本位置与作用域</h3>

脚本位置决定作用域、执行时机及异步和写入权限。插件没有一个自动覆盖所有页面的全局脚本文档。

<ul>

<li>Page Script：只属于当前页；顶层 var、let、const、class、function 可供同页动画和表达式引用。</li>

<li>hqVisuDesignerPageReady(ctx)：页面运行时准备完成后执行一次，适合初始化组件；动画首轮就需要的常量和函数仍放 Page Script 顶层。</li>

<li>Setup Script：只为当前这一条行为准备变量和中间结果，不是页面全局区。</li>

<li>Condition / Value / Display Text / Fill / Border / Visibility / Source value：同步表达式位置，必须立即返回一个结果。</li>

<li>Click / Hover / Press-Release Script：事件触发的完整脚本体，可写多行逻辑；WriteTag 只允许真实 Click、Press 或 Release，Hover 不允许设备写入。</li>

</ul>

<li><a href="/ppt/manual/design-reuse-guide/">动手练习：复用方式与参数</a></li>

<li><a href="/ppt/manual/recipe-popup-selection/">动手练习：弹窗选设备并返回</a></li>

</ul>

</article>

<h3 id="script-scope-and-parameter-passing-item-2">动画脚本的推荐拆分方式</h3>

同页共享的 Tag 前缀、量程和换算函数放 Page Script。具有 Setup Script 的颜色或文本行为可在其中准备局部结果。当前 Move、Rotate、Scale 编辑器没有 Setup Script 或 Post Operations 输入区：读取方法和换算表达式直接写入 Source value 或 Rotation input，需要复用的函数放 Page Script。

const tankTagPrefix = "PLC_LINE01.TANK01";

function percent(value, min, max) {

return Math.max(0, Math.min(100, (value - min) * 100 / (max - min)));

}

// Scale 的 Source value

percent(ReadTagDouble(tankTagPrefix + ".LEVEL", 0), 0, 10)

// Source minimum / maximum：0 / 100

// Limit minimum / maximum：0 / 100

// At limit minimum / maximum：0 / 1

// Moving edge：Top</code></pre></div>

</article>

<h3 id="script-scope-and-parameter-passing-item-3">同步、异步与写入边界</h3>

表达式位置不能直接放 fetch、Promise、setTimeout 或 setInterval，因为动画求值必须立即得到结果。异步准备放 Page Script 的 async 函数、hqVisuDesignerPageReady、Click Script 或 Hover Script，再把结果写入当前页变量或宿主数据源供动画读取。await 只能在 async 函数内部；顶层 await 和 import/export 模块语法不支持。设备写入必须来自真实用户点击、按下或释放，并继续接受宿主权限、确认、原因和审计控制。

</article>

<h3 id="script-scope-and-parameter-passing-item-4">页面导航传参：支持内容</h3>

在 Open Link 中选择 Internal page 后，可通过 Parameters (optional) 传参。其他 Destination 按所选目标填写对应字段。脚本传参使用 hqVisuDesigner.openPage 的第二个参数。参数支持字符串、数字、布尔值和 null；目标页按字符串读取，null 读取为空字符串。

<ul>

<li>parameters 必须是数组，每项形如 { key, value }。</li>

<li>数组保留顺序和重复 Key；普通对象不是 openPage 的正式参数格式。</li>

<li>frameTarget 支持 frame、fullscreen、_blank；openInNewWindow: true 等同 _blank。</li>

<li>同包页面使用 openPage；跨包使用 openScreen(screenCode)，通用 Jump Parameters 不用于保证跨画面包传参。</li>

<li>外部 Website / File URL 参数会进入 URL 查询部分，目标系统按自己的查询参数规则读取。</li>

</ul>

<div class="manual-code" data-code-language="text"><div class="manual-code-toolbar">TextText<button type="button" data-copy-code data-copied="已复制" data-failed="请选中代码后复制" aria-label="复制代码: Text">复制代码</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>hqVisuDesigner.openPage("device_details", {

frameTarget: "frame",

parameters: [

{ key: "PLC", value: "PLC_LINE01" },

{ key: "Device", value: "PUMP_01" },

{ key: "Mode", value: 1 },

{ key: "Enabled", value: true }

]

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

</article>

<h3 id="script-scope-and-parameter-passing-item-5">目标页面读取与类型转换</h3>

目标页应在 Page Script 中读取参数，并在使用前验证。GetPageParameter 返回第一个同名值；GetPageParameterValues 返回全部同名值数组；GetPageParameters 按原始顺序返回全部 { key, value }。三者也都有 hqVisuDesigner 命名空间版本。读取值都是字符串，因此数值和布尔值必须显式转换，拼接 Tag 前先限制允许字符。

<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>var plc = GetPageParameter("PLC", "");

var device = GetPageParameter("Device", "");

var modeText = GetPageParameter("Mode", "0");

var enabledText = GetPageParameter("Enabled", "false");

if (!/^[A-Za-z0-9_-]{1,64}$/.test(plc) ||

!/^[A-Za-z0-9_-]{1,64}$/.test(device)) {

throw new Error("Invalid page parameter");

}

var mode = Number.parseInt(modeText, 10);

var enabled = enabledText === "true";

var statusTag = plc + "." + device + ".STATUS";</code></pre></div>

</article>

<h3 id="script-scope-and-parameter-passing-item-6">弹窗传参和关闭结果</h3>

Open Page as Popup 的静态输入框只接受 JSON object，不接受顶层数组。启用 Build page parameters with an expression 后，运行时表达式可返回对象或有序的 { key, value } 数组；需要重复 Key 时使用数组。目标弹窗页仍使用 GetPageParameter* 读取。Close Current Popup 的 Result expression 是从弹窗返回打开方的结果通道，可返回布尔值、数字、字符串或对象；它与打开时的页面查询参数是两个方向、两套用途。

</article>

<h3 id="script-scope-and-parameter-passing-item-7">参数数量、长度和安全限制</h3>

Runtime 最多保留 64 项导航参数；Key 最长 256 个字符，Value 最长 2048 个字符，非法项会被忽略。参数进入 URL 查询部分，不得传密码、令牌、权限证明、个人敏感数据或大块 JSON。Cookie、localStorage、sessionStorage 受同源、iframe 和宿主加载方式影响，不能作为正式跨页面参数协议。页面参数也不能扩大宿主授予的 Tag、页面或用户权限。

</article>

<h3 id="script-scope-and-parameter-passing-item-8">四类值的边界与排错顺序</h3>

模板变量、Runtime Variable、PLC Tag 和页面参数解决的是不同问题：模板变量在实例/导出阶段替换；Runtime Variable 只做当前页联动；PLC Tag 属于宿主数据层；页面参数只在打开目标页面时传递上下文。参数读取为空时依次检查目标类型是否支持、Key 大小写、parameters 是否为数组、是否超过限制、宿主是否接管导航、目标地址是否带查询参数，以及是否错误使用了跨包相对路径。

</article>

</div>