ToolJet RunJS 查询动作指南在 JavaScript 中触发查询、操作变量与组件【免费下载链接】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导读RunJSRun JavaScript code查询是 ToolJet 应用构建器中最灵活的扩展点之一除了直接执行任意 JavaScript 逻辑它还暴露了一套完整的actionsAPI 与queriesAPI让你可以在代码中触发其他查询、读写应用变量与页面变量、弹出/关闭模态框、写浏览器 localStorage、生成文件乃至跳转应用。本文以 run-action-from-runjs.md 为主体系统讲解每个动作的语法、参数与示例并结合 eventsSlice.js 等源码说明其底层实现帮助你写出可复用、可维护的 RunJS 逻辑。Run Query在 RunJS 中触发其他查询在 RunJS 查询中触发运行一个已定义查询有两种等价写法queries.getSalesData.run() // 将 getSalesData 替换为你的查询名或使用actions.runQueryawait actions.runQuery(getSalesData) // 将 getSalesData 替换为你的查询名两种语法的最终效果一致。从源码看queries.queryName是查询面板暴露给运行时的查询对象封装见 queryPanelSlice.js其run方法最终调用actions.runQuery(query.name, processedParams, moduleId, callbackFns)而actions.runQuery在 eventsSlice.js 中根据查询名在dataQuery.queries.modules[moduleId]中查找目标查询组装actionId: run-query事件后交由executeAction分发执行。值得注意的是源码会校验查询是否可运行isQueryRunnable并阻止查询运行自身提示 Cannot run query from itself——因此在 RunJS 里触发查询时不要在目标查询自身内部调用自己。下图展示了在 RunJS 查询编辑器中用两种语法同时触发getSalesData查询的示例Get Query Data触发后立即读取查询数据仅触发查询往往不够你常常需要在同一个 RunJS 查询中先运行、后读取结果。queries.name对象在运行完成后暴露了三个读取方法// 触发查询并读取 data处理后的数据 await queries.getSalesData.run(); let value queries.getSalesData.getData();// 触发查询并读取 rawData原始数据 await queries.getCustomerData.run(); let value queries.getCustomerData.getRawData();// 触发查询并读取加载状态 await queries.getTodos.run(); let value queries.getTodos.getLoadingState();这三个方法的底层是活取值live getter机制源码在 queryPanelSlice.js 中为每个查询对象定义了getData: () getLiveQueryState()?.data、getRawData: () getLiveQueryState()?.rawData以及加载状态读取器并通过 Object.defineProperties 为查询的其他属性如error、request、responseHeaders等动态绑定同样的实时 getter注释明确指出其设计目的在await queries.x.run()之后任何字段读取都能反映本次运行完成后的最新状态。因此推荐模式是先用await queries.name.run()确保查询执行完毕再调用getData()/getRawData()读取结果避免拿到上一次运行的旧数据。变量操作Set / Unset / GetSet Variable设置变量创建或更新一个应用级变量actions.setVariable(variableName, variableValue)例如actions.setVariable(mode, dark);源码中setVariable会组装actionId: set-custom-variable事件见 eventsSlice.js变量一旦设置即可在整个应用范围内通过variables.key访问。下图是 RunJS 中设置test数值 123与test2字符串两个变量的实际界面Unset Variable删除变量删除之前通过 Set Variable 创建的变量actions.unSetVariable(variableName)对应底层事件为unset-custom-variable见 eventsSlice.js。使用场景包括清理临时标记、重置筛选状态等。Get Variables读取变量RunJS 中设置变量后若想在同一段代码里立刻读取可使用getVariable与getPageVariableactions.setVariable(mode, dark); // 将 mode 替换为你的变量名 return actions.getVariable(mode);actions.setPageVariable(number, 1); // 将 number 替换为你的变量名 return actions.getPageVariable(number);其中setPageVariable/getPageVariable操作的是页面级变量——它只作用于当前页面无法跨页访问与全局变量不同详见 set-page-var.md 与 unset-page-var.md。对应源码实现位于 eventsSlice.js底层事件分别为set-page-variable与get-page-variable。同理删除页面变量可调用actions.unsetPageVariable(variableName)。Logout登出当前用户actions.logout();该动作会登出当前登录用户并跳转到登录页。源码中logout组装actionId: logout事件eventsSlice.js在事件分发时调用logoutAction()见 eventsSlice.js。适合在退出登录按钮或会话失效检测的 RunJS 逻辑中使用。Show Modal / Close Modal模态框控制打开指定模态框actions.showModal(modalName)关闭指定模态框actions.closeModal(modalName)modalName是画布上 Modal 组件的名称。源码实现eventsSlice.js会遍历当前页组件将组件名解析为内部 modal key 后分别派发show-modal/close-modal事件。常见的表单校验失败弹出提示模态框保存成功后自动关闭模态框等交互均可借此实现。Set Local Storage写入浏览器本地存储actions.setLocalStorage(key, value);该动作将key/value写入浏览器 localStorage底层事件为set-localstorage-value见 eventsSlice.js。典型用途包括保存表单草稿防止刷新丢失、缓存不落库的临时数据。与之配套的读取方式是在 RunJS 中直接使用浏览器 APIreturn localStorage.getItem(localtest);完整的存值 → 读取 → 回显到组件流程可参考 set-localstorage.md 中的分步示例Text Input 输入值经按钮事件写入 localStorage再通过 RunJS 查询读取并由 Text 组件展示。Copy to Clipboard复制内容到剪贴板actions.copyToClipboard(contentToCopy)将文本复制到系统剪贴板适合复制链接 / 复制订单号 / 复制 API Key等场景。底层实现来自 appUtils.js 的copyToClipboard工具函数事件分发见 eventsSlice.js。contentToCopy支持模板字符串与求值表达式例如actions.copyToClipboard(Order #${variables.orderId} has been created)Generate File按需生成并下载文件actions.generateFile(fileName, fileType, data)参数说明fileName生成文件的名称字符串fileType文件类型支持csv、plaintext、pdfdata写入文件的数据其格式取决于文件类型。常用示例以表格组件的当前页数据为数据源// 生成 csv 文件内容为表格当前页数据 actions.generateFile(csvfile1, csv, {{components.table1.currentPageData}}) // 生成文本文件内容为表格当前页数据序列化后的字符串 actions.generateFile(textfile1, plaintext, {{JSON.stringify(components.table1.currentPageData)}}) // 生成 pdf 文件内容为表格当前页数据 actions.generateFile(Pdffile1, pdf, {{components.table1.currentPageData}})三种文件类型对data的格式要求与 generate-file.md 一致CSV数据应为对象数组对象键作为表头。例如[ { name: John, email: johntooljet.com }, { name: Sarah, email: sarahtooljet.com } ]会生成name,email两列的 CSVTextplaintext数据应为字符串若数据源是对象数组需先用JSON.stringify序列化PDF既支持字符串生成纯文本 PDF也支持对象数组以表格形式呈现行列。源码中generateFile对三个参数做了非空校验缺失时提示 Action failed: fileName, fileType and data are required并派发generate-file事件eventsSlice.js文件生成逻辑由/_lib/generate-file模块承载。Go to App跳转到其他应用actions.goToApp(slug, queryparams)slug目标应用的标识可在已发布应用的 URL 中application/之后找到或在应用构建器右上角点击Share弹出的分享弹窗中获取queryparams以二维数组形式传递的查询参数格式为[ [key1,value1 ], [key2,value2] ]。源码中goToApp组装actionId: go-to-app事件eventsSlice.js事件分发时会解析 slug 与查询参数并拼接出/applications/slug形式的跳转 URLeventsSlice.js。注意目标应用需为**已发布released**状态见 go-to-app.md未发布的应用无法通过该动作打开。// 示例跳转到 slug 为 sales-dashboard 的应用并携带两个查询参数 actions.goToApp(sales-dashboard, [[region, apac], [year, 2026]])Show Alert弹出提示消息actions.showAlert(alert type , message )可用 alert 类型为info、success、warning、danger。示例actions.showAlert(error , This is an error)源码的事件分发eventsSlice.js展示了每种类型的实际表现success/error调用toast[type]info为普通 toastwarning额外带 ⚠️ 图标若 message 是对象会被自动JSON.stringify。可以在查询成功/失败分支中插入success/error提示为使用者提供即时反馈。组合多个动作async/await 与定时执行在一个 RunJS 查询中运行多个动作时必须使用async-await保证执行顺序。例如顺序触发两个查询再弹出信息提示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) }该模式常被用于按固定间隔轮询数据setInterval每 5 秒调用一次countdown内部依次触发两个查询并给出提示若想停止轮询可用clearInterval(variables.interval)。完整的定时拉取 REST 数据并渲染到表格的分步教程含创建应用、配置查询、开启Run query on page load、按钮停止轮询等见 run-query-at-specified-intervals.md。关键点setInterval的返回值interval id先通过actions.setVariable存入变量后续才能用variables.interval取出并clearInterval这正是前文 Set/Get Variable 动作的典型实战结合。小结与最佳实践优先await再取值使用queries.name.run()后通过getData()/getRawData()/getLoadingState()读取结果依赖源码中的 live getter 机制确保读到的是本次运行的最新状态查询名保持唯一actions.runQuery(name)、queries.name.run()均按名称定位查询重名会导致命中错误同时避免在查询内部触发自身变量作用域分清应用级变量用setVariable/unSetVariable/getVariable页面级变量用setPageVariable/getPageVariable/unsetPageVariable多页应用场景下务必区分文件生成注意数据格式CSV 传对象数组、plaintext 传字符串、PDF 两者皆可表格数据传 PDF/CSV 时可直接引用components.tableName.currentPageData多动作务必 async-awaitRunJS 中组合多个异步动作尤其是定时器内时用await保证串行顺序避免竞态。RunJS 查询把 ToolJet 的事件系统完整暴露给了 JavaScript从触发查询、读写变量到控制模态框、剪贴板、本地存储、文件下载与应用跳转全部可以在数十行代码内完成。你可以在 eventsSlice.js 中查阅每个动作的事件分发细节在 docs/versioned_docs/version-3.0.0-LTS/actions 下找到与每个动作对应的完整参考文档继续深入扩展你的应用。【免费下载链接】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），仅供参考