页面变量

变量类型概览

常见的页面变量来源包括：

• 外部变量：值从 URL 参数或嵌入场景的传参中获取，例如报表跳转到 UX 页面时携带的 req_id。

• 常规变量：在页面中设置默认值，用于保存页面内的状态；接收外部跳转参数时应选择“外部”来源。

• 变量元素/模型变量：从变量元素或 DeepModel 中取数，作为页面的统一上下文（如当前年度、当前实体）。

外部变量

增加外部变量的主要目的为：

1. 定义页面参数，便于外部读取，进行 UI 配置，无需记忆两边的 key。

2. 在数据源、控件和动作中统一通过变量选择器或 $var.变量编码 使用传入值。

在【页面变量】中新增变量，填写变量编码，来源选择【外部】。业务主键、流程实例 ID、任务实例 ID 使用 string；布尔开关按需要使用 boolean，并保持来源值与判断条件的类型一致。保存 UX 后，再在来源页面或工作流中加载参数并为同名参数赋值。

例如先声明外部变量 req_id，来源页面为同名参数传入业务主键，再在目标页面的数据源查询条件中选择变量 req_id，对应表达式为 $var.req_id。声明变量、来源赋值、页面内引用是三个独立配置步骤；仅新增变量不会自动绑定数据源或控件。

👉点击跳转：外部变量应用详情见-如何配置清单表的跳转

变量元素

UX 中支持添加变量元素，并且将变量元素中的成员作为 UX 中的变量进行使用。

变量元素成员支持配置编码、名称、数据格式、是否多选、是否启用维度表达式等信息，用于描述变量的含义和取值方式。

当页面加载时，页面会根据已关联的变量元素和 DeepModel 变量自动拉取当前值，填充到变量的数据中，此后即可在表达式中通过 $var.变量编码 进行使用。

运行时结构与表达式访问

在运行时，页面变量会以统一的对象挂载到表达式上下文中（在表达式编辑器中通常以“变量”类型出现），常见能力包括：

• 统一保存所有变量成员的最终值，是 $var.变量编码 实际读取的数据来源。

• 记录变量元素和外部变量的字段信息，便于在编辑器中选择。

• 管理变量取数的加载状态与异常信息，便于在页面上做相应处理。

表达式中的常见用法示例：

• 使用变量元素中的成员：$var.Year、$var.Entity

• 使用外部变量并参与计算：$var.req_id === $components.req_id_input.value

通过外部变量与变量元素的组合，可以在页面中统一管理“来自 URL / 嵌入场景”以及“来自模型/变量元素”的上下文信息。