ToolJet RunJS 查询执行 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在 ToolJet 应用构建器中RunJS 查询允许你在 JavaScript 代码片段里直接调用平台内置的 Actions从而把查询触发、变量管理、弹窗控制、文件导出、页面跳转、消息提示等能力统一编排进一段脚本逻辑中。本指南以 ToolJet 2.50.0-LTS 官方文档 run-action-from-runjs 为主线逐条讲解每种 Action 的调用语法与典型示例并结合仓库前端源码如 eventsSlice.js说明底层实现与边界条件。读完本文你将能在 RunJS 查询中熟练完成查询联动、变量读写、弹窗/提示、文件生成、应用跳转以及 async-await 多动作编排等实战操作。一、RunJS 查询与 Actions 的对应关系ToolJet 的 App Builder 在可视化层面把交互能力抽象为一组事件动作Actions它们既可以在组件事件面板中通过表单配置也可以在 RunJS / RunPy 查询中通过代码直接调用。在仓库中这一组动作被统一定义在两处ActionTypes.js事件面板里可选的 Action 列表包含run-query、show-alert、show-modal、set-custom-variable、go-to-app、generate-file等constants/actions.js代码编辑器提示code hints中暴露给用户的 Actions 函数名清单即ACTIONS数组。两处形成一一对应的关系面板上配置的run-query对应代码中的actions.runQuery()set-custom-variable对应actions.setVariable()。RunJS 查询本质上就是把这段 JS 代码注入到执行上下文从而复用同一套executeAction事件分发机制见 eventsSlice.js。在编写代码时你可以选择两种风格全局查询对象风格queries.查询名.run()每个查询对象由 queryPanelSlice.js 动态构建actions命名空间风格actions.runQuery(查询名)直接调用事件分发。二、运行查询Run Query2.1 两种调用语法queries.getSalesData.run() // replace getSalesData with your query name或等价的 actions 风格await actions.runQuery(getSalesData) // replace getSalesData with your query name从源码看queries.name.run(params, callbackFns)内部会对params做对象校验非对象会被归一为空对象并按查询定义的options.parameters过滤出合法参数后调用actions.runQuery见 queryPanelSlice.js。而actions.runQuery(queryName, parameters, moduleId, callbackFns)会按名称在当前模块的查询列表中查找目标查询并构造{ actionId: run-query, queryId, queryName, parameters, callbackFns }事件交由executeAction执行见 eventsSlice.js。需要留意两个边界条件源码中有明确处理若查询名称不存在会弹出Query not found错误提示若在查询自身的代码中调用自身queryId query?.id会弹出Cannot run query from itself提示防止无限递归见 eventsSlice.js。2.2 带参数运行当目标查询定义了参数时传入的参数会被query.options.parameters逐个过滤只保留声明过的参数名见 eventsSlice.jsawait actions.runQuery(getUserById, { id: components.dropdown1.selectedValue });三、获取查询结果数据Get Query Data触发查询后若想立即在 RunJS 中使用其返回结果可在await queries.name.run()之后调用以下三个函数它们由 queryPanelSlice.js 以实时 getter方式提供函数返回值对应底层字段getData()查询处理后的数据resolvedState中该查询的datagetRawData()查询的原始响应数据该查询的rawDatagetLoadingState()查询是否处于加载中该查询的isLoading// 触发查询并读取数据 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();源码中注释明确说明这些 getter 是live getter在await queries.x.run()完成后任何字段data、error、request、response、metadata、responseHeaders等都会反映本次运行的最新结果见 queryPanelSlice.js。因此getData()/getRawData()必须放在await ...run()之后调用才能拿到刚运行完的数据否则读到的是上一次或空的状态。四、变量管理设置、删除与读取4.1 设置变量Set Variablesactions.setVariable(variableName, variableValue)源码中setVariable(key, value)会校验 key 非空随后构造actionId: set-custom-variable事件见 eventsSlice.js。4.2 删除变量Unset Variableactions.unSetVariable(variableName)对应事件为unset-custom-variablekey 为空时直接忽略见 eventsSlice.js。另外还提供了批量删除actions.unsetAllVariables()对应unset-all-custom-variables见 eventsSlice.js。4.3 读取变量Get Variables设置变量后如需在同一段 RunJS 代码内立刻取回使用getVariable与getPageVariable// 设置并读取普通变量 actions.setVariable(mode,dark); //replace mode with your desired variable name return actions.getVariable(mode);// 设置并读取页面级变量 actions.setPageVariable(number,1); //replace number with your desired variable name return actions.getPageVariable(number);页面级变量的对应实现为setPageVariable(key, value)→set-page-variable与getPageVariable(key)→get-page-variable见 eventsSlice.js。它们与普通变量的区别在于作用域普通变量在整个应用生命周期内有效页面变量随页面切换而隔离或清空。五、用户会话与界面控制5.1 登出Logoutactions.logout();实现上构造actionId: logout事件最终调用logoutAction()来自/AppBuilder/_utils/auth完成当前用户登出见 eventsSlice.js。适合在退出登录按钮的 onClick 事件中通过 RunJS 触发。5.2 打开 / 关闭弹窗Show / Close Modalactions.showModal(modalName) actions.closeModal(modalName)源码中showModal(modalName)会在当前组件树中按组件名称component.name modalName查找 Modal 组件的实例 id再构造show-modal/close-modal事件见 eventsSlice.js。因此参数必须与画布上 Modal 组件的名称完全一致否则找不到对应弹窗。5.3 设置本地存储Set Local Storageactions.setLocalStorage(key, value);对应set-localstorage-value事件见 eventsSlice.js。数据写入浏览器localStorage可在不同页面、甚至重新打开应用后读取适合存放主题偏好、用户设置等轻量持久化数据。5.4 复制到剪贴板Copy to Clipboardactions.copyToClipboard(contentToCopy)实现上构造copy-to-clipboard事件最终调用copyToClipboard来自/_helpers/appUtils执行复制见 eventsSlice.js。注意浏览器对剪贴板 API 的调用往往要求用户手势如点击按钮上下文在 RunJS 中同步调用通常没有问题。六、生成文件Generate File6.1 语法与参数actions.generateFile(fileName, fileType, data)参数说明可选值/类型fileName生成文件的名称字符串fileType文件类型csv、plaintext、pdfdata写入文件的数据任意数据可用{{ }}引用组件/查询值源码中对三个参数做了非空校验任一缺失都会弹出错误提示Action failed: fileName, fileType and data are required并构造generate-file事件见 eventsSlice.js。6.2 生成 CSV 文件actions.generateFile(csvfile1, csv, {{components.table1.currentPageData}}) // generate a csv file named csvfile1 with the data from the current page of table6.3 生成文本文件actions.generateFile(textfile1, plaintext, {{JSON.stringify(components.table1.currentPageData)}}) // generate a text file named textfile1 with the data from the current page of table (stringified)文本格式下建议先用JSON.stringify()将对象数组序列化为字符串否则写入内容可能不符合预期。6.4 生成 PDF 文件actions.generateFile(Pdffile1, pdf, {{components.table1.currentPageData}}) // generate a text file named Pdffile1 with the data from the current page of table文件生成的底层逻辑由/_lib/generate-file提供见 eventsSlice.js。这一动作非常适合一键导出报表/表格数据场景例如把表格当前页数据导出为 CSV 供下载。七、应用间跳转Go to Appactions.goToApp(slug, queryparams)两个参数的含义slug目标应用的 slug。可以在已发布应用的 URL 中application/之后找到也可以在 App Builder 右上角点击Share按钮弹出的分享弹窗中获取queryparams以二维数组形式提供的查询参数格式为[ [key1,value1 ], [key2,value2] ]。actions.goToApp(sales-dashboard, [[period, 2026-Q3], [region, APAC]]);实现上构造actionId: go-to-app事件并携带slug与queryParams见 eventsSlice.js。在事件面板中该动作对应go-to-app见 ActionTypes.js。目标应用收到参数后可通过globals.urlparams读取。八、消息提示Show Alertactions.showAlert(alert type , message )可用提示类型info、success、warning、danger。示例actions.showAlert(error , This is an error )对应show-alert事件参数为alertType与message见 eventsSlice.js。提示会以顶部/角落的 Toast 形式展示适合在分支逻辑中给出成功或失败反馈。注意官方示例中使用了error而标准可选值集合为info/success/warning/danger实际使用建议从标准集合中选取以保证样式符合预期。九、组合使用async-await 编排多个动作在 RunJS 查询中运行多个动作时必须使用async-await来保证顺序执行否则后续动作会在前序查询尚未完成时就启动。典型示例按 5 秒间隔轮询两个查询并在每次完成后弹出信息提示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 秒调用一次countdownawait确保restapi1→restapi2→ 提示按顺序完成。如果你需要更精细的定时/间隔运行查询能力可进一步参考仓库中的完整指南 run-query-at-specified-intervals。十、补充更多可用动作与排查建议除了文档列出的动作ACTIONS常量见 constants/actions.js中还暴露了以下能力可在 RunJS 中按同样风格调用函数作用actions.resetQuery(查询名)重置查询状态对应reset-queryactions.abortQuery(查询名)中止正在运行的查询对应abort-queryactions.switchPage(页面名)切换当前应用页面actions.logInfo(...)/actions.logError(...)向调试器输出日志actions.toggleAppMode(模式)切换应用的编辑/查看模式actions.scrollComponentInToView(...)将组件滚动到可视区域排查建议查询名写错runQuery找不到查询时会提示Query not found请核对查询面板中的名称区分大小写自调用不要在 RunJS 查询里运行它自己否则提示Cannot run query from itselfModal 名称不匹配showModal/closeModal按组件名称精确匹配请确认传入的名称与画布组件名一致数据时序getData()等读取函数必须在await ...run()之后调用代码提示编辑器内输入actions.或queries.时会基于ACTIONS常量与查询对象实时给出函数提示可减少拼写错误见 codeHinterSlice.js。相关文档官方指南原文run-action-from-runjsActions 列表定义ActionTypes.jsActions 代码提示常量constants/actions.jsActions 核心实现eventsSlice.js查询对象run/getData/getRawData/getloadingState实现queryPanelSlice.js【免费下载链接】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），仅供参考