企业官网建设流程全解析

ToolJet 变量体系完全指南：应用变量、页面变量、Exposed Variables、工作区常量与环境变量

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

ToolJet 是一套用于构建内部工具、仪表盘、业务应用与工作流的开源低代码平台，而变量（Variables）是其应用状态管理的核心机制。本文以 ToolJet 官方概念文档 variables.md 为主体，系统讲解 ToolJet 中五类变量的用途、定义方式与访问语法，并结合仓库前端源码（状态管理 Store、RunJS 静态分析器）与部署文档，帮助你掌握如何在应用内、页面间、工作区内以及不同部署环境下安全地组织、共享和保护数据。读完本文，你将能熟练使用setVariable/setPageVariable、components.xxx.value、{{constants.xxx}}与{{secrets.xxx}}等核心 API，构建出状态清晰、数据安全的应用。

一、ToolJet 变量体系总览

在 ToolJet 中，变量用于存储可在应用内部或跨工作区访问和操作的数据。根据作用域与数据性质，ToolJet 将变量划分为以下五类：

这五类机制共同构成了 ToolJet 组织、共享和保护数据的完整框架，覆盖了从「单组件状态」到「跨应用敏感信息」再到「跨环境部署配置」的全部层级。下面逐一深入。

二、应用变量与页面变量：用setVariable/setPageVariable驱动应用状态

2.1 定义与核心 API

应用变量（Variables）可以在应用的任意位置通过Run Javascript code查询中的setVariable(key, value)函数定义；页面变量（Page Variables）则通过setPageVariable(key, value)定义。两者一旦定义，即可用于驱动应用功能逻辑。

从仓库源码可以确认，ToolJet 将这两组 API 作为「应用构建器动作（Actions）」的一等公民暴露给开发者。在 actions.js 中，可以看到完整动作清单：

// frontend/src/AppBuilder/_stores/constants/actions.js export const ACTIONS = [ 'runQuery', 'resetQuery', 'setVariable', 'unsetAllVariables', 'unSetVariable', 'showAlert', 'showModal', 'closeModal', 'setLocalStorage', 'copyToClipboard', 'goToApp', 'generateFile', 'setPageVariable', 'unsetAllPageVariables', 'unsetPageVariable', 'switchPage', 'logInfo', 'log', 'logError', 'toggleAppMode', 'scrollComponentInToView', ];

可见除了setVariable/setPageVariable，ToolJet 还提供了配套的unSetVariable（删除单个应用变量）、unsetAllVariables（清空全部应用变量）、unsetPageVariable（删除单个页面变量）与unsetAllPageVariables（清空全部页面变量），形成完整的变量生命周期管理能力。

2.2 底层实现：变量存储在哪里

在状态管理层（resolvedSlice.js），应用变量与页面变量被存储在响应式引擎的exposedValues中。从源码结构看：

• 应用变量存放在exposedValues.variables（键值对对象）；
• 页面变量存放在exposedValues.page.variables；
• setVariable(key, value)写入variables[key] = value后，会通过scheduleDependencyUpdate('variables.' + key)触发依赖级联重算——这意味着所有引用了该变量的组件与查询会自动响应更新，这正是 ToolJet「声明式响应式」数据流的核心；
• unsetVariable(key)在删除键值的同时调用removeNode与updateDependencyValues，确保响应式依赖图同步清理，避免脏引用。

2.3 读取语法

在表达式（{{ }}）或 RunJS 代码中，应用变量通过variables.变量名读取，页面变量通过page.variables.变量名读取。这一点在 RunJS 静态分析器 scriptAnalysis.ts 中得到了印证——该模块用 AST（acorn + acorn-walk）解析 RunJS 代码，并将不同 API 调用归类到不同「桶」中：

// frontend/src/AppBuilder/_utils/scriptAnalysis.ts const ACTION_FN_BUCKETS = new Map<string, BucketKey>([ ['setVariable', 'variableWrites'], ['unSetVariable', 'variableWrites'], ['getVariable', 'variableReads'], ['setPageVariable', 'pageVariableWrites'], ['unsetPageVariable', 'pageVariableWrites'], ['getPageVariable', 'pageVariableReads'], ]);

同时该分析器还会识别variables.xxx、page.variables.xxx的成员访问写法，以及const { key } = variables这类解构赋值，用于依赖视图（Dependency Viewer）中展示变量读写关系。这说明 ToolJet 对变量的读取与写入路径有完整的静态追踪能力，你在 RunJS 中的每一次变量操作都会被可视化地呈现。

2.4 实战示例一：记录页面访问历史

官方文档给出的典型场景是：用setVariable(key, value)创建一个变量来记录用户在应用内访问过的页面历史，从而实现自定义返回导航、或对用户流转与参与度做分析。

例如在应用级 RunJS 查询中：

// 每次切换页面时执行：把当前页名追加到历史数组 const history = variables.pageHistory || []; history.push(components.currentPageName.value); setVariable('pageHistory', history);

随后在按钮的onClick事件或任意表达式中即可读取：

// 自定义返回按钮：取历史中倒数第二个页面 variables.pageHistory[variables.pageHistory.length - 2]

2.5 实战示例二：记住报表页的筛选条件

同样地，页面变量适合承载「页面局部记忆」。文档示例中，在报表页保存用户的筛选选择（例如日期范围）：

// 在日期范围组件值变化时执行 setPageVariable('dateRange', components.dateRangePicker1.value);

下次用户回到该页面时，筛选状态依然可用：

// 初始化查询参数 {{ page.variables.dateRange }}

需要清理时调用unsetPageVariable('dateRange')或unsetAllPageVariables()即可。

三、Exposed Variables：组件暴露变量

