文档手册

脚本作用域与参数传递

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

功能文档修订：2026-10-21

功能: 脚本作用域与参数传递

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

脚本位置与作用域

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

Page Script：只属于当前页；顶层 var、let、const、class、function 可供同页动画和表达式引用。
hqVisuDesignerPageReady(ctx)：页面运行时准备完成后执行一次，适合初始化组件；动画首轮就需要的常量和函数仍放 Page Script 顶层。
Setup Script：只为当前这一条行为准备变量和中间结果，不是页面全局区。
Condition / Value / Display Text / Fill / Border / Visibility / Source value：同步表达式位置，必须立即返回一个结果。
Click / Hover / Press-Release Script：事件触发的完整脚本体，可写多行逻辑；WriteTag 只允许真实 Click、Press 或 Release，Hover 不允许设备写入。

动画脚本的推荐拆分方式

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

// 当前页 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

同步、异步与写入边界

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

页面导航传参：支持内容

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

parameters 必须是数组，每项形如 { key, value }。
数组保留顺序和重复 Key；普通对象不是 openPage 的正式参数格式。
frameTarget 支持 frame、fullscreen、_blank；openInNewWindow: true 等同 _blank。
同包页面使用 openPage；跨包使用 openScreen(screenCode)，通用 Jump Parameters 不用于保证跨画面包传参。
外部 Website / File URL 参数会进入 URL 查询部分，目标系统按自己的查询参数规则读取。

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 }
  ]
});

目标页面读取与类型转换

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

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";

弹窗传参和关闭结果

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

参数数量、长度和安全限制

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

四类值的边界与排错顺序

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