ToolJet Switch Page 动作详解多页面应用中的页面跳转、Query Params 与 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/ToolJetSwitch Page 是 ToolJet 多页面Multipage应用中用于在页面之间进行导航的核心动作Action可挂载在按钮等组件的各类事件处理器上也可通过 RunJS 查询以编程方式触发。本文将以 v3.0.0-LTS 版本文档为主体结合仓库前端源码完整讲解 Switch Page 的配置方式、Query Params查询参数的传递机制、RunJS 调用语法以及底层实现原理帮助你掌握多页面应用中的页面跳转实战方案。Switch Page 动作概览ToolJet 允许在单个应用内创建多个页面使应用更易于导航和更友好参见 Pages 教程。Switch Page 动作的作用就是将用户从当前页面过渡到应用内的另一个页面它可以挂载到各种组件的事件处理器Event Handler上例如按钮的On Click事件。在动作配置面板中可以看到以下关键字段Page Handle目标页面的句柄slug。页面句柄是追加在应用 URL 末尾的路径片段默认是页面名称的小写形式、空格替换为连字符可在页面的 kebab 菜单中通过 Edit 图标修改见 Pages 文档。Debounce防抖默认留空可输入一个数值表示动作执行前等待的毫秒数例如300表示延迟 300ms 后执行。防抖常用于避免用户快速重复点击导致页面频繁切换。Query Params查询参数可附加在切换后页面 URL 上的键值对参数详见下文。提示Pages 面板中每个页面都有独立的暴露变量包括handle、name、id和variables可通过{{page.handle}}、{{page.name}}、{{page.id}}、{{page.variables.pageVariableName}}动态访问见 Pages 文档的 Exposed variables 小节。这些变量可以在设置 Switch Page 动作时作为参考。配置 Query Params查询参数Switch Page 动作支持向目标页面传递查询参数。查询参数会被追加到应用 URL 末尾并以问号?开头。参数格式查询参数由键值对组成key与value之间用等号分隔。点击动作配置面板中的按钮可以添加多组查询参数最终生成的 URL 中多组参数之间以连接。例如配置一组参数后切换页面的 URL 会形如https://your-domain/applications/app-slug/page-handle?usernameuserexample.com使用动态值查询参数的值支持 ToolJet 的表达式语法双花括号{{ }}可以引用组件状态、全局变量等。官方示例中以username作为 keyvalue 设置为{{globals.currentUser.email}}即可动态获取当前登录用户的邮箱key: username value: {{globals.currentUser.email}}当点击按钮触发挂载在它上面的 Switch Page 事件处理器后切换到的页面 URL 就会携带username当前用户邮箱这样的参数。这种方式常用于向服务端传递附加信息修改目标页面的行为例如预填充筛选条件过滤搜索结果、分页、排序等场景。通过 RunJS 查询切换页面除了在事件处理器中可视化配置Switch Page 动作还可以通过 RunJS 查询以代码方式触发。关于如何在 RunJS 查询中运行各种动作的完整指南可参考 Run Actions from RunJS Query。基本语法在 RunJS 查询中使用actions.switchPage函数传入目标页面的句柄page handleawait actions.switchPage(page-handle)注意这里使用的是页面句柄slug而非页面名称。例如页面名为 Dashboard、句柄为dashboard则调用await actions.switchPage(dashboard)。携带查询参数切换Switch Page 动作也可以在切换的同时携带查询参数语法为传入一个由键值对数组构成的二维数组actions.switchPage(pageHandle, [[param1, value1], [param2, value2]])其中param1、param2是查询参数名value1、value2是对应的值可以替换为任意合法的参数名和值同样支持表达式求值。生成的 URL 中会以?param1value1param2value2的形式附加。从仓库前端源码的代码提示常量表可以看到switchPage是应用构建器中可供 RunJS 使用的内置动作之一见 actions.js该文件是代码提示code hints中可用动作的单一事实来源single source of truth。源码视角Switch Page 的底层实现要深入理解 Switch Page 动作的行为可以查看其核心实现。前端状态管理中switchPage的实现在 appSlice.js其函数签名如下switchPage: (pageId, handle, queryParams [], moduleId canvas, isBackOrForward false) { ... }从源码结构看一次页面切换主要经历以下过程防重复切换守卫通过pageSwitchInProgress标志位防止快速连续触发。若切换正在进行会弹出提示 Please wait, page switch in progress 并直接返回该标志会在切换前同步置位避免并发调用绕过守卫。加载态展示设置页面加载器setPageLoader(true)并通过yieldToMain()让出主线程确保加载器先绘制出来再执行后续重活。状态清理与切换清理旧页面存储cleanUpStore、清理临时布局clearTemporaryLayouts、更新当前页面 ID、组件名映射和查询映射setCurrentPageId、setComponentNameIdMapping、setQueryMapping并重新初始化依赖图initDependencyGraph。查询参数过滤对传入的查询参数进行过滤——值为空的参数会被剔除env参数仅在 License 有效时保留frontend/src/AppBuilder/_stores/slices/appSlice.js#L331-L335。URL 构造与导航将查询参数拼接为keyvalue...形式的字符串结合应用 slug、subpath、workspace 等信息构造目标 URL 并执行navigate预览模式走/applications/slug/handle编辑模式走/workspaceId/apps/slug/handle同时通过state传递页面切换信息。全局状态更新更新页面对应的已解析常量setResolvedPageConstants包含id、handle、name并将解析后的查询参数写入全局urlparamssetResolvedGlobals(urlparams, ...)供目标页面通过{{globals.urlparams}}读取。若切换的是同一页面isSamePage为 true还会生成新的pageKeyUUID以强制触发页面级刷新逻辑appSlice.js。事件处理器中的解析与拦截当通过事件处理器触发 Switch Page 时实际执行路径在 eventsSlice.js。该实现中值得注意的细节参数解析queryParams中的每个键值对都会通过getResolvedValue先解析支持表达式再传给switchPage。保留 version 与 env如果当前 URL 中带有version或env查询参数而目标参数中没有则会将它们自动补充到解析后的参数列表首位确保切换页面时版本/环境信息不丢失。受限页面拦截如果目标页面设置了访问受限page.restricted且当前不是编辑模式会提示 Access to this page is restricted. Contact admin to know more. 并中止切换。禁用页面拦截如果目标页面被禁用page.disabled会提示 Page is disabled同时在调试器中记录一条错误日志navToDisablePage。这与 Pages 文档 中的说明一致被隐藏Hide Page的页面虽然不出现在导航侧边栏但仍可通过 Switch Page 动作或页面 URL 直接访问而被禁用Disable Page的页面在 viewer 模式下不可访问。典型使用场景结合文档与源码Switch Page 动作的典型场景包括场景实现方式按钮点击跳转到另一页在按钮On Click事件处理器中添加 Switch Page 动作选择目标页面句柄跳转并携带筛选条件在 Query Params 中配置如statusactive或 value 使用{{components.table1.selectedRow.status}}等动态表达式登录后携带用户信息跳转value 使用{{globals.currentUser.email}}动态获取当前用户邮箱逻辑判断后编程跳转在 RunJS 查询中调用await actions.switchPage(orders, [[status, pending]])页面加载事件跳转在页面的On page load事件处理器中使用 Switch Page页面也可挂载事件处理器见 Pages 文档的 Event Handlers 小节注意事项与最佳实践句柄而非名称RunJS 调用时第一个参数必须是目标页面的句柄可在页面 kebab 菜单中查看/修改不是页面显示名称。防抖字段若需防止快速重复切换可在动作配置中为 Debounce 字段设置毫秒值如300源码层面也有pageSwitchInProgress防并发保护。动态值求值Query Params 的 key 和 value 均支持{{ }}表达式事件处理器触发时会先通过getResolvedValue解析再拼入 URL。版本与环境参数自动保留从源码实现看切换页面时当前 URL 中的version、env参数会被自动带到目标页无需手动重复配置。受限/禁用页面不可切换受限页面在非编辑模式会拦截跳转禁用页面在 viewer 模式不可访问主页Home不能被隐藏或禁用但可以被 Switch Page 跳转。通过 URL 直接访问切换后的页面 URL 形如.../app-slug/page-handle?keyvalue该 URL 本身也可用于直接访问或分享特定页面。延伸阅读Pages 教程多页面应用与页面句柄Run Actions from RunJS Query在 RunJS 中调用各类动作动作底层实现appSlice.js 中的 switchPage、eventsSlice.js 中的事件触发逻辑动作列表单一事实来源frontend/src/AppBuilder/_stores/constants/actions.js相关页面动作文档Set Page Variable、Unset Page Variable、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考