ToolJet 导入外部 JavaScript 库基于 RunJS 查询加载 CDN 库的完整指南【免费下载链接】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 库如 MathJS、FlattenJS从创建应用、选择 CDN 链接到编写加载代码、在查询面板中运行验证的完整流程。读完本文你将掌握addScript动态加载模式、在 RunJS 查询中调用第三方库函数的方法以及让库在整个应用生命周期内全局可用的配置技巧并能结合源码理解 RunJS 查询在 ToolJet 前端与后端的执行机制。RunJS 查询是什么先理解执行环境在动手之前有必要先明确 RunJS 查询的本质。从仓库源码看RunJS即 Run JavaScript是 ToolJet 的一类特殊查询类型与 Run Pythonrunpy、REST APIrestapi、ToolJet Databasetooljetdb、Workflowsworkflows并列属于平台内置的静态数据源// server/src/modules/data-sources/constants/index.ts export const DefaultDataSourceKinds: DefaultDataSourceKind[] [restapi, runjs, runpy, tooljetdb, workflows];按照 server/src/modules/data-sources/AGENTS.md 的说明这类静态数据源的type static每个工作区会自动生成一行${kind}default记录即 runjsdefault且不提供用户可编辑的连接选项——你无需配置任何服务器、密钥或连接字符串。关键差异在于执行位置普通数据源查询如 Postgres、REST API由 ToolJet 服务端执行而RunJS 查询针对普通应用是在浏览器中执行的server/src/modules/data-queries/AGENTS.md 明确说明 Executed in the browser for apps。这一点决定了你可以在 RunJS 代码中访问document、window等浏览器 API你可以动态创建script标签并挂载到 DOM 上来加载外部 CDN 库加载的库会注册为全局变量如math、flatten在同一浏览器会话中后续查询可直接使用。补充说明RunJS 仅在**工作流Workflow**场景下才由服务端执行通过isolated-vm沙箱见 server/src/modules/data-queries/interfaces/IUtilService.ts。本指南聚焦普通应用的浏览器端用法。选择合适的 JavaScript 库CDN导入外部库的前提是拿到该库的 Content Delivery NetworkCDN链接。ToolJet 官方推荐的来源是 jsDelivr——一个开源项目的公共 CDN 服务你可以在其中搜索任意开源 JavaScript 库并获取其 CDN 地址。选择库时的建议优先选择提供 UMD / 浏览器全局构建的库这类库加载后会在window上暴露全局变量如 MathJS 暴露math便于在后续 RunJS 查询中直接调用留意 CDN 链接指向的入口文件有些库的根路径直接就是可用的浏览器构建如mathjs有些则需要指定dist下的具体文件如 FlattenJS 需要lib/flatten.min.js建议锁定版本号使用带版本号的 CDN 链接如mathjs11.7.0可以保证行为可复现避免上游更新引入不兼容变更。创建应用与新建 RunJS 查询从 ToolJet Dashboard仪表盘创建一个新应用应用打开后在查询面板中选择 ToolJet 默认自带的JavaScript数据源即runjs静态数据源新建查询。新建的 RunJS 查询会提供一个多行 JavaScript 代码编辑器。从前端源码看该编辑器由 frontend/src/AppBuilder/QueryManager/QueryEditors/Runjs/Runjs.jsx 实现它复用了 AppBuilder 的CodeHinter组件langjavascript多行模式高度 400px默认占位代码为//Type your JavaScript code here代码变更会实时同步到查询的options.code中。导入外部库动态加载脚本RunJS 查询在浏览器中运行因此最简单可靠的导入方式是通过document.createElement(script)动态注入script标签。在新建查询的代码区粘贴以下代码// Function to add script dynamically function addScript(src) { return new Promise((resolve, reject) { const scriptTag document.createElement(script); scriptTag.setAttribute(src, src); scriptTag.addEventListener(load, resolve); scriptTag.addEventListener(error, reject); document.body.appendChild(scriptTag); }); } try { // Importing MathJS await addScript(https://cdn.jsdelivr.net/npm/mathjs11.7.0); // Importing FlattenJS await addScript(https://cdn.jsdelivr.net/npm/flattenjs2.1.3/lib/flatten.min.js); // Showing a success alert await actions.showAlert(success, Mathjs and Flatten imported); } catch (error) { console.error(error); }这段代码的关键设计addScript(src)返回一个Promise通过监听script标签的load与error事件把「脚本加载完成」这一异步过程转换为可await的流程——只有当前库加载成功后才继续加载下一个避免库之间存在依赖时竞态出错使用try...catch包裹加载过程任一脚本加载失败都会进入catch分支并将错误输出到控制台便于排查 CDN 链接有效性等问题actions.showAlert(success, ...)是 ToolJet 内置的前端动作 API用于在页面弹出提示框这里作为导入成功的可视化反馈。粘贴代码后点击查询面板中的Run按钮运行。如果一切正常页面会弹出提示框显示 Mathjs and Flatten imported。让库在整个应用中全局可用:::tip 勾选查询面板中的Run this query on application load?应用加载时运行此查询选项即可在应用加载完成后立即执行该导入查询使这些库在整个应用运行期间始终可用而无需手动触发。 :::这是把「库加载」与「库使用」解耦的关键一步导入查询只负责一次性注入脚本其余所有 RunJS 查询在应用生命周期内都可以直接引用math、flatten等全局变量。实战示例一使用 FlattenJS 扁平化 JSON 对象导入完成后新建另一个 RunJS 查询来验证 FlattenJS 的实际能力。FlattenJS 用于将嵌套的 JSON 对象展开为单层键值结构。在代码区输入return flatten({ key1: { keyA: valueI }, key2: { keyB: valueII }, key3: { a: { b: { c: 2 } } } });运行后或在查询管理器中预览输出你会得到如下扁平化结果{ key1.keyA: valueI, key2.keyB: valueII, key3.a.b.c: 2 }嵌套的key3: { a: { b: { c: 2 } } }被展开为以点号分隔的路径键key3.a.b.c这种结构非常适合在表格组件中直接展示、写入关系型数据库或与其他系统做数据交换。实战示例二使用 MathJS 进行数学计算再新建一个 RunJS 查询利用 MathJS 强大的数学函数库做计算。MathJS 支持复数、矩阵、单位换算、数值积分等高级数学能力。输入以下代码return math.atan2(3, -3) / math.pi;math.atan2(y, x)计算从 x 轴正方向到点 (x, y) 的夹角弧度结果除以math.pi归一化。运行后输出为0.75即 3π/4 与 π 的比值。你可以在此基础上继续组合 MathJS 的其他 API例如math.sqrt、math.evaluate、math.matrix等实现报表中的统计计算、科学计算甚至矩阵运算。进阶理解 RunJS 查询的底层执行链路了解源码层的执行机制有助于你更好地使用这一能力查询编辑器前端通过CodeHinter渲染多行 JavaScript 编辑器Runjs.jsx输入的代码作为查询的options.code存储数据源归属查询归属于工作区的静态数据源runjsdefault类型static无用户可编辑选项这意味着你无需任何连接配置即可开箱即用执行方式普通应用中代码在浏览器端执行因此可以操作 DOM、动态加载脚本、调用actions系列 API而在 Workflow 场景中同一类代码由服务端通过isolated-vm沙箱执行见 IUtilService.ts两者能力边界不同——浏览器端代码可依赖document/window服务端则不能。最佳实践与注意事项库的加载幂等性如果应用加载查询被多次触发如页面刷新script标签可能被重复注入。可先判断全局变量是否已存在如if (window.math) return;再执行加载避免重复下载版本锁定CDN 链接务必携带精确版本号防止库升级导致全局 API 变化加载失败排查确认 CDN 链接在浏览器中可直接访问利用catch分支中的console.error查看错误详情按需导入只在确实需要时才加载外部库避免一次性注入过多脚本拖慢应用首屏加载将「库加载」查询与「业务计算」查询分离保持查询职责单一敏感逻辑保护RunJS 代码在浏览器端执行所有逻辑对最终用户可见不要在 RunJS 查询中放置密钥、密码等敏感信息——这类信息应放入工作区常量{{secrets.*}}或由服务端数据源处理。通过 RunJS 查询 CDN 动态加载的组合你可以在不修改 ToolJet 核心代码的前提下为应用引入任意开源 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考