企业官网建设流程全解析

ToolJet Unset Variable 动作详解：从事件处理器到 RunJS 的变量清理实战

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

Unset variable 是 ToolJet 动作（Action）体系中用于管理应用运行时变量生命周期的关键能力，它负责移除先前通过Set variable动作创建的变量。本文围绕该动作的配置参数、触发方式与底层实现展开，帮助你在应用构建器中通过事件处理器或 JavaScript 代码精准释放不再需要的变量，实现状态清理、表单重置与内存释放等实战需求。

什么是 Unset variable 动作

在 ToolJet 应用构建过程中，开发者常使用变量（Variables）在应用内动态存储和传递数据，例如跟踪用户偏好、记录访问次数、缓存查询结果等。变量一旦创建，会持续存在于当前应用会话的运行时状态中。当变量不再被任何组件或逻辑引用时，就需要通过Unset variable动作将其移除，避免陈旧数据影响后续逻辑判断。

Unset variable 动作的作用非常明确：删除一个由 Set variable 动作创建的变量。与之配套的变量管理动作还包括：

上述动作类型集中定义在 ActionTypes.js 中，从源码结构看，Unset variable属于variable分组，且是少数仅需Key一个必填参数的动作——删除变量只需要知道它的名字，不需要提供新值。

在事件处理器中配置 Unset variable

在应用编辑器中，你可以像配置其他动作一样配置 Unset variable：为某个组件或查询添加事件处理器（Event Handler），在Action下拉框中选择Unset variable，然后配置动作选项。

动作选项说明

如上图所示，在On click事件中配置Unset variable动作，Key 填写name，Debounce 填写300，即组件被点击 300 毫秒后删除名为name的变量。Debounce 适用于需要等待其他动作完成或避免高频触发造成抖动干扰的场景。

典型配置流程

1. 选中组件（如按钮），在右侧属性面板中添加事件处理器；
2. Event 选择On click（或组件支持的其他事件）；
3. Action 选择Unset variable；
4. 在 Action Options 的 Key 中填入要删除的变量名，如name；
5. 按需设置 Debounce 毫秒数；
6. 保存并运行应用验证变量已被移除。

通过 RunJS 代码触发 Unset variable

除了在事件处理器中可视化配置，ToolJet 还支持在Run JavaScript code（RunJS）查询中直接调用动作。官方文档提供的语法为：

actions.unSetVariable('<variableName>')

示例——创建变量后再删除它：

// 先创建变量 actions.setVariable('name', 'ToolJet'); // 立即读取变量（同步可读） return actions.getVariable('name'); // 返回 'ToolJet' // 删除变量 actions.unSetVariable('name');

对应的页面级变量删除语法为actions.unsetPageVariable('<variableName>')，全部清空则使用actions.unsetAllVariables()与actions.unsetAllPageVariables()。更完整的 RunJS 动作调用说明可参考 run-action-from-runjs.md。

RunJS 调用链的源码佐证

从源码结构看，RunJS 中的actions.unSetVariable(key)最终通过executeAction事件分发机制触发unset-custom-variable动作，事件对象构造如下（eventsSlice.js）：

const unSetVariable = (key = '') => { if (key) { const event = { actionId: 'unset-custom-variable', key, }; return executeAction(event, mode, {}, moduleId); } };

注意两点：其一，函数仅在key非空时才会触发动作，空 Key 调用会被静默忽略；其二，Key 会经过getResolvedValue解析（见 eventsSlice.js），因此你可以在 Key 位置使用{{ }}表达式动态指定变量名，例如actions.unSetVariable({{ variables.currentKeyName }})。

底层实现：Unset variable 在运行时发生了什么

理解底层实现有助于判断删除变量后的副作用。Unset variable 动作的核心实现在 resolvedSlice.js 中：

unsetVariable: (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); },

从实现可以看到，删除一个变量并非简单的内存清理，而是触发了一连串连锁反应：

1. 同步删除状态：从运行时状态exposedValues.variables中delete该 Key，同步写入保证同一 RunJS 上下文中后续读取立即返回undefined；
2. 移除依赖节点：removeNode('variables.${key}')会从依赖图中移除该变量节点，切断依赖该变量的组件、表达式与查询之间的关联；
3. 更新依赖值：updateDependencyValues通知所有引用variables.<key>的表达式重新求值，因此依赖该变量的组件属性（如 Text 的文本、Table 的 Data）会立刻刷新；
4. 重建变量提示：rebuildVariableHints更新编辑器中的变量自动补全提示，保证编码体验与实际状态一致。

这也解释了为什么 Unset variable 与直接将变量设为空字符串不同：setVariable('name', '')会保留 Key 并让variables.name求值为空字符串，而unSetVariable('name')会彻底移除 Key，使variables.name变为undefined。在条件判断如{{ variables.name }}或if (variables.name)中，二者行为截然不同，设计业务逻辑时需加以区分。

全部删除的批量实现

unset-all-custom-variables动作对应unsetAllVariables（resolvedSlice.js），它会遍历所有已存在的变量并逐个执行removeNode与updateDependencyValues，最后将变量表重置为空对象。批量删除适用于退出登录、重置整个应用状态等场景。

实战场景：Unset variable 的典型用法

场景一：表单提交后清理临时状态

使用变量暂存表单中间态数据，提交完成后删除变量，防止用户二次编辑时读到残留数据：

// 提交成功后执行 await queries.saveUser.run(); // 清理临时变量 actions.unSetVariable('formDraft'); actions.unSetVariable('editingUserId');

场景二：模拟加载状态控制（变量替代法）

参考 variables.md 中的官方做法：先用变量缓存查询数据，避免 Table 组件在数据更新时闪烁加载动画；在数据彻底废弃后，再通过 Unset variable 释放变量，例如切换筛选条件时：

// 切换筛选条件：先删除缓存变量，再重新拉取数据 actions.unSetVariable('loadedData'); await queries.getData.run();

场景三：页面退出时的变量回收

利用页面的On page leave或按钮的On click事件，在离开页面或关闭弹窗时删除页面级变量，避免跨页面污染：

Event: On click Action: Unset page variable Key: visitCount

注意事项与最佳实践

• Key 大小写敏感：变量名按字符串精确匹配，unSetVariable('Name')无法删除name变量；
• 删除不存在的变量不会报错：从实现看，delete对不存在的 Key 是安全的空操作，可放心调用；
• 区分空值与 undefined：如需保留 Key 仅清空内容用setVariable(key, '')；如需彻底移除 Key 用unSetVariable(key)；
• Debounce 仅影响触发时机：防抖延迟的是动作执行时间，不改变删除语义，适合与其他动作串联时控制时序；
• 善用批量清理：当应用包含大量动态创建的变量时，优先使用Unset all variables避免逐个删除遗漏。

通过事件处理器与 RunJS 两种方式组合使用 Unset variable，再配合对底层依赖更新机制的理解，你可以在 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