ToolJet 动作参考Set variable 动作的配置与底层实现原理【免费下载链接】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 中的Set variable设置变量动作介绍如何通过该动作创建自定义变量并赋值涵盖 Key / Value / Debounce 三个选项的完整配置说明并结合frontend仓库源码剖析该动作从事件触发、值解析到状态更新的底层调用链。读完本文你将能够在 ToolJet 应用中熟练使用 Set variable 动作维护跨组件共享的状态并能在 RunJS 查询中以代码方式动态写入变量。本文基于 ToolJet 仓库中 version-2.50.0-LTS 的 Set variable 文档 展开并辅以 frontend 源码 进行原理层面的印证。Set variable 动作能做什么Set variable 是一个事件动作Event Action它允许你创建一个自定义变量并为该变量赋予一个value。创建后的变量可以在整个应用范围内被读取和使用是 ToolJet 应用中实现组件间数据传递、跨页面状态共享的基础手段之一。在 ToolJet 的响应式体系中变量写入后会自动触发依赖它的表达式重新计算因此非常适合承载诸如「当前选中项」「主题模式」「用户偏好」「分页状态」等需要被多个组件或查询共享的临时状态。该动作与配套的 Unset variable删除变量动作 一起构成了变量生命周期的「写」与「删」两个端点而变量读取则统一通过 Inspector 面板或{{variables.变量名}}表达式完成。选项详解在事件的「动作」下拉框中选择Set variable后会出现以下三个配置项选项说明Key变量名String 类型通过该名称即可访问变量的值Value变量的值可以是字符串、数字、布尔表达式、数组或对象Debounce防抖时间默认留空填写数值可指定动作延迟执行的毫秒数例如300Key变量名即访问句柄Key是变量的唯一标识名类型为字符串。变量创建后你可以通过 Inspector 面板或表达式{{variables.key}}来访问它的值。例如设置Key mode之后便可用{{variables.mode}}读取。Key 的命名应遵循 JavaScript 标识符习惯建议使用驼峰或下划线命名以方便在表达式中直接引用。Value支持任意 JavaScript 可求值类型Value字段支持的类型非常宽泛包括字符串如active、dark数字如42、3.14布尔表达式如{{components.checkbox1.value true}}、1 0数组如[1, 2, 3]或{{queries.getData.data}}对象如{ name: ToolJet, version: 2.50.0 }。由于 Value 字段支持模板表达式{{ }}你可以把任意组件属性、查询返回值、全局设置等动态来源直接赋值给变量从而实现「快照」式的状态缓存。这一点与源码实现高度一致在事件执行阶段key和value都会先经过getResolvedValue做求值解析再写入状态详见下文「底层原理」小节。Debounce延迟执行与事件节流Debounce字段默认留空此时动作立即执行一旦填入数值动作会在该毫秒数之后才执行例如300表示 300ms 后执行。它适用于配合输入类组件事件避免高频触发导致频繁写入变量将多个相近时刻触发的事件合并为一次写入降低不必要的依赖重算开销。在源码层面动作执行入口本身就被节流包装executeAction使用了debounce包裹见 eventsSlice.js而防抖时间取自事件配置const debounceTime event?.event?.debounce || event?.debounce;见 utils.js最终以Number(debounceTime)作为延迟毫秒数。可以看到文档中描述的「延迟毫秒数」在实现中正是被转换为setTimeout语义的数值参数。典型使用场景与配置步骤Set variable 动作通常挂在组件的某个事件上如按钮的On Click、文本框的On Change、表格的On Row Selected等具体步骤为在画布中选中目标组件打开右侧「属性」面板找到对应事件如On Click点击「 添加」创建处理器在弹窗中选择动作Set variable填写Key例如selectedRow在Value中填入表达式例如{{components.table1.selectedRow}}把表格当前选中行快照到变量中可选在Debounce中填写如300为写入增加防抖保存并发布应用后即可在其他组件或查询中通过{{variables.selectedRow}}读取该值。从 RunJS 查询中触发除了通过可视化事件配置Set variable 动作也可以直接在RunJS 查询中以 JavaScript 代码触发两者写入的是同一个变量存储。相关语法参考 Run actions from RunJS 指南// 创建变量并赋值 actions.setVariable(mode, dark) // 删除变量 actions.unSetVariable(mode) // 设置后立即读取同步返回 actions.setVariable(number, 1) return actions.getVariable(number) // 页面级变量page 作用域 actions.setPageVariable(pageKey, 100) return actions.getPageVariable(pageKey)需要注意actions.setVariable(变量名, 值)的值参数可以是任意 JavaScript 值字符串、数字、布尔、数组、对象并且在 RunJS 上下文中写入是同步生效的——调用后在同一段 RunJS 代码里即可用getVariable读回这为「先写入、再使用」的脚本逻辑提供了便利。工具链对这类代码有专门的静态分析支持frontend中的 scriptAnalysis.ts 定义了ACTION_FN_BUCKETS把actions.setVariable(...)归类为「变量写入variableWrites」把actions.getVariable(...)归类为「变量读取variableReads」从而在 Dependency Viewer 中呈现变量的读写依赖关系。底层原理从事件到状态更新的调用链Set variable 动作的执行核心位于前端状态管理层其完整链路如下1. 事件分发所有事件动作都经由executeAction防抖包装统一入口分发见 eventsSlice.js。入口会先检查event.disabled与event.runOnlyIf条件不满足则直接跳过。2. 动作匹配与值解析当event.actionId set-custom-variable时执行以下逻辑见 eventsSlice.jscase set-custom-variable: { const { setVariable } get(); const key getResolvedValue(event.key, customVariables, moduleId); const value getResolvedValue(event.value, customVariables, moduleId); setVariable(key, value, moduleId); return Promise.resolve(); }key与value都会先经过getResolvedValue求值——这正是文档中「Value 可以是布尔表达式、数组或对象」的底层实现依据任何{{ }}模板表达式都在此处被解析为实际值。3. 状态写入与依赖传播setVariable的实现位于 resolvedSlice.jssetVariable: (key, value, moduleId canvas) { // 同步写入保证同一 RunJS 上下文中可立即读回 set((state) { state.resolvedStore.modules[moduleId].exposedValues.variables[key] value; }, false, setVariable); // 依赖更新被延迟调度与同批次 setVariable 调用合并 scheduleDependencyUpdate(variables.${key}, moduleId); get().rebuildVariableHints(moduleId); },可以看到三个关键设计同步写入变量值直接写入exposedValues.variables[key]写入即刻完成因此 RunJS 中setVariable后紧跟getVariable能立即读到新值延迟依赖更新scheduleDependencyUpdate(variables.key)采用微任务批次合并机制将同一次事件循环内的多次变量写入合并为一次依赖级联重算避免性能抖动提示重建rebuildVariableHints会同步更新代码补全/Inspector 中的变量提示列表。从源码结构看应用级变量与页面级变量setPageVariable分别存储在同一exposedValues下的variables与page命名空间中且共享同一套「同步写入 依赖调度 提示重建」机制这就是为什么在 Inspector 中能同时看到variables与page.variables两类条目。变量的读取与生命周期管理读取变量创建后可在任何支持表达式的字段中通过{{variables.key}}访问在 RunJS 中则用actions.getVariable(key)读取。删除使用 Unset variable 动作 删除指定变量其Key与Debounce选项与 Set variable 一致对应源码为unsetVariable会执行delete exposedValues.variables[key]并从依赖图中移除该节点见 resolvedSlice.js。持久性Set variable 创建的变量为运行时变量随应用会话存在应用刷新后会重置若需要跨会话保存的数据应改用其他持久化机制如 ToolJet Database 或后端 API不要将 Set variable 当作持久化存储使用。小结Set variable 是 ToolJet 应用中最基础也最常用的事件动作之一通过Key定义变量名、Value支持任意可求值类型、Debounce控制执行时机在可视化事件与 RunJS 两种触发方式下最终都会落到同一套「同步写入 依赖调度」的状态管理实现上。理解其选项语义与底层调用链eventsSlice.js → resolvedSlice.js可以帮助你在构建多组件联动的复杂应用时更合理地规划变量结构与读写时机。【免费下载链接】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），仅供参考