kt-template-admin/skills/references/core/route.md

路由与菜单详细配置

路由类型

核心路由

框架内置路由，位于 src/router/routes/core/，包含根路由、登录路由、404路由等。

静态路由

位于 src/router/routes/index/，项目启动时已确定的路由。

动态路由

位于 src/router/routes/modules/，根据用户权限动态生成。

路由 Meta 配置

interface RouteMeta {
  // 页面标题（必填）
  title: string;

  // 菜单/标签页图标
  icon?: string;

  // 激活图标
  activeIcon?: string;

  // 菜单排序（仅一级菜单有效）
  order?: number;

  // 开启 KeepAlive 缓存
  keepAlive?: boolean;

  // 在菜单中隐藏
  hideInMenu?: boolean;

  // 在标签页中隐藏
  hideInTab?: boolean;

  // 在面包屑中隐藏
  hideInBreadcrumb?: boolean;

  // 子菜单在菜单中隐藏
  hideChildrenInMenu?: boolean;

  // 权限控制
  authority?: string[];

  // 忽略权限，直接访问
  ignoreAccess?: boolean;

  // 菜单可见但禁止访问（跳转403）
  menuVisibleWithForbidden?: boolean;

  // 固定标签页
  affixTab?: boolean;

  // 固定标签页顺序
  affixTabOrder?: number;

  // 标签页最大打开数量
  maxNumOfOpenTab?: number;

  // 徽标
  badge?: string;

  // 徽标类型 'dot' | 'normal'
  badgeType?: 'dot' | 'normal';

  // 徽标颜色
  badgeVariants?: 'default' | 'destructive' | 'primary' | 'success' | 'warning';

  // 外链跳转路径
  link?: string;

  // 在新窗口打开
  openInNewWindow?: boolean;

  // iframe 地址
  iframeSrc?: string;

  // 激活指定菜单路径
  activePath?: string;

  // 不使用基础布局
  noBasicLayout?: boolean;

  // 完整路径作为 tab key
  fullPathKey?: boolean;

  // DOM 缓存（解决复杂页面切换卡顿）
  domCached?: boolean;
}

新增页面示例

1. 添加路由文件 src/router/routes/modules/home.ts：

import type { RouteRecordRaw } from 'vue-router';

import { $t } from '#/locales';

const routes: RouteRecordRaw[] = [
  {
    meta: {
      icon: 'mdi:home',
      title: $t('page.home.title'),
      order: 1000,
    },
    name: 'Home',
    path: '/home',
    redirect: '/home/index',
    children: [
      {
        name: 'HomeIndex',
        path: '/home/index',
        component: () => import('#/views/home/index.vue'),
        meta: {
          icon: 'mdi:home',
          title: $t('page.home.index'),
        },
      },
    ],
  },
];

export default routes;

2. 添加页面组件 src/views/home/index.vue：

<template>
  <div>
    <h1>Home Page</h1>
  </div>
</template>

多级路由示例

const routes: RouteRecordRaw[] = [
  {
    meta: {
      icon: 'ic:baseline-view-in-ar',
      title: '多级菜单',
    },
    name: 'Nested',
    path: '/nested',
    redirect: '/nested/menu1',
    children: [
      {
        name: 'Menu1',
        path: '/nested/menu1',
        component: () => import('#/views/nested/menu1.vue'),
        meta: { title: '菜单1' },
      },
      {
        name: 'Menu2',
        path: '/nested/menu2',
        meta: { title: '菜单2' },
        redirect: '/nested/menu2/menu2-1',
        children: [
          {
            name: 'Menu21',
            path: '/nested/menu2/menu2-1',
            component: () => import('#/views/nested/menu2-1.vue'),
            meta: { title: '菜单2-1' },
          },
        ],
      },
    ],
  },
];

路由刷新

import { useRefresh } from '@vben/hooks';

const { refresh } = useRefresh();
refresh(); // 刷新当前路由

标签页控制

标签页使用唯一 key 标识，优先级：

1. 路由 query 参数 pageKey
2. 路由完整路径（fullPathKey 不为 false 时）
3. 路由 path（fullPathKey 为 false 时）

// 使用 pageKey 打开多个标签页
router.push({
  path: '/detail',
  query: { pageKey: 'unique-id' },
});