Exposed Variables（组件暴露变量）用于访问和操作与组件相关的数据。它们由 ToolJet 在运行时自动创建并更新，随着用户与应用的交互而实时变化——无论是捕获文本编辑器的输入、检查组件可见性，还是获取下拉菜单的选中项，暴露变量都是 ToolJet 应用中动态数据处理的核心。

每个组件都拥有一组自己的暴露变量，保存与该组件相关的特定数据。以 Text Input 组件为例，其value暴露变量会在用户每次输入时更新，可通过 JavaScript 记法动态访问：

{{ components.textinput1.value }}

其他常见例子：

• 下拉组件（Dropdown）的选中值：{{ components.dropdown1.value }}
• 组件的可见性状态：{{ components.table1.isVisible }}
• 表格的选中行数据：{{ components.table1.selectedRow }}

关于各组件暴露变量的详细清单，请参阅 Exposed Variables 文档 及各组件各自的官方文档。在 resolvedSlice.js 中可以看到，组件暴露值同样存放在exposedValues结构中（与variables、page.variables并列），并通过setExposedValue类似的调度机制参与同一套响应式依赖更新——因此组件的交互状态与手工设置的变量在数据流上是同构的，可以无缝混用。

四、工作区变量与工作区常量：跨应用共享敏感信息

4.1 工作区变量（已废弃）

Workspace Variables（工作区变量）的设计初衷是存储同一工作区内多个应用可能用到的值，如 Token、密钥、API Key 等，实现敏感信息的安全、集中管理。

重要提示：根据仓库中的 Workspace Variables 迁移文档，工作区变量目前已被标记为Deprecated（废弃），将在未来版本中移除。当前版本仍然可以删除已有变量并在各 ToolJet 应用中使用它们，但创建与更新变量已不再支持。官方建议使用Workspace Constants（工作区常量）作为替代方案。

迁移路径概括如下：

1. 将每个工作区变量的值创建为对应的工作区常量；
2. 在应用与数据源中将变量引用替换为常量引用——例如把客户端工作区变量%%client.pi%%替换为{{constants.pi}}；
3. 全面测试应用后，在「工作区设置 → 工作区变量」页（示例 URL：https://app.corp.com/nexus/workspace-settings/workspace-variables）点击删除图标清理旧变量。

4.2 工作区常量：Global Constants 与 Secrets

工作区常量（Workspace Constants）是预定义值，用于跨工作区内的应用保持一致性、简化更新并安全存储敏感信息。所有常量与密钥在存入数据库前都会被加密，提供额外的数据保护层。工作区常量分为两类（详见 constants.md）：

1. Global Constants（全局常量）：可复用值，如 API 地址、配置项，在客户端解析，可在组件、数据查询、数据源、工作流中使用；
2. Secret Constants（秘密常量）：专用于 API Key、数据库凭据等敏感信息，在服务端解析、前端掩码显示，不可暴露给客户端；不能在 RunJS / RunPy 查询中使用，且只能以单个键的方式引用，不能组合成复合键。

两类常量的能力对比如下：

创建步骤（需具备相应工作区常量/变量权限）：

1. 在 ToolJet 仪表盘左侧边栏进入「Workspace Constants」页（示例 URL：https://app.corp.com/nexus/workspace-constants）；
2. 点击Create new constant打开配置抽屉；
3. 输入常量名称与值；
4. 选择类型：Global constant或Secret；
5. 点击Add constant保存。

注意：常量或密钥创建后类型不可更改，如需更换类型必须删除后重新创建。

工作区常量还支持环境差异化配置：可以为开发、预发布、生产等不同环境为同一常量/密钥赋予不同值（如各环境独立的 API Key），从而在不改动代码的前提下实现按环境的无缝适配。更深入的说明可参见 工作区常量与密钥概念文档。

五、环境变量：面向部署环境的配置

Environment Variables（环境变量）通常用于管理不同部署环境（开发、测试、生产）之间存在差异的配置项，例如数据库连接串、外部 API 地址或任何环境特定的信息，使开发者无需修改代码即可定制应用行为。

在 ToolJet 中，环境变量属于服务端/部署层的配置，主要用于启动 ToolJet server 与 client。根据 env-vars.md，以下为必需的核心变量：

生成密钥的推荐命令：

# LOCKBOX_MASTER_KEY（32 字节） openssl rand -hex 32 # SECRET_KEY_BASE（64 字节） openssl rand -hex 64

常用可选变量：

• DATABASE_URL：使用连接 URL 而非分项配置，如postgres://username:password@hostname:port/database_name?sslmode=disable；
• PG_DB_OWNER：设为false可禁用数据库与扩展的自动创建（当 PG 用户没有CREATEDB权限时）；
• CHECK_FOR_UPDATES：设为0可关闭自托管版本每 24 小时的产品更新检查（默认开启）；
• COMMENT_FEATURE_ENABLE：true/false，控制画布评论功能（需先在设置中启用多人协同编辑）。

环境变量与前面四类「应用内变量」的定位差异需要厘清：应用变量、页面变量、暴露变量与工作区常量解决的是运行期应用状态的组织与共享；而环境变量解决的是部署期基础设施的差异化管理，两者互补，共同构成 ToolJet 从单应用到整个部署的完整配置与状态体系。

六、总结：五类变量的选型建议

按照「能局部就不全局、能公开就不机密、运行期归变量、部署期归环境」的原则选型，即可充分发挥 ToolJet 变量体系在灵活性、安全性与可维护性上的整体优势。

延伸阅读

• RunJS 动作与变量设置/取消指南
• Exposed Variables 详解
• 工作区常量与密钥完整文档
• 工作区变量迁移指南
• 环境变量完整配置文档
• 工作区常量概念文档

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet