文档手册

脚本作用域与参数传递

HQ VISU Designer 没有一个自动覆盖所有页面的全局脚本文档。脚本放在哪里，决定它能被谁使用、什么时候执行以及能否进行异步和设备写入。

功能

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

统一说明 Page Script、行为 Definition、动画表达式和交互脚本各自的作用域与执行边界，并给出 Open Link、openPage、页面弹窗的完整传参、读取、类型、限制和排错方法。

先分清五种脚本位置

HQ VISU Designer 没有一个自动覆盖所有页面的全局脚本文档。脚本放在哪里，决定它能被谁使用、什么时候执行以及能否进行异步和设备写入。

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

动画脚本的推荐拆分方式

同页多条动画共享的 Tag 前缀、量程、换算函数和格式化函数放 Page Script；某一条行为自己的读值与中间计算放 Definition；输出字段只保留最终表达式。这样既能复用，又能在行为编辑器里直接看出最终结果。

// 当前页 Page Script：同页共享
const pumpTagPrefix = "PLC_LINE01.PUMP01";
function percent(value, min, max) {
  return Math.max(0, Math.min(100, (value - min) * 100 / (max - min)));
}

// Scale 的 Definition：仅当前行为
var level = ReadTagDouble(pumpTagPrefix + ".LEVEL", 0);
var levelPercent = percent(level, 0, 10);

// Scale 的 Source Value：只返回结果
levelPercent

同步、异步与写入边界

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

页面导航传参：支持内容

Open Link 的 Presentation Page、File / URL、Website 支持 Jump Parameters；System Screen 和 Script Action 不直接显示参数区。脚本传参使用 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，动态模式用表达式返回对象。顶层数组无效，对象也不能表达重复 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 是否为数组、是否超过限制、宿主是否接管导航、目标地址是否带查询参数，以及是否错误使用了跨包相对路径。