2026/9/10 1:46:00
FEATURED · 精选文章 
ToolJet Unset variable 动作完全指南移除应用变量、Debounce 配置与底层实现原理【免费下载链接】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图片 altToolJet 事件编辑器中使用 Unset variable 动作的配置界面截图 srcdocs/static/img/actions/unsetvar/unsetvar2.png /本篇技术指南聚焦 ToolJet 低代码平台中的Unset variable移除变量动作介绍它如何删除通过Set variable动作创建的应用变量、如何在事件处理器中配置其Key与Debounce字段并结合仓库前端源码深入讲解该动作从事件派发、状态删除到依赖值重算的完整调用链。读完本文你将能在可视化事件流与 RunJS 脚本两条路径上自由地清理不再需要的应用变量避免变量残留导致的状态污染。一、前置知识ToolJet 的应用变量Variables从何而来在 ToolJet 中变量是跨组件共享状态的基础设施。通常用户通过Set variable动作创建一个命名变量并为其赋值值可以是字符串、数字、布尔表达式、数组或对象创建之后即可在任意组件的属性表达式如{{ variables.xxx }}或 JavaScript 代码中引用该变量。与之配套Unset variable动作负责把“已创建”的变量从运行状态中移除二者成对出现、构成变量生命周期的完整闭环。与其相关的动作文档可在仓库中找到建议对照阅读变量创建Set variable 动作文档页面级变量的创建与移除Set page variable、Unset page variable说明Set/Unset variable 操作的是应用级变量应用内所有页面与组件共享如果只需要某个页面内有效应改用 page variable 系列动作。二、Unset variable 的用途与典型场景根据官方动作参考文档的定义该动作允许你移除之前通过 Set variable 动作创建的变量。典型使用场景包括会话结束清理用户登出或流程结束时用 Unset variable 删除存放用户身份、临时令牌的变量防止残留数据在后续会话中被误读。状态重置表单提交完成后清除暂存变量使下次操作从干净的初始状态开始。多分支互斥在向导式多步骤界面中完成分支 A 后清除其专属变量避免分支 B 读取到无关数据。配合 RunJS 做动态管理在复杂逻辑中用 JavaScript 判断条件后决定是否移除某个变量。三、在事件处理器中配置 Unset variable 动作3.1 添加步骤在 ToolJet 应用编辑器中选中一个组件如按钮打开其事件处理器Event Handler新建一条事件并选择动作Unset variable。此时界面会依据动作定义渲染出对应的可配置字段。从仓库源码看该动作的定义位于 frontend/src/AppBuilder/RightSideBar/Inspector/ActionTypes.js{ name: Unset variable, id: unset-custom-variable, options: [{ name: key, type: code, default: }], group: variable, }该定义表明动作内部 ID 为unset-custom-variable它仅需要一个key输入项类型为code即支持代码高亮与表达式求值归属于variable动作组与 Set variable、Unset all variables 同组。事件编辑器中该动作的 UI 渲染位于 frontend/src/AppBuilder/RightSideBar/Inspector/EventManager.jsx仅渲染一个带Key标签的 CodeHinter 输入框。3.2 选项字段说明选项说明备注Key要移除的变量名字符串String即 Set variable 时使用的那个键名必填。字段为代码类型支持使用表达式动态拼接键名Debounce防抖时间默认值为空可填入毫秒数指定动作在延迟多久之后才执行例如300表示延迟 300msKey 字段详解Key必须与先前 Set variable 时写入的键名完全一致大小写敏感。由于它是代码类型type: code你既可以直接输入静态字符串也可以写{{ variables.selectedUserId }}之类的表达式让运行时动态决定要删除哪个变量。代码在派发时会被解析为实际值——这一点在“底层实现原理”一节会有源码佐证。Debounce 字段详解Debounce在文档中被明确标注为默认空值。留空时动作在事件触发后立即执行填入数值后动作会延迟指定的毫秒数再执行。常见用法是在“先执行一段动画/短暂展示 loading再清理变量”的场景中做时序控制典型取值如300、1000。四、底层实现原理从事件派发到变量真正消失要准确理解 Unset variable 做了什么可以沿着前端状态管理源码追踪它的一次完整执行。4.1 事件派发eventsSlice所有事件动作在 ToolJet 前端都被集中到一个事件执行器中处理。在 frontend/src/AppBuilder/_stores/slices/eventsSlice.js 中unset-custom-variable分支的实现如下case unset-custom-variable: { const { unsetVariable } get(); const key getResolvedValue(event.key, customVariables, moduleId); unsetVariable(key, moduleId); return Promise.resolve(); }关键步骤有两处getResolvedValue(event.key, customVariables, moduleId)先把事件里配置的key解析为运行时实际值——这正是 Key 字段支持动态表达式的原因unsetVariable(key, moduleId)调用状态切片中真正执行删除逻辑的函数moduleId默认是canvas即主画布/应用主体。4.2 状态删除resolvedSlice真正执行删除的是 frontend/src/AppBuilder/_stores/slices/resolvedSlice.js 中的unsetVariableunsetVariable: (key, moduleId canvas) { set( (state) { delete state.resolvedStore.modules[moduleId].exposedValues.variables[key]; }, false, unsetVariable ); get().removeNode(variables.${key}, moduleId); get().updateDependencyValues(variables.${key}, moduleId); get().rebuildVariableHints(moduleId); },这段代码揭示了动作的三个副作用理解它们对排查变量相关问题很有帮助删除键值delete exposedValues.variables[key]将该键从运行时解析结果resolved store中物理移除移除依赖图中的节点removeNode(variables.key, moduleId)把该变量从依赖图dependency graph里摘除。若省略这步变量虽然取不到值但仍可能残留在组件间的依赖关系中导致后续计算或自动补全出现异常重算依赖值并重建提示updateDependencyValues通知所有引用variables.key的组件/表达式重新求值通常表现为使用处变为undefined或触发默认值逻辑rebuildVariableHints则同步更新代码编辑器中的变量补全提示列表。从源码结构看ToolJet 采用 zustand 状态管理set写入新的状态快照随后的removeNode/updateDependencyValues保证“删除变量”这一动作会沿依赖链级联传播而不是仅仅把一个键置空。这也是为什么 Unset variable 与直接把值设为undefined有本质区别——前者是完整的生命周期清理后者仅是取值层面的占位。4.3 批量清理Unset all variables与 Unset variable 配套的还有Unset all variables动作内部 IDunset-all-custom-variables定义见 ActionTypes.js。它的执行逻辑是遍历当前模块下所有变量并逐个执行同样的删除流程见 resolvedSlice.js 中的 unsetAllVariables。当需要一次性清空全部应用变量例如退出登录重置整个应用状态时用它比逐条调用 Unset variable 更高效、更不易遗漏。五、从 RunJS / JavaScript 中触发 Unset variable动作参考文档专门提示你同样可以从 JavaScript 代码中触发该动作详见 RunJS 中运行动作的指南。在 ToolJet 任意组件的RunJS代码编辑器或支持runjs的查询中里你可以直接调用前端暴露的动作 API 来移除变量例如// 删除名为 cartItems 的应用变量 await actions.unsetVariable(cartItems);这样做的意义在于变量的创建与清理可以由一段脚本根据运行期条件灵活决策而无需为每种情况单独配置可视化事件。需要批量删除时也可调用对应的全量清理 API。在事件派发层RunJS 路径与可视化事件路径最终会汇入同一个eventsSlice执行器——动作注册表见 frontend/src/AppBuilder/_stores/slices/eventsSlice.js其中unset-custom-variable与unset-all-custom-variables均被暴露为可编程调用的动作因此两种触发方式在行为上保持一致删除、依赖重算、提示重建都会发生。六、使用建议与注意事项综合文档描述与源码行为实战中请留意以下几点Key 的一致性Unset variable 只能移除与Key精确匹配的变量。若 Key 写错或变量尚不存在删除是幂等的删除不存在的键不会报错但也不会产生任何清理效果因此建议在使用前先通过variables.key校验变量确实存在。区分“置空”与“删除”用 Set variable 把值设为undefined/null只是改变取值变量名仍会出现在依赖图与自动补全中Unset variable 则从状态、依赖图和提示列表中一并清除。需要彻底回收时应使用 Unset variable。动态 Key 的求值Key字段是代码类型派发时会经getResolvedValue求值。若希望删除的键名本身依赖其他变量例如{{ user_ variables.currentId }}可以放心使用表达式但要注意求值结果最终必须落在variables命名空间内存在的键上。模块与作用域底层所有变量操作都挂在moduleId默认canvas之下。理解这一点有助于排查多模块/多页面应用中“明明删了却还能读到”的疑问——请确认操作与读取发生在同一作用域。时序编排需要延迟清理时使用Debounce字段指定毫秒数如果需要在清理前后执行一串其他动作可考虑将多个动作串联在同一个事件链中并按依赖关系排序。七、延伸阅读Set variable创建并赋值应用变量Set page variable / Unset page variable页面级变量管理、Unset page variable通过 RunJS 触发任意动作相关实现文件frontend/src/AppBuilder/RightSideBar/Inspector/ActionTypes.js、frontend/src/AppBuilder/RightSideBar/Inspector/EventManager.jsx、frontend/src/AppBuilder/_stores/slices/eventsSlice.js、frontend/src/AppBuilder/_stores/slices/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），仅供参考
ToolJet Unset variable 动作完全指南：移除应用变量、Debounce 配置与底层实现原理
ToolJet Unset variable 动作完全指南移除应用变量、Debounce 配置与底层实现原理【免费下载链接】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图片 altToolJet 事件编辑器中使用 Unset variable 动作的配置界面截图 srcdocs/static/img/actions/unsetvar/unsetvar2.png /本篇技术指南聚焦 ToolJet 低代码平台中的Unset variable移除变量动作介绍它如何删除通过Set variable动作创建的应用变量、如何在事件处理器中配置其Key与Debounce字段并结合仓库前端源码深入讲解该动作从事件派发、状态删除到依赖值重算的完整调用链。读完本文你将能在可视化事件流与 RunJS 脚本两条路径上自由地清理不再需要的应用变量避免变量残留导致的状态污染。一、前置知识ToolJet 的应用变量Variables从何而来在 ToolJet 中变量是跨组件共享状态的基础设施。通常用户通过Set variable动作创建一个命名变量并为其赋值值可以是字符串、数字、布尔表达式、数组或对象创建之后即可在任意组件的属性表达式如{{ variables.xxx }}或 JavaScript 代码中引用该变量。与之配套Unset variable动作负责把“已创建”的变量从运行状态中移除二者成对出现、构成变量生命周期的完整闭环。与其相关的动作文档可在仓库中找到建议对照阅读变量创建Set variable 动作文档页面级变量的创建与移除Set page variable、Unset page variable说明Set/Unset variable 操作的是应用级变量应用内所有页面与组件共享如果只需要某个页面内有效应改用 page variable 系列动作。二、Unset variable 的用途与典型场景根据官方动作参考文档的定义该动作允许你移除之前通过 Set variable 动作创建的变量。典型使用场景包括会话结束清理用户登出或流程结束时用 Unset variable 删除存放用户身份、临时令牌的变量防止残留数据在后续会话中被误读。状态重置表单提交完成后清除暂存变量使下次操作从干净的初始状态开始。多分支互斥在向导式多步骤界面中完成分支 A 后清除其专属变量避免分支 B 读取到无关数据。配合 RunJS 做动态管理在复杂逻辑中用 JavaScript 判断条件后决定是否移除某个变量。三、在事件处理器中配置 Unset variable 动作3.1 添加步骤在 ToolJet 应用编辑器中选中一个组件如按钮打开其事件处理器Event Handler新建一条事件并选择动作Unset variable。此时界面会依据动作定义渲染出对应的可配置字段。从仓库源码看该动作的定义位于 frontend/src/AppBuilder/RightSideBar/Inspector/ActionTypes.js{ name: Unset variable, id: unset-custom-variable, options: [{ name: key, type: code, default: }], group: variable, }该定义表明动作内部 ID 为unset-custom-variable它仅需要一个key输入项类型为code即支持代码高亮与表达式求值归属于variable动作组与 Set variable、Unset all variables 同组。事件编辑器中该动作的 UI 渲染位于 frontend/src/AppBuilder/RightSideBar/Inspector/EventManager.jsx仅渲染一个带Key标签的 CodeHinter 输入框。3.2 选项字段说明选项说明备注Key要移除的变量名字符串String即 Set variable 时使用的那个键名必填。字段为代码类型支持使用表达式动态拼接键名Debounce防抖时间默认值为空可填入毫秒数指定动作在延迟多久之后才执行例如300表示延迟 300msKey 字段详解Key必须与先前 Set variable 时写入的键名完全一致大小写敏感。由于它是代码类型type: code你既可以直接输入静态字符串也可以写{{ variables.selectedUserId }}之类的表达式让运行时动态决定要删除哪个变量。代码在派发时会被解析为实际值——这一点在“底层实现原理”一节会有源码佐证。Debounce 字段详解Debounce在文档中被明确标注为默认空值。留空时动作在事件触发后立即执行填入数值后动作会延迟指定的毫秒数再执行。常见用法是在“先执行一段动画/短暂展示 loading再清理变量”的场景中做时序控制典型取值如300、1000。四、底层实现原理从事件派发到变量真正消失要准确理解 Unset variable 做了什么可以沿着前端状态管理源码追踪它的一次完整执行。4.1 事件派发eventsSlice所有事件动作在 ToolJet 前端都被集中到一个事件执行器中处理。在 frontend/src/AppBuilder/_stores/slices/eventsSlice.js 中unset-custom-variable分支的实现如下case unset-custom-variable: { const { unsetVariable } get(); const key getResolvedValue(event.key, customVariables, moduleId); unsetVariable(key, moduleId); return Promise.resolve(); }关键步骤有两处getResolvedValue(event.key, customVariables, moduleId)先把事件里配置的key解析为运行时实际值——这正是 Key 字段支持动态表达式的原因unsetVariable(key, moduleId)调用状态切片中真正执行删除逻辑的函数moduleId默认是canvas即主画布/应用主体。4.2 状态删除resolvedSlice真正执行删除的是 frontend/src/AppBuilder/_stores/slices/resolvedSlice.js 中的unsetVariableunsetVariable: (key, moduleId canvas) { set( (state) { delete state.resolvedStore.modules[moduleId].exposedValues.variables[key]; }, false, unsetVariable ); get().removeNode(variables.${key}, moduleId); get().updateDependencyValues(variables.${key}, moduleId); get().rebuildVariableHints(moduleId); },这段代码揭示了动作的三个副作用理解它们对排查变量相关问题很有帮助删除键值delete exposedValues.variables[key]将该键从运行时解析结果resolved store中物理移除移除依赖图中的节点removeNode(variables.key, moduleId)把该变量从依赖图dependency graph里摘除。若省略这步变量虽然取不到值但仍可能残留在组件间的依赖关系中导致后续计算或自动补全出现异常重算依赖值并重建提示updateDependencyValues通知所有引用variables.key的组件/表达式重新求值通常表现为使用处变为undefined或触发默认值逻辑rebuildVariableHints则同步更新代码编辑器中的变量补全提示列表。从源码结构看ToolJet 采用 zustand 状态管理set写入新的状态快照随后的removeNode/updateDependencyValues保证“删除变量”这一动作会沿依赖链级联传播而不是仅仅把一个键置空。这也是为什么 Unset variable 与直接把值设为undefined有本质区别——前者是完整的生命周期清理后者仅是取值层面的占位。4.3 批量清理Unset all variables与 Unset variable 配套的还有Unset all variables动作内部 IDunset-all-custom-variables定义见 ActionTypes.js。它的执行逻辑是遍历当前模块下所有变量并逐个执行同样的删除流程见 resolvedSlice.js 中的 unsetAllVariables。当需要一次性清空全部应用变量例如退出登录重置整个应用状态时用它比逐条调用 Unset variable 更高效、更不易遗漏。五、从 RunJS / JavaScript 中触发 Unset variable动作参考文档专门提示你同样可以从 JavaScript 代码中触发该动作详见 RunJS 中运行动作的指南。在 ToolJet 任意组件的RunJS代码编辑器或支持runjs的查询中里你可以直接调用前端暴露的动作 API 来移除变量例如// 删除名为 cartItems 的应用变量 await actions.unsetVariable(cartItems);这样做的意义在于变量的创建与清理可以由一段脚本根据运行期条件灵活决策而无需为每种情况单独配置可视化事件。需要批量删除时也可调用对应的全量清理 API。在事件派发层RunJS 路径与可视化事件路径最终会汇入同一个eventsSlice执行器——动作注册表见 frontend/src/AppBuilder/_stores/slices/eventsSlice.js其中unset-custom-variable与unset-all-custom-variables均被暴露为可编程调用的动作因此两种触发方式在行为上保持一致删除、依赖重算、提示重建都会发生。六、使用建议与注意事项综合文档描述与源码行为实战中请留意以下几点Key 的一致性Unset variable 只能移除与Key精确匹配的变量。若 Key 写错或变量尚不存在删除是幂等的删除不存在的键不会报错但也不会产生任何清理效果因此建议在使用前先通过variables.key校验变量确实存在。区分“置空”与“删除”用 Set variable 把值设为undefined/null只是改变取值变量名仍会出现在依赖图与自动补全中Unset variable 则从状态、依赖图和提示列表中一并清除。需要彻底回收时应使用 Unset variable。动态 Key 的求值Key字段是代码类型派发时会经getResolvedValue求值。若希望删除的键名本身依赖其他变量例如{{ user_ variables.currentId }}可以放心使用表达式但要注意求值结果最终必须落在variables命名空间内存在的键上。模块与作用域底层所有变量操作都挂在moduleId默认canvas之下。理解这一点有助于排查多模块/多页面应用中“明明删了却还能读到”的疑问——请确认操作与读取发生在同一作用域。时序编排需要延迟清理时使用Debounce字段指定毫秒数如果需要在清理前后执行一串其他动作可考虑将多个动作串联在同一个事件链中并按依赖关系排序。七、延伸阅读Set variable创建并赋值应用变量Set page variable / Unset page variable页面级变量管理、Unset page variable通过 RunJS 触发任意动作相关实现文件frontend/src/AppBuilder/RightSideBar/Inspector/ActionTypes.js、frontend/src/AppBuilder/RightSideBar/Inspector/EventManager.jsx、frontend/src/AppBuilder/_stores/slices/eventsSlice.js、frontend/src/AppBuilder/_stores/slices/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），仅供参考 
