ToolJet RunJS 完全指南用 Run JavaScript Code 查询驱动低代码应用交互【免费下载链接】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/ToolJetRun JavaScript Code下文简称RunJS是 ToolJet 内置的一种代码型数据源它允许在查询编辑器中直接编写 JavaScript用来做计算、动态生成值以及与组件、其他查询进行编排联动。本文将基于仓库中 自定义 JavaScript 数据源文档 的主体内容结合 server 源码 中该数据源类型的注册方式完整讲解 RunJS 查询的创建、参数Parameters机制、跨查询调用技巧与常用示例帮助你直接把这些能力落地到自己的 ToolJet 应用里。一、RunJS 是什么一个内建的代码型数据源在 ToolJet 中查询Query不只用来访问数据库或 API。当你在底部查询管理器中点击 Add选择数据源时会看到Run JavaScript Code这一项它就是 RunJS 查询的入口。从服务端源码可以印证这一点ToolJet 把这类无需外部插件、开箱即用的数据源统一定义为“默认数据源种类”。在 server/src/modules/data-sources/types/index.ts 中可以找到如下类型定义export type DefaultDataSourceKind restapi | runjs | runpy | tooljetdb | workflows;也就是说runjs与restapi、runpyRun Python、tooljetdb等并列属于平台内建的数据源种类在 server/src/modules/data-sources/constants/index.ts 中同样列出了[restapi, runjs, runpy, tooljetdb, workflows]这一组默认种类。因此 RunJS 查询不需要安装任何插件即可使用适合承担以下职责完成纯计算类逻辑数值运算、字符串处理、随机数等对查询结果做二次加工再喂给组件展示组织多个查询的执行顺序实现“查询调用查询”编写带弹窗alert等前端交互效果的小段逻辑。从文档示例大量使用alert这类浏览器 API、且运行结果可直接被{{...}}模板绑定来看RunJS 运行在一个能访问前端上下文的环境执行结果会随查询完成写入对应查询的数据对象中供页面组件即时消费。二、创建第一个 Run JavaScript 查询创建一个 RunJS 查询只需四个步骤对应编辑器底部面板点击编辑器底部查询管理器中的 Add按钮在弹出的数据源列表中选择Run JavaScript Code在代码编辑区中输入你的 JavaScript 代码点击Preview可预览输出点击Run则正式触发该查询。创建完成后查询会出现在左侧查询列表中默认命名类似runjs1这个名称会被注册为全局的queries命名空间下的一个对象例如queries.runjs1供事件处理器与组件属性引用。查询体即一段普通 JavaScript可用return返回结果例如return 40 2;Run 之后你可以到已放置的文本组件属性中输入{{queries.runjs1.data}}页面上就会展示该查询的返回值。查询结果的存储与运行状态由前端的数据查询 Store 统一管理想深入理解其内部结构可阅读 frontend/src/_stores/dataQueriesStore.js。三、参数Parameters机制让同一段代码动态复用参数机制允许你在不修改核心脚本的前提下向 RunJS 代码动态传入不同的输入值让“一段代码、多种输入”成为可能非常适合把通用的处理逻辑抽成可复用的查询。3.1 每个参数由什么构成添加参数时需要为它定义两部分内容字段说明允许取值Name参数名供代码内引用合法标识符字符串Default value参数的默认值常量字符串、数字以及对象3.2 添加参数的步骤在 RunJS 查询编辑器上找到Parameters 按钮并点击创建一个新参数输入参数的Name设置参数的 DefaultValue字符串、数字或对象均可。参数添加成功后即可在代码中通过parameters.参数名语法引用它。3.3 示例一在弹窗中显示参数值假设我们创建一个名为newAlert的参数默认值是一个对象内容为“Displaying the Parameter Value in an Alert Box”然后在代码中调用浏览器的alert方法alert(parameters.newAlert)查询被触发时页面上会弹出提示框并显示该参数的值达到“用参数驱动交互”的效果。3.4 示例二用参数调用另一个查询参数最常见的进阶用法是作为“传参入口”去触发其他查询。文档中给出了一个经典的multiply/callMultiply组合我们按步骤还原第一步创建被调用的multiply查询新建一个 RunJS 查询并命名为multiply为它添加两个参数num1默认值10num2默认值2写入如下代码返回两数乘积return parameters.num1 * parameters.num2;在画布上放置一个文本组件将其内容设为{{queries.multiply.data}}即可实时显示乘法结果。第二步创建调用方callMultiply查询再新建一个名为callMultiply的 RunJS 查询在其中通过queries.multiply.run({...})显式传入自定义参数值来触发multiplyqueries.multiply.run({num1: 20, num2: 7})执行callMultiply时multiply会被以num1 20、num2 7触发执行文本组件上随即展示新结果。这种模式下multiply保留了自己的默认参数可在没有外部调用时独立运行其它查询可通过queries.目标查询名.run({参数名: 值, ...})覆盖默认值、按需调用同一段逻辑被多处复用无需复制粘贴代码方便后续统一维护。这里涉及的关键访问约定总结如下表达式作用parameters.name在查询体内读取调用方传入或默认的参数值queries.name.data读取某查询最近一次运行的数据结果用于模板绑定queries.name.run({ ... })以自定义参数触发某查询执行四、RunJS 实用示例从随机数到唯一 ID文档为不同诉求提供了几段可直接照抄的示例代码下面逐一展开并补充说明适用场景。4.1 生成随机数目标生成并展示19范围内的随机整数并将其绑定到文本组件。const a Math.floor(Math.random() * (10 - 1)) 1; return a;完整搭建流程在画布上一个容器Container内放入一个按钮与一个文本组件点击查询面板的 Add选择Run JavaScript Code新建查询默认名如runjs1写入上述代码并先 Run 一次验证为按钮配置事件处理器事件Event选择On Click动作Action选择Run Query在查询下拉中选择runjs1——此后每次点击按钮都会重新执行这段 JS刷新随机数修改文本组件的属性在其文本字段中输入Random number: {{queries.runjs1.data}}。这样页面上就会显示“Random number: JS 返回的结果”且随按钮点击不断变化。(10 - 1)代表区间上限开区间调整括号内的两个数即可改变随机范围。4.2 生成一个简单唯一 ID下面的代码生成“id”前缀 一串随机十六进制字符的唯一 IDvar id id Math.random().toString(16).slice(2); return id;Math.random().toString(16)将随机小数转换为十六进制字符串.slice(2)去掉开头的0.最终结果形如id2f4a1b。适合用作本地临时键名、行标识等轻量去重场景。4.3 生成基于时间戳的唯一 ID如果希望 ID 同时携带时间维度、并进一步降低碰撞概率可以组合当前时间与随机串return String(Date.now().toString(32) Math.random().toString(16)).replace(/\./g, );Date.now().toString(32)把当前毫秒时间戳转成 base-32 字符串作为 ID 的前段拼接一段随机十六进制值再通过.replace(/\./g, )去除可能出现的点号。由此生成的 ID 形如2g3h1d6a4h3比上一种更长、更不易重复可用于需要跨会话保证一定唯一性的标识生成。4.4 什么时候用哪种只需要“每次变化”的演示值 → 随机数方案需要在页面内快速生成键名 → 简单唯一 ID需要把“生成时间”隐含在 ID 里便于排查或排序 → 基于时间戳的唯一 ID。五、内置库与更多实战路径RunJS 查询体内可以直接使用 ToolJet 内置集成的第三方库无需额外导入。官方文档列出了三个基础库库名定位与典型用途Moment日期时间的解析、格式化与计算如moment().format(...)Lodash数组、对象、集合的工具函数集如_.groupBy、_.cloneDeepAxios基于 Promise 的 HTTP 客户端用于在代码中请求外部接口结合文档给出四条值得深挖的实战路径均可在对应文档中找到完整步骤引入外部 JavaScript 库仅靠内置库不够时可用 RunJS 动态加载第三方库来增强能力参考 导入外部 JavaScript 库主动让查询失败在某些业务分支中需要故意中断并抛出错误用于校验、权限拦截等参考 Intentionally Fail 一个 JS 查询按固定间隔触发查询借助 RunJS 实现“定时轮询/定时刷新”类需求例如周期拉取数据源刷新界面参考 指定时间间隔运行查询结合外部 API 二次加工先通过 API 查询获取原始数据再用 RunJS 对响应做裁剪、聚合与格式化最后交给图表等组件渲染。六、小结与使用建议RunJS 把 JavaScript 的灵活性与低代码的“可绑定、可触发”机制衔接起来。从创建查询、用parameters.name解耦输入、用queries.name.run({...})组织查询编排到通过queries.name.data把结果交给组件一整条链路都不需要写组件源码而是在编辑器中以“配置 少量脚本”完成。服务端将runjs注册为默认数据源种类见 types 定义保证了该能力的开箱即用。实际落地时建议遵循三条原则单一职责把一段可复用的计算抽成带参数的 RunJS 查询而不是在多个查询里复制代码善用参数而非硬编码将变化点数值、对象、边界暴露为参数默认值提升查询的可复用面与组件事件协同把 RunJS 查询挂到按钮 On Click、文本{{queries.xxx.data}}绑定等机制上让数据“跑起来”而不是只停留在查询面板里。【免费下载链接】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），仅供参考