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/ToolJetToolJet 提供了一套覆盖应用级、页面级、组件级、工作区级与部署级的多层变量体系让开发者在构建内部工具、仪表盘与业务应用时能够灵活地存储、共享和隔离数据。本文以 ToolJet 官方变量概念文档为骨架结合仓库中前端状态管理与部署配置的实际实现系统讲解五类变量的定义方式、访问语法、典型使用场景与安全边界帮助读者在 ToolJet 应用中正确选型并落地变量方案。变量体系总览在 ToolJet 中变量用于存储可在应用内部或跨工作区访问和操作的数据。按照作用域与用途共分为五种类型变量类型作用域典型用途定义方式Variables应用变量整个应用内的任意位置记录页面访问历史、全局用户偏好setVariable(key, value)/ 事件处理器Page Variables页面变量应用中的单个页面记住报表页的筛选条件如日期范围setPageVariable(key, value)/ 事件处理器Exposed Variables暴露变量组件级应用内可访问读取文本输入值、组件可见性、下拉选中项由组件自动创建与更新Workspace Constants工作区常量整个工作区的所有应用存储令牌、密钥、API Key 等敏感信息工作区设置中由管理员创建Environment Variables环境变量部署环境开发/测试/生产数据库连接串、外部 API URL、实例级密钥部署配置如.env这五类机制共同构成了 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 RunJSactions.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 教程创建名为countVisits的Run JavaScript code查询function incrementPageVisit() { if (!page.variables.visitCount) { actions.setPageVariable(visitCount, 1); } else { actions.setPageVariable(visitCount, Number(page.variables.visitCount) 1); } } incrementPageVisit();新建页面如Product Listing在页面事件处理器中选择On page load事件 Run Query动作Query 选择countVisits。此后每次用户进入该页面visitCount都会自增。典型场景四用变量消除 Table 加载闪烁在更新数据时不想让 Table 出现 loading 状态可以把数据先存入变量再渲染创建getData与updateData两个查询给getData添加Query Success事件动作选setVariable把返回数据queries.getData.data存入变量loadedData在 Table 组件的Data属性中填入{{variables.loadedData}}给updateData添加两个Query Success事件第一个运行getData第二个用getData的最新返回数据更新loadedData变量。这样 Table 始终渲染变量中的数据避免刷新过程中的加载指示器闪烁。暴露变量Exposed VariablesExposed 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 概念文档。两种类型Global Constants全局常量可复用的值在整个产品中保持一致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_HOSTToolJet 实例对外的主机地址LOCKBOX_MASTER_KEY32 字节十六进制字符串用于加密数据源凭据SECRET_KEY_BASE64 字节十六进制字符串用于加密会话 Cookie数据库相关配置PG_HOST、PG_DBNAME、PG_USER、PG_PASSWORD、PG_PORTPostgREST 相关PGRST_JWT_SECRET可用openssl rand -hex 32生成未指定时 PostgREST 将拒绝认证请求、PGRST_DB_URI、PGRST_LOG_LEVELinfo。环境变量与工作区常量在定位上互补前者面向这个部署环境该如何运行实例级配置后者面向应用之间如何共享业务级敏感值工作区级配置。在 Azure、EC2、Kubernetes 等部署方案中环境变量都是配置应用行为的标准入口参见 azure-container 部署文档 与 Docker 部署文档。变量选型建议与综合实践综合以上五种变量类型选型时可遵循以下思路跨页面、全局性业务状态如导航历史、全局主题偏好→ 应用变量variables.*页面内局部 UI 状态如筛选条件、分页位置→ 页面变量page.variables.*组件当前状态与用户输入文本框内容、表格选中行→ 暴露变量components.*由系统自动维护跨应用共享的非敏感业务值如统一的折扣率、配置常量→ 全局常量constants.*跨应用共享的敏感凭据API Key、密钥、连接凭据→ Secretssecrets.*务必只用于数据源与数据查询由服务端解析避免下发到浏览器随部署环境变化的实例级配置连接串、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考