设置界面变量

界面变量用于在低代码应用的用户界面中临时保存数据，让不同组件、事件和页面可以共享同一个值。例如，可以记录用户当前选中的选项，再让文本、表单或页面跳转动作读取该值。

界面变量属于用户界面搭建器，与业务逻辑中的应用变量、用户变量和系统变量不是同一类配置。需要了解业务逻辑变量时，请参阅为低代码应用设置变量。

进入界面变量页面

1. 进入 AI 编程 > 项目管理。
2. 打开一个低代码应用。
3. 在编辑器顶部切换到 用户界面。
4. 在左侧面板单击 数据。
5. 展开 变量。

创建界面变量

1. 在 数据 > 变量 标题右侧单击 +。
2. 在新建的变量行中填写变量名。
3. 根据需要填写默认值。
4. 等待页面顶部显示 已自动保存。

当前版本的界面变量仅提供以下两个配置项：

配置项	是否必填	说明
变量名	是	组件和事件引用该变量时使用的标识
默认值	否	页面首次使用该变量时的初始值

当前页面没有单独的数据类型选择器。请根据实际使用场景填写默认值，并在引用该变量的组件或事件中保持数据格式一致。

命名建议

• 使用能表达用途的名称，例如 selectedOption、searchKeyword 或 isPanelVisible。
• 同一个低代码应用内不要创建重名的界面变量。
• 变量名修改后，应同步检查所有引用该变量的组件和事件。
• 不要仅通过变量名称猜测数据格式；复杂对象或数组应在使用前确认上下游结构一致。

在组件属性中读取界面变量

需要让组件显示或使用界面变量时：

1. 在画布中选中目标组件。
2. 在右侧 属性 面板找到支持变量绑定的配置项。
3. 单击配置项旁的变量插入按钮。
4. 从变量选择器中选择目标界面变量。
5. 检查画布或预览页面中的实际结果。

建议通过变量选择器插入引用，避免手动输入错误的变量名或引用格式。

常见用法包括：

• 将输入组件的值显示到文本组件中。
• 使用一个变量控制多个组件展示相同数据。
• 在不同页面之间传递临时选择结果。
• 根据变量值控制组件的可见性或交互状态。

通过事件为界面变量赋值

1. 选中用于触发操作的组件，例如按钮、单选框或输入组件。
2. 在右侧面板切换到 事件。
3. 单击 新建。
4. 选择适合当前组件的事件类型，例如按钮的点击事件或单选框的数据改变时。
5. 将 执行动作 设置为 界面变量赋值。
6. 选择要写入的界面变量。
7. 设置写入值，可以使用固定值，也可以从当前组件或其他可用数据中选择动态值。
8. 单击 确定，然后打开预览验证结果。

例如，已创建 selectedOption 变量后，可以在单选框的数据改变时事件中把当前选中项写入该变量，再由文本组件读取并展示选择结果。

恢复默认值

事件动作如果提供恢复默认值选项，可以将变量重新设置为创建变量时填写的默认值。适合以下场景：

• 清空一次筛选或搜索条件。
• 重置表单中的临时选择。
• 返回页面的初始展示状态。

如果变量没有填写默认值，恢复后可能为空。配置重置动作前，应先确认组件能正确处理空值。

修改或删除界面变量

• 修改：直接编辑变量行中的名称或默认值，等待自动保存完成。
• 删除：单击变量行右侧的删除按钮。

删除或重命名之前，先检查组件属性、组件事件和页面交互中是否仍然引用该变量。引用失效后，组件可能显示空值或无法按预期执行动作。

与业务逻辑变量的区别

类型	配置入口	主要用途	生命周期
界面变量	用户界面 > 数据	组件联动、页面交互和临时界面状态	用户界面运行期间
应用变量	业务逻辑 > 设置 > 变量	同一次请求中的流程状态	每次新请求按默认值初始化
用户变量	业务逻辑 > 设置 > 变量	按用户长期保存的数据	跨请求持久化
系统变量	业务逻辑 > 设置 > 变量	平台在请求运行时提供的只读数据	由平台产生

常见问题

为什么界面变量页面没有类型设置？

当前版本只提供变量名和默认值。数据格式应由默认值、组件输入和事件赋值共同保持一致。

为什么组件中找不到刚创建的变量？

先确认页面顶部已完成自动保存，再重新打开组件属性中的变量选择器。如果仍未显示，检查变量是否已被删除或重命名。

修改变量名后组件显示为空怎么办？

重新打开引用该变量的组件属性或事件配置，通过变量选择器选择修改后的变量，并再次预览验证。