外观
路由与菜单规范
单一数据源
模板使用 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 | 页面所需操作权限,默认满足任一项 |
permissionMode | all 要求 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 时必须确保:
- 路由
name和页面的defineOptions({ name })完全一致; - 页面状态保存在组件实例中,而不是依赖重复请求恢复;
- 刷新标签页时允许框架临时把组件加入 KeepAlive 排除列表;
- 不需要保留状态的详情页不要默认开启缓存。
可使用 /examples/navigation/state 验证缓存行为:输入内容、修改计数器、进入隐藏详情页,再返回确认状态未丢失。
项目接入边界
模板阶段使用前端静态路由。未来接入后端菜单时,服务端数据应先通过独立的 normalizeServerRoutes() 适配为 AppRouteRecord[],再交给现有注册器。页面、布局、标签页和面包屑不应感知服务端原始字段。