企业官网建设流程全解析

ToolJet 事件操作实战：使用 Set localStorage 操作实现浏览器本地数据持久化

【免费下载链接】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 localStorage（设置本地存储）事件操作（Action）的完整用法。该操作允许你在组件事件触发时，将指定的key与对应的value写入浏览器 localStorage，从而把不需要进入数据库的数据持久化在客户端。读完本文，你将掌握：如何通过事件处理器将组件值写入 localStorage、如何通过Run JavaScript code查询读取该值并驱动其他组件显示、如何使用 debounce（防抖）控制操作执行时机，以及如何从 RunJS 查询中直接调用actions.setLocalStorage。

一、Set localStorage 操作是什么

Set localStorage是 ToolJet 内置的事件操作（Action）之一，用于向浏览器本地存储中写入一个键值对。它的语义与浏览器原生 APIlocalStorage.setItem(key, value)完全一致，但做了两层增强：

1. key 与 value 都支持动态解析：可以填写字面量，也可以填入{{...}}双大括号表达式（如组件属性、查询结果），事件触发时会先解析再写入；
2. 通过事件处理器串联触发：它与Run query、Show alert、Copy to clipboard等操作一样，挂载在组件的任意事件上（如按钮的On click）。

从 ToolJet 前端源码 eventsSlice.js 可以看到该操作在事件分发器中的真实实现：

case 'set-localstorage-value': { const key = getResolvedValue(event.key, customVariables, moduleId); const value = getResolvedValue(event.value, customVariables, moduleId); localStorage.setItem(key, value); return Promise.resolve(); }

这段代码印证了两个关键事实：

• 操作内部先通过getResolvedValue对key和value进行表达式求值，因此你在配置面板中填写的{{components.textinput1.value}}这类动态值会在执行时被替换为真实值；
• 最终落地的动作就是浏览器原生的localStorage.setItem，数据保存在当前浏览器环境中，刷新页面后依然存在。

二、典型使用场景

文档中列出了 localStorage 最常见、最有价值的两类场景：

• 保存表单值，避免用户刷新页面后丢失：例如一个多字段表单，用户填写到一半误刷新页面，通过 localStorage 可以在页面重新加载后自动回填，改善填写体验；
• 存储不进入数据库的临时数据：例如界面偏好、临时筛选状态、页面级配置等，这类数据既不需要服务端持久化，也不希望随请求发送到后端。

此外，从更广泛的前端实践看，localStorage 还适合存放跨页面共享的轻量状态（如主题模式、上次访问位置等），只要数据量小、无敏感信息、无需跨设备同步即可。

三、实战示例：将组件值写入 localStorage 并驱动显示

原文档提供了一个完整的五步示例，下面完整复现并补充细节说明。最终效果是：在按钮上写入本地存储值，再通过一个 RunJS 查询读取它，让 Text 组件实时显示该值。

第 1 步：向画布添加组件

在应用画布（Canvas）上依次添加Text Input、Button和Text三个组件：

组件默认会被命名为textinput1、button1、text1，后续步骤中的引用依赖这些默认名称；如果你重命名了组件，表达式中的引用也要同步修改。

第 2 步：在按钮上配置 Set localStorage 事件

选中 Button 组件，在右侧属性面板中找到Events（事件）区域，添加一个新的事件处理器（Event Handler）：

• Event（事件）：On click（点击按钮时触发）；
• Action（操作）：Set local storage；
• Key：localtest（自定义的存储键名）；
• Value：{{components.textinput1.value}}（动态取 Text Input 当前输入的值）。

这样，每次点击按钮，ToolJet 就会把键localtest的值设置为 Text Input 组件当时的输入内容。

第 3 步：创建 RunJS 查询读取本地存储

在 Query Panel 中新建一个Run JavaScript code类型的查询（默认命名为runjs1），输入以下代码：

return localStorage.getItem("localtest");

点击 Query Panel 上的Run（运行）按钮执行一次。该查询通过浏览器原生localStorage.getItem读取第 2 步写入的localtest键，并把值作为查询结果queries.runjs1.data返回。

