
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/ToolJetToolJet 是一套用于构建内部工具、仪表盘、业务应用与工作流的开源低代码平台而变量Variables是其应用状态管理的核心机制。本文以 ToolJet 官方概念文档 variables.md 为主体系统讲解 ToolJet 中五类变量的用途、定义方式与访问语法并结合仓库前端源码状态管理 Store、RunJS 静态分析器与部署文档帮助你掌握如何在应用内、页面间、工作区内以及不同部署环境下安全地组织、共享和保护数据。读完本文你将能熟练使用setVariable/setPageVariable、components.xxx.value、{{constants.xxx}}与{{secrets.xxx}}等核心 API构建出状态清晰、数据安全的应用。一、ToolJet 变量体系总览在 ToolJet 中变量用于存储可在应用内部或跨工作区访问和操作的数据。根据作用域与数据性质ToolJet 将变量划分为以下五类变量类型定义位置作用域典型用途Variables应用变量应用任意位置的Run Javascript code查询整个应用页面访问历史、跨组件共享的临时状态Page Variables页面变量特定页面的Run Javascript code查询单个页面记住某报表页的筛选条件如日期范围Exposed Variables组件暴露变量由组件自动创建并更新应用内读取文本输入值、组件可见性、下拉选项等Workspace Variables / Constants工作区变量/常量工作区设置工作区内全部应用存储 Token、密钥、API Key 等敏感信息Environment Variables环境变量部署环境服务端配置整个部署实例数据库连接串、外部 API 地址等环境差异化配置这五类机制共同构成了 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/setPageVariableToolJet 还提供了配套的unSetVariable删除单个应用变量、unsetAllVariables清空全部应用变量、unsetPageVariable删除单个页面变量与unsetAllPageVariables清空全部页面变量形成完整的变量生命周期管理能力。2.2 底层实现变量存储在哪里在状态管理层resolvedSlice.js应用变量与页面变量被存储在响应式引擎的exposedValues中。从源码结构看应用变量存放在exposedValues.variables键值对对象页面变量存放在exposedValues.page.variablessetVariable(key, value)写入variables[key] value后会通过scheduleDependencyUpdate(variables. key)触发依赖级联重算——这意味着所有引用了该变量的组件与查询会自动响应更新这正是 ToolJet「声明式响应式」数据流的核心unsetVariable(key)在删除键值的同时调用removeNode与updateDependencyValues确保响应式依赖图同步清理避免脏引用。2.3 读取语法在表达式{{ }}或 RunJS 代码中应用变量通过variables.变量名读取页面变量通过page.variables.变量名读取。这一点在 RunJS 静态分析器 scriptAnalysis.ts 中得到了印证——该模块用 ASTacorn acorn-walk解析 RunJS 代码并将不同 API 调用归类到不同「桶」中// frontend/src/AppBuilder/_utils/scriptAnalysis.ts const ACTION_FN_BUCKETS new Mapstring, 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工作区常量作为替代方案。迁移路径概括如下将每个工作区变量的值创建为对应的工作区常量在应用与数据源中将变量引用替换为常量引用——例如把客户端工作区变量%%client.pi%%替换为{{constants.pi}}全面测试应用后在「工作区设置 → 工作区变量」页示例 URLhttps://app.corp.com/nexus/workspace-settings/workspace-variables点击删除图标清理旧变量。4.2 工作区常量Global Constants 与 Secrets工作区常量Workspace Constants是预定义值用于跨工作区内的应用保持一致性、简化更新并安全存储敏感信息。所有常量与密钥在存入数据库前都会被加密提供额外的数据保护层。工作区常量分为两类详见 constants.mdGlobal Constants全局常量可复用值如 API 地址、配置项在客户端解析可在组件、数据查询、数据源、工作流中使用Secret Constants秘密常量专用于 API Key、数据库凭据等敏感信息在服务端解析、前端掩码显示不可暴露给客户端不能在 RunJS / RunPy 查询中使用且只能以单个键的方式引用不能组合成复合键。两类常量的能力对比如下特性Global ConstantsSecrets组件中使用✅❌数据查询中使用✅✅数据源中使用✅✅工作流中使用✅即将支持数据库加密存储✅✅前端掩码显示❌✅客户端解析✅❌服务端解析❌✅命名语法{{constants.constant_name}}{{secrets.secret_name}}创建步骤需具备相应工作区常量/变量权限在 ToolJet 仪表盘左侧边栏进入「Workspace Constants」页示例 URLhttps://app.corp.com/nexus/workspace-constants点击Create new constant打开配置抽屉输入常量名称与值选择类型Global constant或Secret点击Add constant保存。注意常量或密钥创建后类型不可更改如需更换类型必须删除后重新创建。工作区常量还支持环境差异化配置可以为开发、预发布、生产等不同环境为同一常量/密钥赋予不同值如各环境独立的 API Key从而在不改动代码的前提下实现按环境的无缝适配。更深入的说明可参见 工作区常量与密钥概念文档。五、环境变量面向部署环境的配置Environment Variables环境变量通常用于管理不同部署环境开发、测试、生产之间存在差异的配置项例如数据库连接串、外部 API 地址或任何环境特定的信息使开发者无需修改代码即可定制应用行为。在 ToolJet 中环境变量属于服务端/部署层的配置主要用于启动 ToolJet server 与 client。根据 env-vars.md以下为必需的核心变量类别变量说明主机地址TOOLJET_HOSTToolJet client 的公开 URL如https://app.tooljet.comLockbox 加密LOCKBOX_MASTER_KEY32 字节十六进制字符串用于加密数据源凭据会话密钥SECRET_KEY_BASE64 字节十六进制字符串用于加密会话 Cookie数据库PG_HOSTPostgreSQL 主机数据库PG_DB数据库名数据库PG_USER用户名数据库PG_PASS密码数据库PG_PORT端口生成密钥的推荐命令# LOCKBOX_MASTER_KEY32 字节 openssl rand -hex 32 # SECRET_KEY_BASE64 字节 openssl rand -hex 64常用可选变量DATABASE_URL使用连接 URL 而非分项配置如postgres://username:passwordhostname:port/database_name?sslmodedisablePG_DB_OWNER设为false可禁用数据库与扩展的自动创建当 PG 用户没有CREATEDB权限时CHECK_FOR_UPDATES设为0可关闭自托管版本每 24 小时的产品更新检查默认开启COMMENT_FEATURE_ENABLEtrue/false控制画布评论功能需先在设置中启用多人协同编辑。环境变量与前面四类「应用内变量」的定位差异需要厘清应用变量、页面变量、暴露变量与工作区常量解决的是运行期应用状态的组织与共享而环境变量解决的是部署期基础设施的差异化管理两者互补共同构成 ToolJet 从单应用到整个部署的完整配置与状态体系。六、总结五类变量的选型建议你的需求应选用的机制语法/API跨页面共享的临时应用状态应用变量setVariable(key, value)→variables.key仅单页面内有效的状态页面变量setPageVariable(key, value)→page.variables.key读取组件实时交互数据Exposed Variables{{ components.xxx.value }}等工作区内跨应用共享非敏感值Global Constants{{ constants.xxx }}工作区内跨应用共享敏感凭据Secrets{{ secrets.xxx }}服务端解析部署环境差异化配置Environment Variables服务端环境变量如TOOLJET_HOST、PG_*按照「能局部就不全局、能公开就不机密、运行期归变量、部署期归环境」的原则选型即可充分发挥 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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考