Skip to content

路由与菜单规范 ​

单一数据源 ​

模板使用 AppRouteRecord 作为路由和导航的单一数据源。侧边菜单、面包屑、工作标签页、全局搜索和页面标题均从同一套路由元数据生成。

后端适配器可将仅用于组织路由和权限的单页目录标记为 meta.isMenuWrapper: true。菜单在父子授权校验通过后折叠这一层,访问守卫仍使用原始路由树校验全部祖先权限;隐藏页面和普通业务目录保持原层级。适配器应为目录和页面分配唯一的路由名称,具体后端的重复根路径转换由业务适配层处理。

路由模块位于 src/router/modules,并在 src/router/modules/index.ts 中统一组合。新增标准页面不应修改布局组件或手工维护第二份菜单数据。

基础示例 ​

ts
export const exampleRoutes: AppRouteRecord = {
  name: 'Examples',
  path: '/examples',
  component: '/index/index',
  meta: {
    title: 'menus.examples.title',
    icon: 'ri:apps-2-line'
  },
  children: [
    {
      path: 'overview',
      name: 'ExampleOverview',
      component: '/examples/overview',
      meta: {
        title: 'menus.examples.overview',
        keepAlive: true
      }
    }
  ]
}

约定:

  • 顶级路由使用以 / 开头的绝对路径;
  • 子路由使用相对路径,不以 / 开头;
  • 顶级目录的 component 使用 /index/index;
  • 页面组件路径相对于 src/views,省略 .vue 和末尾 /index.vue;
  • 路由 name 必须全局唯一,并与启用 KeepAlive 的页面组件名一致;
  • meta.title 使用国际化键,同时写入中英文语言文件;
  • 顶级菜单和关键入口使用同一套 Remix Icon 图标。

常用元数据 ​

字段用途
title菜单、面包屑、标签页和浏览器标题
icon菜单和标签页图标
keepAlive标签页切换后保留组件实例和局部状态
fixedTab将页面固定在工作标签栏
isHide从菜单隐藏,但仍注册路由并允许通过 URL 访问
isHideTab不为该页面创建工作标签
activePath隐藏页或详情页进入后需要保持高亮的菜单路径
roles允许访问该路由的角色,前后端菜单模式下均执行
permissions页面所需操作权限,默认满足任一项
permissionModeall 要求 permissions 全部满足,默认 any
authList页面动作描述,不直接授予用户权限
requiresAuth静态路由是否要求登录,动态路由始终要求登录
isFullPage页面脱离常规内容区域展示,适用于异常页等系统页面

目录和隐藏详情页 ​

没有页面组件、但包含 children 的路由会作为目录菜单。目录会自动重定向到第一个可访问子页面。

详情页通常不直接显示在菜单中:

ts
{
  path: 'detail/:id',
  name: 'NavigationDetail',
  component: '/examples/navigation/detail',
  meta: {
    title: 'menus.examples.navigation.detail',
    isHide: true,
    activePath: '/examples/navigation/state'
  }
}

隐藏路由仍属于权限路由树,因此支持深链、刷新和动态参数。activePath 应指向一个实际显示在菜单中的完整路径,但不代表继承该页面的授权。详情页应声明自己的 permissions,或嵌套在带权限限制的父级下。

菜单及已注册路由会随当前用户授权更新,每次导航均检查目标及其父级限制。空菜单、权限更新和兼容迁移规则见权限规则。

KeepAlive ​

启用 keepAlive 时必须确保:

  1. 路由 name 和页面的 defineOptions({ name }) 完全一致;
  2. 页面状态保存在组件实例中,而不是依赖重复请求恢复;
  3. 刷新标签页时允许框架临时把组件加入 KeepAlive 排除列表;
  4. 不需要保留状态的详情页不要默认开启缓存。

可使用 /examples/navigation/state 验证缓存行为:输入内容、修改计数器、进入隐藏详情页,再返回确认状态未丢失。

项目接入边界 ​

模板阶段使用前端静态路由。未来接入后端菜单时,服务端数据应先通过独立的 normalizeServerRoutes() 适配为 AppRouteRecord[],再交给现有注册器。页面、布局、标签页和面包屑不应感知服务端原始字段。