第 4 步：让 Text 组件显示查询结果

选中Text组件，在其Text（文本）属性中填入：

{{queries.runjs1.data}}

此时 Text 组件展示的就是runjs1查询返回的本地存储值。

第 5 步：在按钮上串联 Run query 并设置防抖

为了让「点击按钮 → 更新 localStorage → Text 组件刷新显示」形成完整闭环，还需要让按钮在写入本地存储后重新运行runjs1查询。回到 Button 组件，再添加一个事件处理器：

• Event：On click；
• Action：Run query；
• Query：runjs1；
• Debounce（防抖）：300（毫秒）。

现在完整的交互链路是：每点击一次 Button，先执行Set local storage将 Text Input 的值写入localtest键，再执行Run query触发runjs1重新读取，最后 Text 组件展示最新值。

:::info 防抖说明 Debounce 字段默认是空的（不防抖，立即执行）。你可以填入一个数值，单位是毫秒，表示事件触发后延迟多久才真正执行操作。例如填300表示延迟 300ms 后执行。这在需要合并高频触发（如连续输入、连续点击）时非常有用。 :::

关于防抖的源码佐证

从源码看，事件执行入口executeAction本身就被debounce包装（见 eventsSlice.js）：

executeAction: debounce((eventObj, mode, customVariables = {}, moduleId = 'canvas') => { ... }, ...)

也就是说，事件处理器的执行统一经过防抖层，你在配置面板中填写的 debounce 数值正是控制该层延迟的关键参数；此外，事件处理器还支持disabled（禁用）与runOnlyIf（条件执行）等高级开关，进一步控制操作的触发条件。

四、在 RunJS 查询中直接设置 localStorage

除了通过组件事件处理器使用该操作外，ToolJet 还在 RunJS 查询环境中暴露了等价的动作函数actions.setLocalStorage。它的语法为：

actions.setLocalStorage('key', 'value');

在查询面板的Run JavaScript code中即可直接调用，例如：

actions.setLocalStorage('localtest', components.textinput1.value); return actions.getVariable('localtest'); // 或使用 localStorage.getItem('localtest') 验证

这一用法记录在 run-action-from-runjs.md 文档中，与事件处理器方式互为补充：

• 事件处理器方式：面向 UI 交互，由组件事件驱动，适合「用户点击/输入后写入」；
• RunJS 方式：面向逻辑编排，可在查询中与其他代码混合执行，适合在复杂业务逻辑中按条件写入。

五、使用要点与注意事项

综合文档与源码，使用Set localStorage时建议注意以下几点：

1. 数据仅存于浏览器端：localStorage 属于浏览器本地存储，不随网络请求发送到服务器，也无法跨浏览器、跨设备同步；需要服务端持久化的数据请使用数据库数据源。
2. 值为字符串：localStorage.setItem要求值最终为字符串。若getResolvedValue解析出的 value 是对象或数组（例如{{components.table1.selectedRow}}），建议在表达式中用JSON.stringify(...)包裹，读取时再用JSON.parse还原。
3. 容量与安全：localStorage 容量通常有限（浏览器一般约 5MB），且存储内容在浏览器开发者工具中可见，不适合存放敏感信息（如令牌、密码）。
4. 命名规范：键名建议使用有业务含义且全局唯一的前缀（如localtest），避免与应用内其他逻辑使用的键冲突。
5. 结合防抖使用：对于高频事件（如输入框变化触发），通过 Debounce 字段设置毫秒级延迟可以避免频繁写入。

六、总结

Set localStorage是 ToolJet 事件操作体系中处理浏览器端轻量状态的核心手段：它以原生localStorage.setItem为底层实现，通过getResolvedValue支持动态表达式，配合组件事件、RunJS 查询与防抖机制，可以轻松实现「表单防丢失」「界面状态记忆」「跨组件状态共享」等常见需求。本文的完整示例——组件写入 → RunJS 读取 → Text 显示 → 按钮联动刷新——可以直接复用到你自己的应用中，作为本地持久化交互的标准范式。

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