ctx.router 编程式导航完全指南：在 NocoBase RunJS 中实现页面跳转、历史控制与数据传递-平芜编程栈

ctx.router 编程式导航完全指南：在 NocoBase RunJS 中实现页面跳转、历史控制与数据传递

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

ctx.router 是 NocoBase RunJS 运行环境中基于 React Router 封装的路由实例，用于在 JS 区块（JSBlock）、JS 字段（JSField）、JS 操作（JSAction）、联动规则与事件流等场景中通过代码完成页面跳转、后退、刷新与历史记录控制。本文完整讲解ctx.router.navigate()的签名、参数与典型用法，并结合ctx.route、ctx.location、ctx.urlSearchParams梳理「导航动作」与「路由状态」的分工，最后给出源码层面的实现依据，帮助你写出可复制、可维护的编程式导航代码。

适用场景

ctx.router解决的是「用代码而不是点击链接来改变页面」的问题，在 NocoBase 的低代码页面里非常常见：

场景	说明
JSBlock / JSField	按钮点击后跳转到详情页、列表页或外部链接
联动规则 / 事件流	提交成功后`navigate`到列表或详情，或传递 state 到目标页
JSAction / 事件处理	在表单提交、链接点击等逻辑中执行路由跳转
视图导航	内部视图栈切换时通过`navigate`更新 URL

注意：ctx.router仅在存在路由上下文的 RunJS 环境中可用（如页面内的 JSBlock、Flow 页面、事件流等）；在纯后端或无路由的上下文（如工作流）中可能为空。

类型定义

router: Router

Router来自@remix-run/router，在 RunJS 中通过ctx.router.navigate()实现跳转、后退、刷新等导航操作。

从源码结构看，客户端路由由 RouterManager 负责创建：它支持hash、browser、memory三种路由类型（对应createHashRouter、createBrowserRouter、createMemoryRouter），并把RouterBridge、CustomRouterContextProvider、VariablesProvider等能力挂载到路由树外层。这意味着ctx.router与ctx.route、ctx.location共享同一个路由实例，navigate()之后这些状态会自动同步更新。

方法

ctx.router.navigate()

跳转到目标路径，或执行后退/刷新。

签名：

navigate(to: string | number | null, options?: RouterNavigateOptions): Promise<void>

参数：

to：目标路径（string）、相对历史位置（number，如-1表示后退）或null（刷新当前页）
options：可选配置
- replace?: boolean：是否替换当前历史记录（默认false，即 push 新记录）
- state?: any：传递给目标路由的 state。该数据不会出现在 URL 中，可在目标页通过ctx.location.state访问，适用于敏感信息、临时数据或不宜放在 URL 中的信息

示例

基础跳转

// 跳转到用户列表（push 新历史，可后退） ctx.router.navigate('/admin/users'); // 跳转到详情页 ctx.router.navigate(`/admin/users/${recordId}`);

字符串形式的to可以直接拼接动态参数。NocoBase 管理后台的页面路径一般以/admin为前缀，recordId可来自ctx.route.params、ctx.location.search或表单当前记录。

替换历史（无新增记录）

// 登录后重定向到首页，用户后退不会回到登录页 ctx.router.navigate('/admin', { replace: true }); // 表单提交成功后替换当前页为详情页 ctx.router.navigate(`/admin/users/${newId}`, { replace: true });

replace: true会替换当前历史记录而不新增，适合「不允许用户后退回到上一页」的流程，例如登录重定向、表单提交成功跳转等。

传递 state

// 跳转时携带数据，目标页通过 ctx.location.state 获取 ctx.router.navigate('/admin/users/123', { state: { from: 'dashboard', tab: 'profile' } });

state适合传递敏感信息或临时数据，因为它不会出现在 URL 中。需要注意的是，state会保存在浏览器历史中，前进/后退时仍可访问，但刷新页面后会丢失。

后退与刷新

// 后退一页 ctx.router.navigate(-1); // 后退两页 ctx.router.navigate(-2); // 刷新当前页 ctx.router.navigate(null);

数字形式的to表示相对历史位置，负数即后退；null表示重新加载当前路由（等价于刷新）。

与 ctx.route、ctx.location 的关系

在 NocoBase RunJS 中，路由上下文由三个对象配合使用：

用途	推荐用法
导航跳转	`ctx.router.navigate(path)`
读取当前路径	`ctx.route.pathname`或`ctx.location.pathname`
读取跳转时传递的 state	`ctx.location.state`
读取路由参数	`ctx.route.params`

ctx.router负责「导航动作」，ctx.route和ctx.location负责「当前路由状态」。

三者对应的文档为：

ctx.route：当前路由匹配信息（pathname、params 等）。其params从路由模板（如/admin/:name）中解析动态参数，pathname与ctx.location.pathname一致；
ctx.location：当前 URL 位置（pathname、search、hash、state），跳转后state在此读取。Location来自react-router-dom，与 React Router 的useLocation()返回值一致；
ctx.urlSearchParams：由ctx.location.search解析而来的查询参数对象，读取 query 比手动new URLSearchParams()更便捷。

综合实战：提交成功后跳转并携带状态

把以上能力组合起来，即可实现一个典型的「表单提交 → 跳转详情页 → 目标页根据来源展示提示」完整链路：

// 源页面（表单提交成功后） const newId = ctx.route.params?.id; // 或来自表单数据 ctx.router.navigate(`/admin/users/${newId}`, { replace: true, state: { from: 'form', message: '创建成功' } });

// 目标页面（详情页 JSBlock 中读取） const prevState = ctx.location.state; if (prevState?.from === 'form') { ctx.message.success(prevState.message); }

注意

navigate(path)默认会 push 新历史记录，用户可通过浏览器后退返回
replace: true会替换当前历史记录而不新增，适用于登录后重定向、提交成功跳转等场景
关于state参数：
- 通过state传递的数据不会出现在 URL 中，适合敏感或临时数据
- 在目标页可通过ctx.location.state访问
- state会保存在浏览器历史中，前进/后退时仍可访问
- 刷新页面后state会丢失