企业官网建设流程全解析

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

【免费下载链接】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 提供了一套覆盖应用级、页面级、组件级、工作区级与部署级的多层变量体系，让开发者在构建内部工具、仪表盘与业务应用时，能够灵活地存储、共享和隔离数据。本文以 ToolJet 官方变量概念文档为骨架，结合仓库中前端状态管理与部署配置的实际实现，系统讲解五类变量的定义方式、访问语法、典型使用场景与安全边界，帮助读者在 ToolJet 应用中正确选型并落地变量方案。

变量体系总览

在 ToolJet 中，变量用于存储可在应用内部或跨工作区访问和操作的数据。按照作用域与用途，共分为五种类型：

这五类机制共同构成了 ToolJet 中组织、共享与保护数据的完整框架。下面逐一深入。

应用变量（Variables）与页面变量（Page Variables）

应用变量可在应用内任意位置定义和访问，页面变量则被限定在其创建所在的页面内，无法像普通变量那样在整个应用中访问（参见 Set page variable 动作说明）。

通过 RunJS 查询定义与读取

在Run JavaScript code查询中，使用以下函数：

// 定义应用变量 setVariable(key, value); // 定义页面变量 setPageVariable(key, value);

定义后，可在任意组件属性、查询参数中使用{{}}语法读取：

{{variables.myKey}} // 读取应用变量 {{page.variables.myKey}} // 读取页面变量

在 RunJS 查询内部，也可以通过actionsAPI 立即读取刚设置的变量（参见 Run Actions from RunJS）：

actions.setVariable('mode', 'dark'); return actions.getVariable('mode'); // 返回 'dark' actions.setPageVariable('number', 1); return actions.getPageVariable('number'); // 返回 1

清理不再需要的变量时，使用：

actions.unSetVariable('<variableName>')

从源码实现看，这些函数最终都会构造标准事件并交给executeAction统一分发——setVariable生成actionId: 'set-custom-variable'事件，setPageVariable生成actionId: 'set-page-variable'事件，而getVariable、getPageVariable、unsetPageVariable也都有对应的 actionId（见 eventsSlice.js 与 eventsSlice.js 页面变量部分）。这意味着两种定义入口——RunJS 与事件处理器——在底层走的是同一条执行链路。

通过事件处理器定义

无需编写代码时，可以在事件处理器中直接选择动作：

• 添加事件处理器，选择Set variable动作，在 Action Options 中定义变量的 Key 与 Value；
• 页面变量则使用Set page variable动作。

事件方式的"Set page variable"动作默认留空 debounce 字段，可以填入毫秒数（例如300）延迟动作执行。

典型场景一：记录页面访问历史

文档给出的经典用例是：用setVariable维护用户在应用内的页面访问历史，进而实现自定义返回导航或用户行为分析。例如每次切换页面时把当前页压入一个数组变量，即可在任意页面渲染"上一页"按钮或上报访问漏斗。

典型场景二：记住报表页筛选条件

报表页的用户筛选（如日期范围）属于该页面的局部状态，非常适合用页面变量承载：用户设置完筛选后调用setPageVariable('dateRange', {...})，离开页面再返回时依然保留，且不会污染应用级命名空间。

典型场景三：统计页面访问次数

完整步骤（参见 Create and Manage Variables 教程）：

1. 创建名为countVisits的Run JavaScript code查询：

function incrementPageVisit() { if (!page.variables.visitCount) { actions.setPageVariable('visitCount', 1); } else { actions.setPageVariable('visitCount', Number(page.variables.visitCount) + 1); } } incrementPageVisit();

2. 新建页面（如Product Listing），在页面事件处理器中选择On page load事件 +Run Query动作，Query 选择countVisits。
3. 此后每次用户进入该页面，visitCount都会自增。

典型场景四：用变量消除 Table 加载闪烁

在更新数据时不想让 Table 出现 loading 状态，可以把数据先存入变量再渲染：

1. 创建getData与updateData两个查询；
2. 给getData添加Query Success事件，动作选setVariable，把返回数据（queries.getData.data）存入变量loadedData；
3. 在 Table 组件的Data属性中填入{{variables.loadedData}}；
4. 给updateData添加两个Query Success事件：第一个运行getData，第二个用getData的最新返回数据更新loadedData变量。

这样 Table 始终渲染变量中的数据，避免刷新过程中的加载指示器闪烁。

暴露变量（Exposed Variables）

Exposed Variables用于访问和操作组件相关的数据，由 ToolJet 在用户与应用交互时自动创建和更新，无需手动定义。无论是捕获文本编辑器中的内容、检查组件的可见性，还是获取下拉菜单的选中项，暴露变量都是 ToolJet 中动态数据处理的核心（详见 Exposed variables 概念文档）。

每个组件都自带一组暴露变量。以 Text Input 组件为例，value变量会在用户每次输入时实时更新，可通过 JS 语法动态访问：

{{components.textinput1.value}}

其他常见用法还包括：

{{components.table1.selectedRow.id}} // Table 选中行的 id {{components.dropdown1.value}} // 下拉菜单当前值 {{components.table1.currentPageData}} // Table 当前页数据

