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)完全一致但做了两层增强key 与 value 都支持动态解析可以填写字面量也可以填入{{...}}双大括号表达式如组件属性、查询结果事件触发时会先解析再写入通过事件处理器串联触发它与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 HandlerEvent事件On click点击按钮时触发Action操作Set local storageKeylocaltest自定义的存储键名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 组件再添加一个事件处理器EventOn clickActionRun queryQueryrunjs1Debounce防抖300毫秒。现在完整的交互链路是每点击一次 Button先执行Set local storage将 Text Input 的值写入localtest键再执行Run query触发runjs1重新读取最后 Text 组件展示最新值。:::info 防抖说明 Debounce 字段默认是空的不防抖立即执行。你可以填入一个数值单位是毫秒表示事件触发后延迟多久才真正执行操作。例如填300表示延迟 300ms 后执行。这在需要合并高频触发如连续输入、连续点击时非常有用。 :::关于防抖的源码佐证从源码看事件执行入口executeAction本身就被debounce包装见 eventsSlice.jsexecuteAction: 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时建议注意以下几点数据仅存于浏览器端localStorage 属于浏览器本地存储不随网络请求发送到服务器也无法跨浏览器、跨设备同步需要服务端持久化的数据请使用数据库数据源。值为字符串localStorage.setItem要求值最终为字符串。若getResolvedValue解析出的 value 是对象或数组例如{{components.table1.selectedRow}}建议在表达式中用JSON.stringify(...)包裹读取时再用JSON.parse还原。容量与安全localStorage 容量通常有限浏览器一般约 5MB且存储内容在浏览器开发者工具中可见不适合存放敏感信息如令牌、密码。命名规范键名建议使用有业务含义且全局唯一的前缀如localtest避免与应用内其他逻辑使用的键冲突。结合防抖使用对于高频事件如输入框变化触发通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ToolJet 事件操作实战：使用 Set localStorage 操作实现浏览器本地数据持久化
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)完全一致但做了两层增强key 与 value 都支持动态解析可以填写字面量也可以填入{{...}}双大括号表达式如组件属性、查询结果事件触发时会先解析再写入通过事件处理器串联触发它与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 HandlerEvent事件On click点击按钮时触发Action操作Set local storageKeylocaltest自定义的存储键名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 组件再添加一个事件处理器EventOn clickActionRun queryQueryrunjs1Debounce防抖300毫秒。现在完整的交互链路是每点击一次 Button先执行Set local storage将 Text Input 的值写入localtest键再执行Run query触发runjs1重新读取最后 Text 组件展示最新值。:::info 防抖说明 Debounce 字段默认是空的不防抖立即执行。你可以填入一个数值单位是毫秒表示事件触发后延迟多久才真正执行操作。例如填300表示延迟 300ms 后执行。这在需要合并高频触发如连续输入、连续点击时非常有用。 :::关于防抖的源码佐证从源码看事件执行入口executeAction本身就被debounce包装见 eventsSlice.jsexecuteAction: 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时建议注意以下几点数据仅存于浏览器端localStorage 属于浏览器本地存储不随网络请求发送到服务器也无法跨浏览器、跨设备同步需要服务端持久化的数据请使用数据库数据源。值为字符串localStorage.setItem要求值最终为字符串。若getResolvedValue解析出的 value 是对象或数组例如{{components.table1.selectedRow}}建议在表达式中用JSON.stringify(...)包裹读取时再用JSON.parse还原。容量与安全localStorage 容量通常有限浏览器一般约 5MB且存储内容在浏览器开发者工具中可见不适合存放敏感信息如令牌、密码。命名规范键名建议使用有业务含义且全局唯一的前缀如localtest避免与应用内其他逻辑使用的键冲突。结合防抖使用对于高频事件如输入框变化触发通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考