NocoBase 路由管理器：统一管理系统桌面端与移动端路由和菜单-平芜编程栈

NocoBase 路由管理器：统一管理系统桌面端与移动端路由和菜单

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

路由管理器（Routes Manager）是 NocoBase 中用于管理系统主页面路由与导航菜单的工具，支持桌面端与移动端两套路由体系。路由与菜单双向同步：在路由管理器中创建的路由会同步显示在菜单中（也可配置为不在菜单中显示），反过来在页面菜单处添加的菜单也会出现在路由管理器列表中。读完本文，你可以掌握路由管理器的四种路由类型（分组、页面、标签、链接）、完整的添加与批量操作流程，以及其背后的数据模型、权限迁移与源码实现位置，从而独立完成系统导航结构的规划与维护。

路由管理器是什么

从文档定义看，路由管理器的核心价值在于把“页面路由”与“导航菜单”两件事合并为一个管理入口：

支持桌面端和移动端两套独立的路由体系；
使用路由管理器创建的路由，会同步显示在菜单中（可配置为不显示在菜单中）；
在页面菜单处添加的菜单，也会同步显示在路由管理器列表中。

也就是说，菜单并不是一个独立于路由的第二套配置，而是路由的一个“展示视图”。这一设计在源码中可以得到印证：

plugin-client 客户端入口中通过pluginSettingsManager注册了routes（路由）、routes.desktop（桌面端路由）与routes.mobile（移动端路由）三个设置项，分别绑定DesktopRoutesManager与MobileRoutesManager两个管理组件，并声明了对应的 ACL 片段（pm.routes、pm.routes.desktop、pm.routes.mobile），即路由管理功能本身也纳入了权限体系；
服务端插件实现中操作desktopRoutes仓库（repository），并通过localeManager.registerSource('desktop-routes', ...)将路由标题注册为可翻译源，使菜单名称支持多语言。

四种路由类型

系统支持四种类型的路由，覆盖了导航结构中的几乎所有场景：

类型	说明
分组（group）	用于对路由进行分组管理，可以包含子路由
页面（page）	系统内部页面
标签（tab）	用于在页面内部进行标签页切换的路由类型
链接（link）	内部或者外部链接，可直接跳转到其配置的链接地址

类型选择在创建路由的第一步完成。其中page是与具体页面实体直接关联的类型：从服务端历史数据迁移逻辑（2024122912211-transform-menu-schema-to-routes.ts）中可以看到，只有type === 'page'的路由才会进一步读取其关联的 UI Schema 来判断是否开启 Tab 页，这与“标签页是页面内部的切换机制”这一定位一致。

添加路由

点击右上角的 “Add new” 按钮可以创建新的路由，完整字段如下：

选择路由类型（Type）：即上文四种类型之一；
填写路由标题（Title）：该标题同时作为菜单显示名称，并会被注册进多语言翻译源；
选择路由图标（Icon）：用于菜单中路由条目的图标展示；
设置是否在菜单中显示（Show in menu）：关闭后路由仍然存在但不出现在导航菜单中，可用于隐藏管理页等场景；
设置是否开启 Tab 页（Enable page tabs）：对应源码中enablePageTabs配置项（可在客户端中英文文案等 locale 文件中检索到该键），开启后页面内部以标签页形式管理多个子页签；
对于页面类型，系统会自动生成唯一的路由路径（Path），无需手工编写，避免路径冲突。

路由条目操作与批量操作

每个路由条目支持以下行内操作：

Add child：添加子路由，用于构建分组/嵌套层级；
Edit：编辑路由配置（类型、标题、图标、菜单显示等）;
View：查看路由页面；
Delete：删除路由。

顶部工具栏提供批量操作功能：

Refresh：刷新路由列表；
Delete：删除选中的路由；
Hide in menu：在菜单中隐藏选中的路由；
Show in menu：在菜单中显示选中的路由。

此外，顶部 “Filter” 功能可根据需要对路由列表进行筛选，便于在路由数量较多时快速定位目标条目。

:::info 路由配置的修改将直接影响系统的导航菜单结构，请谨慎操作，确保路由配置的正确性。 :::

菜单与路由的同步机制

路由管理器的设计要点是“菜单是路由的投影”，这在数据模型层面体现为：

桌面端与移动端各自拥有独立的路由集合（desktopRoutes、mobileRoutes），由 plugin-client 服务端代码统一读写；
“是否在菜单中显示” 是路由条目上的属性，批量 “Hide in menu / Show in menu” 操作本质上就是批量修改该属性；
页面菜单处新增的菜单条目，会以路由记录的形式落库，因此能在路由管理器列表中同步看到。

历史数据迁移：从 uiSchemas 菜单到 routes

值得一提的是，路由管理器并非一开始就以独立路由集合存在。从迁移脚本 2024122912211-transform-menu-schema-to-routes.ts 可以还原这一演进过程（该迁移在appVersion < 1.6.0的版本升级时执行）：

将旧版基于uiSchemas（菜单 schema，uid 为nocobase-admin-menu）的菜单数据，经schemaToRoutes转换为新版desktopRoutes记录；
将旧版角色权限中基于menuUiSchemas的菜单授权，转换为新版的roles.desktopRoutes授权关系（计算需要移除/补充的路由 ID 后批量更新）；
对移动端路由，逐条读取type === 'page'的路由所关联的 schema，将旧的x-component-props.displayTabs映射为新的enablePageTabs配置。

这段迁移逻辑说明了两件事：其一，路由与菜单权限是绑定在一起的——角色可以授权访问哪些路由；其二，enablePageTabs正是旧版displayTabs配置的新形态，印证了前述 “Enable page tabs” 字段的历史来源。相关的数据模型与转换逻辑也有对应的测试用例覆盖，例如 schemaToRoutes.test.ts 与 desktopRoutes.test.ts，可以据此进一步验证路由集合的行为与权限修正逻辑（如 202502071837-fix-permissions.test.ts）。

小结

路由管理器是 NocoBase 中路由与菜单的统一管理入口，支持桌面端/移动端，并保证菜单与路由列表双向同步；
四种路由类型（group/page/tab/link）+ “Show in menu” 属性，覆盖了分组、内部页面、页内标签、内外部链接的全部导航诉求；
从源码结构看，路由管理功能由@nocobase/plugin-client插件承载：客户端DesktopRoutesManager/MobileRoutesManager组件负责界面，服务端desktopRoutes/mobileRoutes仓库负责数据，ACL 片段与多语言注册保证了权限与国际化支持；
修改路由会直接影响导航菜单结构，建议在变更前规划好层级与显示策略，并善用 Filter 与批量操作维护大型路由树。

更多细节可参考中文文档路由管理器。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考