在应用编辑器的左侧Inspector面板中可以看到当前应用所有可访问的值——包括查询返回数据、组件暴露变量与全局变量（参见 Access Values 文档），方便随时确认变量名与结构。除此之外，{{}}内还可以写自定义 JS 表达式，例如用fx动态设置按钮背景色：

{{globals.theme.name == "light" ? "#375FCF" : "#FFFFFF"}}

或根据表单输入禁用按钮：

{{components.form1.data.textinput1 == "" ? true : false}}

工作区常量（Workspace Constants）

工作区常量用于存储工作区内所有应用都可能需要的值，如令牌、密钥、API Key 等。与前述变量不同，常量在运行期间保持不变，且只读、集中管理，保证了敏感信息在跨应用共享时既易于访问又不牺牲安全（详见 Workspace Constants 概念文档）。

两种类型

1. Global Constants（全局常量）：可复用的值，在整个产品中保持一致；
2. Secrets（密钥）：敏感数据的加密存储，如 API Key、数据库凭据、加密密钥。

安全机制

• 服务端解析：Global Constants 与 Secrets 都在服务端完成解析，真实值不会随网络请求载荷下发到客户端，避免前端暴露；
• 前端掩码：Secrets 在前端界面中显示为掩码，为敏感信息提供额外一层保护。

权限与使用范围

• 只有**管理员（Admins）**可以创建、更新或删除工作区常量；
• 拥有编辑权限的用户可以在应用各环节引用常量：
  • Global Constants 可用于应用构建器、数据源、数据查询、工作流；
  • Secrets 仅可用于数据源与数据查询，不能在应用构建器或工作流中使用。

引用语法

{{constants.constant_name}} // 引用全局常量 {{secrets.secret_name}} // 引用密钥

旧版 Workspace Variables 的迁移

需要注意的是，旧版的Workspace Variables已被标记为Deprecated（弃用）：当前版本仍可删除既有变量并在应用中继续使用，但不再支持创建和更新。官方建议迁移到 Workspace Constants（参见 Workspace Variables Migration 文档）：

• 按 Creating Workspace Constants 指南 创建新常量并存入对应值；
• 在应用和数据源中，将形如%%client.pi%%的旧工作区变量替换为{{constants.pi}}；
• 全面测试应用后，到 Workspace Settings 的 Workspace Variables 标签页删除旧变量。

环境变量（Environment Variables）

环境变量用于管理随部署环境（如开发、测试、生产）而异的配置项。它们可以存放数据库连接串、外部 API URL 或任何环境特定的信息，使开发者无需改动代码即可调整应用行为。

在 ToolJet 中，环境变量属于实例/部署层面的配置，通常在自托管部署时通过.env文件或容器环境注入，详细清单见 Environment variables 参考文档。以 Docker 部署为例，需要在.env中至少配置以下关键项：

• TOOLJET_HOST：ToolJet 实例对外的主机地址；
• LOCKBOX_MASTER_KEY：32 字节十六进制字符串，用于加密数据源凭据；
• SECRET_KEY_BASE：64 字节十六进制字符串，用于加密会话 Cookie；
• 数据库相关配置（PG_HOST、PG_DBNAME、PG_USER、PG_PASSWORD、PG_PORT）；
• PostgREST 相关：PGRST_JWT_SECRET（可用openssl rand -hex 32生成，未指定时 PostgREST 将拒绝认证请求）、PGRST_DB_URI、PGRST_LOG_LEVEL=info。

环境变量与工作区常量在定位上互补：前者面向"这个部署环境该如何运行"（实例级配置），后者面向"应用之间如何共享业务级敏感值"（工作区级配置）。在 Azure、EC2、Kubernetes 等部署方案中，环境变量都是配置应用行为的标准入口（参见 azure-container 部署文档 与 Docker 部署文档）。

变量选型建议与综合实践

综合以上五种变量类型，选型时可遵循以下思路：

• 跨页面、全局性业务状态（如导航历史、全局主题偏好）→ 应用变量（variables.*）；
• 页面内局部 UI 状态（如筛选条件、分页位置）→ 页面变量（page.variables.*）；
• 组件当前状态与用户输入（文本框内容、表格选中行）→ 暴露变量（components.*），由系统自动维护；
• 跨应用共享的非敏感业务值（如统一的折扣率、配置常量）→ 全局常量（constants.*）；
• 跨应用共享的敏感凭据（API Key、密钥、连接凭据）→ Secrets（secrets.*），务必只用于数据源与数据查询，由服务端解析，避免下发到浏览器；
• 随部署环境变化的实例级配置（连接串、JWT 密钥等）→ 环境变量，写入部署配置文件。

在 Run JavaScript code 查询中，这些机制可以组合使用——例如将 RunJS 与事件处理器配合，实现"查询成功后更新变量 → 组件绑定变量即时刷新"的响应式数据流。整套变量体系让 ToolJet 应用既能保持灵活的动态交互（应用/页面/暴露变量），又能兼顾安全与一致性（工作区常量与环境变量），从而支撑起复杂内部工具生态中数据的组织、共享与保护。

【免费下载链接】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