ToolJet「Go to app」动作完全指南事件驱动跨应用跳转与查询参数传递【免费下载链接】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导读「Go to app」是 ToolJet 提供的一个导航类动作Action用于在某个事件发生时将用户跳转到任意一个**已发布released**的 ToolJet 应用。本文基于 ToolJet 2.50.0-LTS 版本文档与源码完整讲解该动作的配置方式目标应用选择、查询参数、Debounce 防抖、底层执行原理事件分发、目标解析、URL 拼接、在编辑器与运行器中的差异行为以及如何在 JavaScript 代码RunJS中调用等价能力帮助你搭建应用之间的无缝导航链路。动作概览从一个应用跳到另一个应用「Go to app」的核心定位是应用级导航与「Switch page」在同一应用内切换页面不同它会将用户带到另一个 ToolJet 应用。官方文档明确了使用前提——只有已发布released的应用才能通过该动作打开This action allows you to open any released ToolJet application when an event occurs. Only the apps that are released can be opened using this action.这意味着目标应用必须先经历「发布/Release」流程否则跳转目标无法被解析。这一点与源码中的校验逻辑完全一致详见后文「目标应用有效性校验」一节。在 ToolJet 前端源码中该动作被登记为导航组navigation group的一员。见 ActionTypes.js{ name: Go to app, id: go-to-app, options: [ { name: app, type: text, default: }, { name: queryParams, type: code, default: [] }, ], group: navigation, },从定义可以看出该动作只有两个核心配置项目标应用app与查询参数queryParams默认空数组所属分组为导航类动作。同时在 actions.js 中goToApp被列入应用构建器可用的代码提示code hints动作列表说明它既可以通过可视化事件配置器使用也可以在 RunJS 中以编程方式调用。配置步骤在事件处理器中绑定「Go to app」1. 选择触发事件在右侧检查器Inspector面板中为组件如按钮 Button添加一个事件处理器例如「On click」随后在动作Action下拉框中选择Go to app。这是最典型的用法用户点击按钮后跳转到另一个应用。2. 选择目标应用在动作选项Action Options区域通过App下拉选择框从当前工作区的应用列表中选择目标应用。源码中该下拉框通过getAllApps()动态加载应用列表见 GotoApp.jsxuseEffect(() { getAllApps() .then(setAppOptions) .finally(() setIsLoading(false)); }, []);选中应用后配置面板持久化的是应用的稳定标识correlationId而不再使用传统的slug见 GotoApp.jsx// Persist only the stable id; drop the legacy slug key. handlerChanged(eventIndex, { correlationId: value, slug: undefined }); // Mirror both slug and currentVersionId into the store so click-time URL // building works without a reload AND the validator can distinguish missing target from no released version. upsertLinkedApp( value, { slug: selected?.slug ?? null, currentVersionId: selected?.currentVersionId ?? null }, moduleId );选择应用的同时配置面板会把目标应用的slug与currentVersionId镜像写入 store 的linkedApps映射中appSlice.js以便在运行时无需重新加载即可拼接跳转 URL同时为后面的有效性校验提供依据。3. 添加查询参数Query params「Go to app」支持在跳转 URL 上携带查询参数用于向目标应用传递数据。配置面板默认展示空的参数列表你可以通过Add param按钮添加键值对见 GotoApp.jsxButton onClick{addQueryParam} Add param /Button每个参数由「键」和「值」两个输入框组成且两个输入框都支持 ToolJet 表达式通过 CodeHinter 编辑器这意味着你可以写入类似{{globals.currentUser.email}}或{{components.table1.selectedRow.id}}这样的动态引用见 GotoApp.jsx。参数值会在动作执行时被解析为实际值再拼接到目标 URL 上。4. 设置 Debounce 防抖可选Debounce 字段默认为空。你可以输入一个毫秒数值例如300指定事件触发后延迟多久才执行该动作。这在防止高频事件如快速连点按钮造成重复跳转时非常实用。Debounce 的实现位于事件分发层的executeAction上源码中使用debounce包裹了动作执行函数见 eventsSlice.jsexecuteAction: debounce((eventObj, mode, customVariables {}, moduleId canvas) { ... }),因此只要在事件配置中填写了 Debounce 毫秒值对应动作的执行就会按该延迟节流。提示Debounce 字段留空表示不防抖事件触发后立即执行动作。5. 条件执行Run Only If与 ToolJet 其他动作一致「Go to app」也支持Run Only If条件表达式。只有当该表达式求值为真时动作才会真正执行适合做权限控制或前置条件判断例如仅在选中了某行数据时才允许跳转。运行原理事件是如何被分发并执行跳转的「Go to app」的执行入口是事件分发器executeAction它根据actionId匹配到go-to-app分支。核心执行逻辑位于 eventsSlice.js可拆解为以下几步第一步解析目标应用的 slug执行逻辑区分两种来源见 eventsSlice.jsif (event.source app-action) { // RunJS app action go-to-app still send a slug directly for backward compatibility. if (!event.slug) { throw new Error(No application slug provided); } slug getResolvedValue(event.slug, customVariables, moduleId); } else { // Builder-configured go-to-app events resolve the target via correlationId. if (!event.correlationId) { throw new Error(No application selected); } const linkedApps get().appStore.modules[moduleId]?.linkedApps; const appSlug linkedApps?.[event.correlationId]?.slug; ... slug getResolvedValue(appSlug, customVariables, moduleId); }通过可视化事件配置器创建的动作source非app-action会基于持久化的correlationId到linkedApps映射中反查slug通过 RunJS 调用的动作source app-action为了向后兼容仍然直接传递slug。第二步解析查询参数查询参数以键值对数组形式存储执行时逐个把键和值通过getResolvedValue解析为真实值再合并为对象见 eventsSlice.jsconst queryParams event.queryParams?.reduce( (result, queryParam) ({ ...result, ...{ [getResolvedValue(queryParam[0], customVariables, moduleId)]: getResolvedValue( queryParam[1], customVariables, moduleId ), }, }), {} );第三步拼接 URL 并执行跳转目标 URL 格式为/applications/${slug}若存在查询参数则通过serializeNestedObjectToQueryParams序列化后以?拼接见 eventsSlice.jslet url /applications/${slug}; if (queryParams) { const queryPart serializeNestedObjectToQueryParams(queryParams); if (queryPart.length 0) url url ?${queryPart}; } const path getSubpath(); if (path) url path url; if (mode view) { window.open(url, _self); } else { if (confirm(The app will be opened in a new tab as the action is triggered from the editor.)) { window.open(urlJoin(getHostURL(), url)); } }最终生成的 URL 形如/applications/slug?key1value1key2value2其中查询参数键值可以是嵌套结构会被序列化为 URL 查询字符串。编辑器与运行器中的行为差异「Go to app」在编辑器editor与运行器viewer/已发布应用中的跳转方式不同这是使用时需要注意的关键差异运行模式跳转行为运行器view 模式使用window.open(url, _self)在当前标签页打开目标应用编辑器编辑模式弹出确认框「The app will be opened in a new tab as the action is triggered from the editor.」确认后在新标签页打开此外在编辑模式下如果目标应用缺失或未发布会抛错并通过logError(go_to_app, ...)记录到调试器debugger方便开发者定位问题见 eventsSlice.js而在运行器模式下则会跳过校验、直接尝试重定向交给既有的 404 / 「not found」处理逻辑兜底见 eventsSlice.js 中的注释说明。目标应用有效性校验未发布应用无法跳转前文提到「只有已发布的应用才能打开」这一约束在源码中有明确的校验实现。校验函数isLinkedAppValid定义在 utils.jsexport function isLinkedAppValid(correlationId, linkedAppsMap) { if (!correlationId) return { isValid: true, errorMessage: null }; const entry linkedAppsMap?.[correlationId]; if (!entry || !entry.slug) { return { isValid: false, errorMessage: App ${correlationId} undefined. Check if the linked app exists and has a released version., }; } if (!entry.currentVersionId) { return { isValid: false, errorMessage: Check if the linked app has a released version., }; } return { isValid: true, errorMessage: null }; }校验逻辑分两层目标应用是否存在若linkedApps映射中找不到对应的correlationId或没有slug则判定无效错误信息提示「检查目标应用是否存在且有已发布版本」目标应用是否已发布若映射中存在应用但缺少currentVersionId即没有已发布的版本则判定无效错误信息提示「检查目标应用是否有已发布版本」。该校验在事件配置阶段EventManager.jsx和编辑模式执行阶段eventsSlice.js都会被调用。在事件管理器中校验失败时会在事件行内展示内联错误提示如「Undefined app」及具体错误信息帮助你在保存前就发现配置问题。在 JavaScript 代码RunJS中调用除了通过可视化事件配置器你也可以在RunJS代码中触发「Go to app」动作。ToolJet 的 RunJS 中暴露了actions.goToApp()方法其签名与实现位于 eventsSlice.jsconst goToApp (slug , queryParams []) { const event { actionId: go-to-app, source: app-action, slug, queryParams, }; return executeAction(event, mode, {}, moduleId); };对应的方法定义如下goToApp(slug, queryParams)slug字符串目标应用的 slug应用唯一标识。queryParams数组查询参数列表元素为[key, value]形式的二元数组。示例在 RunJS 中跳转到 slug 为analytics-dashboard的应用并携带userId与source两个查询参数await actions.goToApp(analytics-dashboard, [ [userId, {{globals.currentUser.id}}], [source, homepage], ]);执行时该方法构造actionId: go-to-app、source: app-action的事件对象并走同一个executeAction分发管道。由于source为app-action运行时直接使用传入的slug而不依赖linkedApps映射见 eventsSlice.js因此通过 RunJS 调用时只需保证 slug 正确即可。其他交互方式如 RunJS 代码中触发任意事件动作的通用写法可参考 run-actions-from-runjs 文档。常见使用场景与注意事项典型场景工作台/门户导航主应用作为工作台点击某个业务入口按钮跳转到对应的已发布子应用上下文传递跳转时通过查询参数把当前选中记录的主键、用户信息等传给目标应用让目标应用直接进入对应详情页或过滤后的列表流程串联一个应用中完成某步操作后如表单提交成功事件自动跳转到下一个处理环节的应用。注意事项目标应用必须先发布未发布的应用无法作为跳转目标配置阶段与执行阶段都会给出校验错误提示查询参数键值支持表达式键和值都可以写 ToolJet 表达式会在执行时动态解析适合传递运行时数据Debounce 默认关闭需要防抖时自行填写毫秒值编辑器与运行器跳转方式不同编辑器内跳转会弹出确认框并在新标签页打开运行器中则直接在当前标签页跳转通过 RunJS 调用时直接传 slugactions.goToApp(slug, queryParams)中slug为目标应用的 slugqueryParams为[key, value]二元数组列表。配置界面一览下图展示了 ToolJet 中「Go to app」动作的完整配置界面图片来源于本仓库文档 gotoapp3.png界面左侧为动作配置区顶部依次是事件Event如 On click、动作Action已选择 Go to app与 Run Only If 条件输入框下方的 Action Options 包含目标应用下拉选择框App、可增删的查询参数键值对Query params以及 Debounce 防抖输入框。右侧为组件属性区如按钮文本、加载状态、事件绑定列表等两者联动即可完成「点击按钮 → 跳转到已发布应用并携带参数」的完整配置。【免费下载链接】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），仅供参考