企业官网建设流程全解析

ToolJet 定时刷新指南：使用 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

本指南讲解如何在 ToolJet 中构建一个按指定时间间隔自动获取数据的应用：通过 REST API 查询拉取数据、用表格组件展示，并借助RunJS（Run JavaScript code）查询配合浏览器setInterval定时器实现周期性触发。读完本文，你将掌握 RunJS 查询的完整用法、actions与variables的配合方式，以及如何用clearInterval为自动化任务增加可控的停止机制，从而应用到轮询接口、实时监控大屏等真实场景。

方案概览：为什么用 RunJS + setInterval 实现定时查询

ToolJet 查询面板本身不提供原生的"定时执行"开关，但 RunJS 查询赋予了在浏览器端执行任意 JavaScript 的能力，因此可以借助 Web 平台的标准定时器 APIsetInterval来周期性调用其他查询（如 REST API 查询），实现动态、高效的数据抓取。

从源码看，RunJS 是 ToolJet 内置的**静态数据源（default data source）**之一。服务端在 server/src/modules/data-sources/constants/index.ts 中定义了DefaultDataSourceKinds = ['restapi', 'runjs', 'runpy', 'tooljetdb', 'workflows']；前端查询面板中对应runjs这一查询类型，显示名称为 "Run JavaScript code"，见 frontend/src/AppBuilder/QueryManager/constants.js。在 queryPanelSlice.js 中，RunJS 代码通过new AsyncFunction(...)在浏览器沙箱内执行，因此setInterval、clearInterval等浏览器 API 可以正常使用，这也是本方案可行的底层基础。

Step 1: 创建新应用并添加表格组件

在 ToolJet 仪表盘中新建一个应用，进入应用编辑器（App Builder）后，从组件库拖入一个表格（Table）组件到画布上。该表格将用于展示 REST API 查询返回的数据。

Step 2: 创建并测试 REST API 查询

1. 在查询面板（Query Panel）中新建一个REST API查询；
2. 请求方法选择GET；
3. 在 URL 中填入 mock 接口地址，例如https://jsonplaceholder.typicode.com/posts；
4. 将查询命名为post；
5. 点击Run运行查询，确认能成功获取到数据（可在查询结果预览中检查返回的 JSON 数组）。

Step 3: 将查询数据绑定到表格

选中画布上的表格组件，在右侧属性面板中找到Table Data（表格数据）属性，将其设置为：

{{queries.post.data}}

这里的{{ }}是 ToolJet 的模板语法，queries.post.data引用名为post的查询的返回结果。设置后，REST API 查询与表格组件之间就建立了数据连接，后续任何一次queries.post.run()调用产生的数据变化都会自动反映到表格中。

Step 4: 用 RunJS 查询实现定时触发

新建一个RunJS查询，写入以下脚本，通过setInterval每 5 秒触发一次post查询：

actions.setVariable('interval', setInterval(countdown, 5000)); // 5000ms = 5 seconds function countdown(){ // Function to trigger the REST API query queries.post.run(); // action to run the REST API query }

要点说明：

• actions.setVariable('interval', ...)将定时器的 ID 保存到应用级变量interval中，供后续停止定时器时使用；
• setInterval(countdown, 5000)表示每 5000 毫秒（5 秒）调用一次countdown函数；
• queries.post.run()是 RunJS 环境中运行指定查询的标准动作，等价于在查询面板中点击 Run。

间隔时长可根据业务需求调整。如果要在一次周期内串联执行多个动作，可以在countdown函数中使用async/await，例如先运行两个 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 执行环境中可用的能力

为什么这段脚本里能直接用actions、queries、setInterval？因为在 queryPanelSlice.js 中，RunJS 代码通过new AsyncFunction(...)动态构造执行函数，并向其中注入了以下参数（即 RunJS 运行环境的内置能力）：

