Skip to main content
在项目中，框架提供了一套基础的路由系统，并根据路由文件自动生成对应的菜单结构。

​
路由类型

路由分为核心路由、静态路由和动态路由，核心路由是框架内置的路由，包含了根路由、登录路由、404路由等；静态路由是在项目启动时就已经确定的路由；动态路由一般是在用户登录后，根据用户的权限动态生成的路由。 静态路由和动态路由都会走权限控制，可以通过配置路由的 meta 属性中的 authority 字段来控制权限，可以参考路由权限控制。

​
核心路由

核心路由是框架内置的路由，包含了根路由、登录路由、404路由等，核心路由的配置在应用下 src/router/routes/core 目录下
核心路由主要用于框架的基础功能，因此不建议将业务相关的路由放在核心路由中，推荐将业务相关的路由放在静态路由或动态路由中。

​
静态路由

静态路由的配置在应用下 src/router/routes/index 目录下，打开注释的文件内容:
权限控制是通过路由的 meta 属性中的 authority 字段来控制的，如果你的页面项目不需要权限控制，可以不设置 authority 字段。
// 有需要可以自行打开注释，并创建文件夹
// const externalRouteFiles = import.meta.glob('./external/**/*.ts', { eager: true });
const staticRouteFiles = import.meta.glob('./static/**/*.ts', { eager: true }); 
/** 动态路由 */
const dynamicRoutes: RouteRecordRaw[] = mergeRouteModules(dynamicRouteFiles);

/** 外部路由列表，访问这些页面可以不需要Layout，可能用于内嵌在别的系统 */
// const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles)
const externalRoutes: RouteRecordRaw[] = []; 
const externalRoutes: RouteRecordRaw[] = mergeRouteModules(externalRouteFiles);

​
动态路由

动态路由的配置在对应应用 src/router/routes/modules 目录下，这个目录下存放了所有的路由文件。每个文件的内容格式如下，与 Vue Router 的路由配置格式一致，以下为二级路由和多级路由的配置。

​
路由定义

静态路由与动态路由的配置方式一致，以下为二级路由和多级路由的配置：

​
二级路由

​
多级路由

如果没有特殊情况，父级路由的 redirect 属性，不需要指定，默认会指向第一个子路由。

​
新增页面

新增一个页面，你只需要添加一个路由及对应的页面组件即可。

​
添加路由

在对应的路由文件中添加一个路由对象，如下： 
import type { RouteRecordRaw } from 'vue-router';

import { VBEN_LOGO_URL } from '@vben/constants';

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

const routes: RouteRecordRaw[] = [
  {
    meta: {
      icon: 'mdi:home',
      title: $t('page.home.title'),
    },
    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;

​
添加页面组件

在#/views/home/下，新增一个index.vue文件，如下： 
<template>
  <div>
    <h1>home page</h1>
  </div>
</template>

​
验证

到这里页面已添加完成，访问 http://localhost:5555/home/index 出现对应的页面即可。

​
路由配置

路由配置项主要在对象路由的 meta 属性中，以下为常用的配置项： 
const routes = [
  {
    name: 'HomeIndex',
    path: '/home/index',
    meta: {
      icon: 'mdi:home',
      title: $t('page.home.index'),
    },
  },
];

​
title

  • 类型：string
  • 默认值：''
用于配置页面的标题，会在菜单和标签页中显示。一般会配合国际化使用。

​
icon

  • 类型：string
  • 默认值：''
用于配置页面的图标，会在菜单和标签页中显示。一般会配合图标库使用，如果是http链接，会自动加载图片。

​
activeIcon

  • 类型：string
  • 默认值：''
用于配置页面的激活图标，会在菜单中显示。一般会配合图标库使用，如果是http链接，会自动加载图片。

​
keepAlive

  • 类型：boolean
  • 默认值：false
用于配置页面是否开启缓存，开启后页面会缓存，不会重新加载，仅在标签页启用时有效。

​
hideInMenu

  • 类型：boolean
  • 默认值：false
用于配置页面是否在菜单中隐藏，隐藏后页面不会在菜单中显示。

​
hideInTab

  • 类型：boolean
  • 默认值：false
用于配置页面是否在标签页中隐藏，隐藏后页面不会在标签页中显示。

​
hideInBreadcrumb

  • 类型：boolean
  • 默认值：false
用于配置页面是否在面包屑中隐藏，隐藏后页面不会在面包屑中显示。

​
hideChildrenInMenu

  • 类型：boolean
  • 默认值：false
用于配置页面的子页面是否在菜单中隐藏，隐藏后子页面不会在菜单中显示。

​
authority

  • 类型：string[]
  • 默认值：[]
用于配置页面的权限，只有拥有对应权限的用户才能访问页面，不配置则不需要权限。

​
badge

  • 类型：string
  • 默认值：''
用于配置页面的徽标，会在菜单显示。

​
badgeType

  • 类型：'dot' | 'normal'
  • 默认值：'normal'
用于配置页面的徽标类型，dot 为小红点，normal 为文本。

​
badgeVariants

  • 类型：'default' | 'destructive' | 'primary' | 'success' | 'warning' | string
  • 默认值：'success'
用于配置页面的徽标颜色。

​
activePath

  • 类型：string
  • 默认值：''
用于配置当前激活的菜单，有时候页面没有显示在菜单内，需要激活父级菜单时使用。

​
affixTab

  • 类型：boolean
  • 默认值：false
用于配置页面是否固定标签页，固定后页面不可关闭。

​
affixTabOrder

  • 类型：number
  • 默认值：0
用于配置页面固定标签页的排序, 采用升序排序。

​
iframeSrc

  • 类型：string
  • 默认值：''
用于配置内嵌页面的 iframe 地址，设置后会在当前页面内嵌对应的页面。

​
ignoreAccess

  • 类型：boolean
  • 默认值：false
用于配置页面是否忽略权限，直接可以访问。
  • 类型：string
  • 默认值：''
用于配置外链跳转路径，会在新窗口打开。

​
maxNumOfOpenTab

  • 类型：number
  • 默认值：-1
用于配置标签页最大打开数量，设置后会在打开新标签页时自动关闭最早打开的标签页(仅在打开同名标签页时生效)。
  • 类型：boolean
  • 默认值：false
用于配置页面在菜单可以看到，但是访问会被重定向到403。

​
openInNewWindow

  • 类型：boolean
  • 默认值：false
设置为 true 时，会在新窗口打开页面。

​
order

  • 类型：number
  • 默认值：0
用于配置页面的排序，用于路由到菜单排序。 注意: 排序仅针对一级菜单有效，二级菜单的排序需要在对应的一级菜单中按代码顺序设置。

​
query

  • 类型：Recordable
  • 默认值：{}
用于配置页面的菜单参数，会在菜单中传递给页面。

​
noBasicLayout

  • 类型：boolean
  • 默认值：false
用于配置当前路由不使用基础布局，仅在顶级时生效。默认情况下，所有的路由都会被包裹在基础布局中（包含顶部以及侧边等导航部件），如果你的页面不需要这些部件，可以设置 noBasicLayout 为 true。

​
路由刷新

路由刷新方式如下： 
<script setup lang="ts">
import { useRefresh } from '@vben/hooks';

const { refresh } = useRefresh();

// 刷新当前路由
refresh();
</script>