ToolJet Actions 事件动作机制全解析从事件触发到 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导读Actions动作是 ToolJet 应用构建器中连接事件与行为的关键机制——当按钮被点击、查询执行完成或定时器到达指定间隔时动作决定了应用接下来要做什么弹窗提示、执行数据查询、切换页面、生成文件等。本文以 ToolJet Actions 概念文档为核心结合 动作参考文档 与 RunJS 动作调用指南系统讲解动作的类型、两种配置方式、全部内置动作的参数与语法并从 前端状态管理源码 层面解释其底层实现原理。读完本文你将能够熟练地在组件事件处理器中配置动作也能在 RunJS 查询中通过代码动态编排多动作执行。Actions 是什么在 ToolJet 中Actions 是可由应用内事件触发的多功能函数。基于用户交互点击按钮、输入变化、查询完成等动作可以被配置为显示弹窗提示Show alert、执行数据查询Run query、切换页面Switch page、跳转到其他应用Go to app、管理模态框Show/Close modal、复制文本到剪贴板、向 localStorage 写入值、从应用数据生成可下载文件等。动作本身不单独存在它总是与**事件Event**配对出现事件是触发器发生了什么动作是响应器做什么。例如用户点击按钮这一事件可以触发运行刷新数据的查询这一动作而查询执行成功又是一个新事件可以继续触发弹出成功提示的下一个动作。动作的两种配置方式ToolJet 提供两种配置动作的途径分别适用于声明式静态场景和编程式动态场景方式一在组件/查询的配置面板中新建事件在任何组件或查询的配置设置中都可以建立一个新的Event 事件处理器然后为事件指定要执行的动作。这是最直观的方式选中目标组件例如按钮 Button在右侧配置面板中找到 Event Handlers事件处理器点击New Event Handler新建事件处理器定义触发条件Event如On click与要采取的动作Action如 Run query、Show alert、Switch page。事件可以链式串联以执行一系列逻辑操作例如查询 A 执行完成后触发事件该事件再运行查询 B查询 B 完成后再弹出一个提示。这样一次用户交互如一次点击就能触发一整条动作链。方式二通过 RunJS 查询动态调用对于更动态的交互场景可以在应用中新建一个Run JavaScript codeRunJS查询在其代码编辑器中直接调用actions.*与queries.*API 来触发动作。这种方式支持基于任意条件分支决定执行哪个动作if/else逻辑在指定时间间隔内反复执行动作配合setInterval在动作执行前后读取查询返回的数据实现数据加工后触发后续动作。两种方式并不互斥可以在按钮事件中运行 RunJS 查询再由 RunJS 查询内部编排多个动作形成事件 → 代码 → 多动作的复合流程。全部内置动作参考以下动作均可在 Actions Reference 动作参考目录 中查到完整说明。按文档目录划分ToolJet 2.50.0-LTS 共提供 17 个内置动作动作作用参考文档Show alert弹出提示消息show-alert.mdRun query触发数据查询执行run-query.mdOpen webpage在新网页中打开链接open-webpage.mdSwitch page切换当前应用页面switch-page.mdGo to app跳转到另一个 ToolJet 应用go-to-app.mdShow modal打开模态框show-modal.mdClose modal关闭模态框close-modal.mdCopy to clipboard复制文本到剪贴板copy-to-clipboard.mdSet localstorage写入浏览器 localStorageset-localstorage.mdSet variable创建全局变量set-variable.mdUnset variable删除已创建的全局变量unset-variable.mdSet page var创建页面级变量set-page-var.mdUnset page var删除页面级变量unset-page-var.mdControl component以编程方式控制组件control-component.mdGenerate file从应用数据生成可下载文件generate-file.mdSet table page设置表格组件的当前页set-table-page.mdLogout将当前登录用户登出logout.md动作通用参数Debounce防抖在事件处理器的动作配置中多数动作带有Debounce 字段。它默认为空可填入一个数值单位是毫秒表示延迟多少时间后再执行该动作。例如填入300即延迟 300ms 执行常用于防止快速重复点击导致的抖动或重复请求。Show alert 示例以最常用的 Show alert 为例其配置只需两个参数Message自定义提示内容Alert type4 种类型之一——Info信息、Success成功、Warning警告、Error错误。在 RunJS 查询中以代码触发动作ToolJet 允许在 RunJS 查询中执行全部上述动作。下面按动作分类给出完整语法与示例均出自 Run Actions from RunJS query。Run Query运行查询两种等价写法将getSalesData替换为你的查询名queries.getSalesData.run()或await actions.runQuery(getSalesData)触发查询并立即取回数据RunJS 提供三个配套函数便于在动作链中即时消费查询结果// 触发查询并获取处理后的数据 await queries.getSalesData.run(); let value queries.getSalesData.getData(); // 触发查询并获取原始数据 await queries.getCustomerData.run(); let value queries.getCustomerData.getRawData(); // 触发查询并读取其加载状态 await queries.getTodos.run() let value queries.getTodos.getLoadingState();getData()返回查询结果数据getRawData()返回未经处理的原始响应getLoadingState()返回布尔型加载状态。Set / Unset / Get Variable变量操作// 创建或覆盖全局变量 actions.setVariable(variableName, variableValue) // 删除全局变量 actions.unSetVariable(variableName) // 设置后立即读取 actions.setVariable(mode,dark); return actions.getVariable(mode); // 页面级变量的设置与读取 actions.setPageVariable(number,1); return actions.getPageVariable(number);变量机制是 ToolJet 应用内跨组件共享状态的基础设施相关概念可进一步阅读 variables.md。Show / Close Modal模态框控制actions.showModal(modalName) actions.closeModal(modalName)将modalName替换为画布中模态框组件Modal的名称。其他常用动作// 将内容复制到剪贴板 actions.copyToClipboard(contentToCopy) // 写入浏览器 localStorage actions.setLocalStorage(key, value); // 登出当前用户 actions.logout(); // 跳转到另一个应用slug 可从发布应用 URL 中 application/ 之后获取 // queryparams 格式为 [ [key1,value1], [key2,value2] ] actions.goToApp(slug, queryparams)goToApp的slug也可以从应用构建器右上角Share按钮打开的分享弹窗中获取。Show Alert弹窗提示actions.showAlert(alert type, message)可用的 alert 类型为info、success、warning、danger。示例actions.showAlert(error, This is an error)Generate File生成文件actions.generateFile(fileName, fileType, data)三个参数说明fileName文件名字符串fileType支持csv、plaintext、pdfdata要写入文件的数据。实际示例从表格组件导出数据// 生成 CSV取表格当前页数据 actions.generateFile(csvfile1, csv, {{components.table1.currentPageData}}) // 生成文本先 JSON 序列化再写入 actions.generateFile(textfile1, plaintext, {{JSON.stringify(components.table1.currentPageData)}}) // 生成 PDF actions.generateFile(Pdffile1, pdf, {{components.table1.currentPageData}})一次运行多个动作async-await在 RunJS 查询中编排多个动作时必须使用async-await语法保证顺序执行。下面示例每 5 秒依次运行两个 REST API 查询然后弹出提示actions.setVariable(interval, setInterval(countdown, 5000)); async function countdown(){ await queries.restapi1.run() await queries.restapi2.run() await actions.showAlert(info,This is an information) }该模式常与 在指定时间间隔运行查询 配合实现轮询类功能。源码级原理动作在运行时如何被解析执行从源码结构看RunJS 中可用的queries.*与actions.*API 由前端状态管理层的查询面板切片query panel slice动态构建。在 queryPanelSlice.js 中每个查询对象被注入了一组方法run()/run(params)调用actions.runQuery(query.name, ...)触发查询执行reset()调用actions.resetQuery(query.name)重置查询状态abort()调用actions.abortQuery(query.name, ...)中止正在执行的查询getData()读取实时查询状态中的data字段getLiveQueryState()?.data。即开发者写下的queries.getSalesData.run()最终会落到统一的actions.runQuery内部调度器上由它把运行查询这一动作派发到对应查询的运行时。这也解释了为何事件处理器中的 Run query 动作与 RunJS 中的actions.runQuery()行为完全一致——两者共用同一套动作执行内核。从代码结构还可以推断动作执行器以统一的actions对象暴露给 RunJS 沙箱因此actions.showAlert、actions.setVariable、actions.goToApp等 API 与事件处理器中的声明式配置走的是同一条底层执行路径只是入口不同UI 配置 vs 代码调用。在 scriptAnalysis.ts 中还可以看到对脚本中actions.*调用模式的静态分析用于识别查询依赖与动作引用。实践建议与注意事项优先声明式复杂逻辑用 RunJS简单的一对一事件 → 动作直接在组件事件处理器中配置涉及条件判断、数据加工、定时轮询或多动作编排时改用 RunJS 查询更清晰。善用 getData() 串联查询需要先取 A 查询结果、再作为参数运行 B 查询的流水线场景在 RunJS 中用await queries.A.run(); queries.A.getData()即可轻松实现无需借助中间组件。注意动作的异步性RunJS 中多动作串行必须await不加await时动作并发执行顺序无法保证。防抖字段用于体验优化在事件处理器中为高频触发的动作如表单提交、按钮点击设置合理毫秒级 Debounce可避免误触与重复请求。更多动作细节完整参数与界面截图请查阅 Actions Reference 目录组件专属的动作如表格翻页、图表交互见 component-specific-actions.md。【免费下载链接】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），仅供参考