• 工具库：moment、_（lodash）、axios；
• 应用状态：components（组件）、queries（查询）、globals、page（页面对象）、variables（应用变量）、constants；
• 动作对象：actions（如setVariable、showAlert、runQuery等）；
• 定时器 API：setTimeout、setInterval、clearTimeout、clearInterval、requestAnimationFrame、cancelAnimationFrame；
• 条件注入：当查询定义了参数时注入parameters；应用类型为模块（Module）时注入input；以及通过 JS 库管理器加载的第三方库（见 frontend/src/AppBuilder/_helpers/libraryLoader.js）。

可用动作的完整清单定义在 frontend/src/AppBuilder/_stores/constants/actions.js，包括runQuery、setVariable、unSetVariable、showAlert、showModal、setLocalStorage、copyToClipboard、goToApp、switchPage、logInfo等。

另一个值得注意的实现细节：RunJS 环境中的定时器并非直接调用window.setInterval，而是经由 frontend/src/AppBuilder/_helpers/timerRegistry.js 的trackedSetInterval包装——它会记录所有存活定时器 ID，并在应用切换或页面卸载时通过clearAll()统一清理，避免 RunJS 遗留定时器导致的内存泄漏。这意味着只要通过actions.setVariable保存定时器 ID，就能用同样的clearInterval语义将其清除。

Step 5: 高级配置：页面加载时自动启动

在 RunJS 查询的Settings（设置）面板中，启用Run query on page load（页面加载时运行查询）。这样应用一打开，RunJS 查询就会自动执行，setInterval随即启动，无需手动点击运行。

建议将查询重命名为setInterval，便于识别与后续引用。

Step 6: 防止无限触发：用 clearInterval 停止定时器

setInterval会无限期执行，必须提供停止机制。新建另一个 RunJS 查询，命名为clearInterval（文档原例拼写为clearInrternal，可按你的命名习惯调整），脚本如下：

clearInterval(variables.interval);

variables.interval读取 Step 4 中通过actions.setVariable('interval', ...)保存的定时器 ID，clearInterval将其清除后，定时触发随即终止。两步配合即为完整的"启动—停止"闭环。

Step 7: 添加按钮作为用户触发的停止机制

为了让使用者能直观地停止定时刷新，拖入一个**按钮（Button）**组件到画布上，并为其配置事件处理器（Event Handler）：

• 事件选择On click（点击时）；
• 动作选择Run Query；
• 查询选择上一步创建的clearInterval。

这样，用户点击按钮即可随时停止自动刷新，应用从"无限轮询"变为"可人工干预"的受控状态。

扩展建议与注意事项

• 避免重复启动定时器：如果 RunJS 查询可能被执行多次（例如手动点击了运行），会在actions.setVariable覆盖 ID 的同时遗留旧定时器。稳妥做法是先clearInterval(variables.interval)再重新setInterval，或参考 timerRegistry 的clearAll()思路统一管理。
• 合理选择间隔时长：间隔过短会给后端接口造成不必要的压力，还可能触发限流。轮询类场景建议结合业务数据时效性设置 5 秒以上的间隔，并在查询失败时通过actions.showAlert或actions.logError输出诊断信息。
• RunJS 查询无法被中止：在 frontend/src/AppBuilder/QueryManager/constants.js 中，runjs被列入ABORT_UNSUPPORTED_KINDS——它运行在浏览器内，无法像 fetch 类查询那样通过 AbortController 取消，因此"停止"必须依赖代码层面的clearInterval而非 UI 的取消按钮。
• 错误定位提示：RunJS 执行出错时，查询面板会返回{ status: 'failed', data: { message, description, lineNumber } }，其中lineNumber由执行堆栈解析而来（见 queryPanelSlice.js），可据此快速定位脚本中的语法或逻辑错误。

按照以上 7 个步骤，你的 ToolJet 应用即可按指定时间间隔动态获取数据，实现自动化、高效的定时刷新体验——该方法适用于数据大屏、实时看板、接口轮询等需要周期性更新数据的应用场景。

【免费下载链接】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