Skip to content

路由(导航)

默认配置下,导航菜单通过路由数据自动生成。

项目路由存放在 /src/router/modules/ 目录下,每一个 ts 文件会被视为一个路由模块。所有路由模块最终会在 /src/router/routes.ts 文件里引入并放到不同的主导航下。

基本配置

二级路由

一个最常见的路由模块可参考以下结构:

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

const routes: RouteRecordRaw = {
  path: '/example',
  component: () => import('@/layouts/index.vue'),
  redirect: '/example/index',
  name: 'Example',
  meta: {
    title: '演示',
  },
  children: [
    {
      path: 'index',
      name: 'ExampleIndex',
      component: () => import('@/views/example/index.vue'),
      meta: {
        title: '演示页面',
      },
    },
  ],
}

export default routes

注意

  • 所有路由的 name 请确保唯一,不能重复
  • 一级路由的 component 需设置为 () => import('@/layouts/index.vue') ,并且 path 前面需要加 /,其余子路由都不要以 / 开头

多级路由

说明

多级路由最终都会转成二级路由并注册,但多级嵌套的层级结构会在导航菜单和面包屑导航中得到保留,其设计原因可阅读《页面缓存》。

多级路由的中间层级,无需设置 component

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

const routes: RouteRecordRaw = {
  path: '/example',
  component: () => import('@/layouts/index.vue'),
  redirect: '/example/level/index',
  name: 'Example',
  meta: {
    title: '演示',
  },
  children: [
    {
      path: 'level',
      // 无需设置 componment
      meta: {
        title: '中间层级',
      },
      children: [
        {
          path: 'index',
          name: 'ExampleIndex',
          component: () => import('@/views/example/index.vue'),
          meta: {
            title: '演示页面',
          },
        },
      ],
    },
  ],
}

export default routes

主导航

主导航并非路由的一部分,它只是将路由模块进行归类,这么做的目的是方便调整单个路由模块的展示位置,并且不会影响路由路径。

/src/router/routes.ts 里进行设置:

ts
const asyncRoutes: Route.recordMainRaw[] = [
  {
    meta: {
      title: '演示',
      icon: 'menu-default',
    },
    children: [
      MultilevelMenuExample,
      BreadcrumbExample,
      KeepAliveExample,
    ],
  },
  {
    meta: {
      title: '其它',
      icon: 'menu-other',
    },
    children: [
      ComponentExample,
      PermissionExample,
    ],
  },
]

主导航只需设置 metachildren 两个参数,其中 meta 接受 titlei18niconactiveIconauth 这 5 个参数,children 则是存放不同的路由模块。

导航配置

框架的核心是通过路由数据生成导航菜单,所以除了路由的基本配置外,框架还提供了针对导航的自定义配置,这些配置都存放在 meta 对象里。

title

类型默认值说明
string/导航、面包屑导航以及页面中展示的标题
v4.8.0 开始,专业版 支持设置 i18n 对应的 key 值,详细可阅读《国际化》。

i18n 专业版 v4.8.0 进入弃用过渡期,预计在 v5.0.0 正式移除

类型默认值说明
string/标题国际化对应的 key 值

详细可阅读《国际化》。

icon

类型默认值说明
string/导航中显示的图标

该项配置最终会通过 <SvgIcon /> 组件进行展示,意味着你可以使用自定义图标,也可使用 Iconify 提供的图标,详细可阅读《SVG 图标》。

activeIcon 专业版

类型默认值说明
string/导航激活时显示的图标

该项配置最终会通过 <SvgIcon /> 组件进行展示,意味着你可以使用自定义图标,也可使用 Iconify 提供的图标,详细可阅读《SVG 图标》。

defaultOpened

类型默认值说明
booleanfalse次导航是否默认展开,在父级路由上设置后,会默认展开并显示下一级的子路由

该特性仅在 顶部模式 / 侧边栏模式(含主导航) / 侧边栏模式(无主导航) 下生效。

使用该特性时,建议在应用配置中关闭 menu.subMenuUniqueOpened 设置,否则可能无法看到效果。

alwaysOpened 专业版 v4.7.0 新增

类型默认值说明
booleanfalse次导航是否始终展开,在父级路由上设置后,会始终展开并显示下一级的子路由

该特性仅在 顶部模式 / 侧边栏模式(含主导航) / 侧边栏模式(无主导航) 下生效。

permanent 专业版

类型默认值说明
booleanfalse是否常驻标签页

使用该特性时,需要在应用配置中开启 tabbar.enable 设置,同时需注意,请勿在带有参数的路由上设置该特性。

auth

类型默认值说明
string / string[]/该路由访问权限,支持多个权限叠加,只要满足一个,即可进入

用户在访问路由时,会判断当前路由是否具备访问权限,不具备访问权限则会显示 403 页面,详细可阅读《权限 - 路由权限》。

如果在某个多级路由的多个层级上均设置了 auth ,则框架会依次判断,必须每一层级都具备访问权限,才能访问该路由。

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

const routes: RouteRecordRaw = {
  path: '/system',
  meta: {
    title: '系统管理',
  },
  children: [
    {
      path: 'department',
      meta: {
        title: '部门管理',
        auth: 'a',
      },
      children: [
        {
          path: 'job',
          meta: {
            title: '职位管理',
          },
          children: [
            {
              path: 'member',
              meta: {
                title: '人员管理',
                auth: 'b', // 只有当用户权限里同时含有 a 和 b 时,才能访问该路由
              },
            },
          ],
        },
      ],
    },
  ],
}

export default routes
v4.8.0 之前版本处理逻辑

为避免多级路由同时设置 auth 可能会导致逻辑冲突,框架会以最先设置的 auth 为准:

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

const routes: RouteRecordRaw = {
  path: '/system',
  meta: {
    title: '系统管理',
  },
  children: [
    {
      path: 'department',
      meta: {
        title: '部门管理',
        auth: 'a',
      },
      children: [
        {
          path: 'job',
          meta: {
            title: '职位管理',
          },
          children: [
            {
              path: 'member',
              meta: {
                title: '人员管理',
                auth: 'b', // 无效设置,该路由的访问权限会以 auth: 'a' 为准
              },
            },
          ],
        },
      ],
    },
  ],
}

export default routes

auths 专业版 v4.7.0 新增

类型默认值说明
{ name: string; value: string }[]
/权限池,对路由本身无实际作用,通常用于角色管理模块,展示路由(导航)可配置权限

权限池存放了该路由相关的所有权限,包括但不限于:访问权限、按钮权限、颗粒度更细的权限等。以下是一个示例:

注意

  • auths 里需包含 auth 所设置的权限,否则会导致无法设置该路由的访问权限。
  • auths 的存放位置并不固定,可以放在任意一级路由上,但通常建议放在某个模块的入口路由上,表示该模块下所有子路由具备的可配置权限。
ts
import type { RouteRecordRaw } from 'vue-router'

const routes: RouteRecordRaw = {
  path: '/news',
  component: () => import('@/layouts/index.vue'),
  meta: {
    title: '新闻管理',
    auths: [
      { name: '浏览', value: 'browse' },
      { name: '新增', value: 'add' },
      { name: '编辑', value: 'edit' },
      { name: '删除', value: 'delete' },
      { name: '导出', value: 'export' },
      { name: '导入', value: 'import' },
    ],
  },
  children: [
    {
      path: 'list',
      component: () => import('@/views/news/list.vue'),
      meta: {
        title: '新闻列表',
        auth: 'browse',
      },
    },
    {
      path: 'detail',
      component: () => import('@/views/news/detail.vue'),
      meta: {
        title: '新闻详情',
        menu: false,
        activeMenu: '/news/list',
        auth: 'browse',
      },
    },
  ],
}

export default routes

该配置的具体应用可参考专业版演示站示例源码

请使用下方 menu 配置项。

类型默认值说明
booleantrue该路由是否在菜单导航中展示

当子路由里没有可展示的路由时,在菜单导航中则只会显示父级路由,例如:

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

const routes: RouteRecordRaw = {
  path: '/permission',
  component: () => import('@/layouts/index.vue'),
  meta: {
    title: '权限验证',
  },
  children: [
    {
      path: '',
      component: () => import('@/views/permission.vue'),
      meta: {
        title: '权限验证',
        menu: false,
      },
    },
  ],
}

export default routes

activeMenu

类型默认值说明
string/指定高亮的菜单导航,需要设置完整路由地址

该参数常与 menu: false 一起使用,因为路由不在菜单导航显示,会导致进入该路由后,菜单导航高亮效果失效,所以需要手动指定。

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

const routes: RouteRecordRaw = {
  path: '/news',
  component: () => import('@/layouts/index.vue'),
  meta: {
    title: '新闻管理',
  },
  children: [
    {
      path: 'list',
      component: () => import('@/views/news/list.vue'),
      meta: {
        title: '新闻列表',
      },
    },
    {
      path: 'detail',
      component: () => import('@/views/news/detail.vue'),
      meta: {
        title: '新闻详情',
        menu: false,
        activeMenu: '/news/list',
      },
    },
  ],
}

export default routes

singleMenu 专业版 v4.6.0 新增

类型默认值说明
boolean/是否为单个一级导航菜单

该配置用于简化只想展示一级,没有二级菜单导航的路由配置。

需注意,该配置只能在一级路由上设置,且只在一级路由上生效。

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

const routes: RouteRecordRaw = {
  path: '/test',
  name: 'test',
  component: () => import('@/views/test/index.tsx'),
  meta: {
    title: '测试页面',
    singleMenu: true,
  },
}

export default routes

以上路由配置等同于以下配置:

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

const routes: RouteRecordRaw = {
  path: '/test',
  component: () => import('@/layouts/index.vue'),
  meta: {
    title: '测试页面',
  },
  children: [
    {
      path: '',
      name: 'test',
      component: () => import('@/views/test/index.tsx'),
      meta: {
        title: '测试页面',
        menu: false,
        breadcrumb: false,
      },
    },
  ],
}

export default routes
类型默认值说明
booleantrue该路由是否在面包屑导航中展示

cache

类型默认值说明
boolean / string / string[]/是否对该页面进行缓存
  • boolean 设置为 true 时,该路由页面会被一直缓存
  • string 设置某个目标路由的 name ,表示当前路由页面跳转到设置的 name 对应的路由页面时,则将当前路由页面进行缓存,否则不缓存
  • string[] ,可设置一个目标路由的 name 数组

当类型为 stringstring[] 时,可以更精细的去控制页面缓存的逻辑。例如从列表页进入详情页,则需要将列表页进行缓存;而从列表页进入其它页面,则无需将列表页进行缓存。详细可阅读《页面缓存》。

noCache

类型默认值说明
string / string[]/是否对该页面清除缓存,须设置 cache 才会生效
  • string 设置某个目标路由的 name ,表示当前路由页面跳转到设置的 name 对应的路由页面时,则将当前路由页面清除缓存,否则不清除缓存
  • string[] ,可设置一个目标路由的 name 数组

该属性通常在启用标签栏合并时会使用到。详细可阅读《页面缓存 - 标签栏开启且合并》。

badge 专业版

类型默认值说明
boolean / number / string/导航标记

设置不同的类型值,展示效果也会不同。

  • boolean 展示形式为点,当值为 false 时隐藏
  • number 展示形式为文本,当值小于等于 0 时隐藏
  • string 展示形式为文本,当值为空时隐藏

如果标记需要动态更新,请设置为箭头函数形式,并返回外部变量,例如搭配 pinia 一起使用。

ts
badge: () => globalStore.number

newWindow 专业版 v4.2.0 新增

类型默认值说明
booleanfalse是否在新窗口打开

该设置仅在菜单导航里点击生效。

类型默认值说明
string/外部网页链接

会在新窗口访问该链接。

外部网页无需设置 component ,但需设置 redirectname 属性。

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

const routes: RouteRecordRaw = {
  path: '/xxx',
  component: () => import('@/layouts/index.vue'),
  redirect: '/xxx/link',
  meta: {
    title: '外部网页',
  },
  children: [
    {
      path: 'link',
      redirect: '',
      name: 'Link',
      meta: {
        title: 'Gitee 仓库',
        link: 'https://gitee.com/fantastic-admin/basic',
      },
    },
  ],
}

export default routes

iframe 专业版

类型默认值说明
string / boolean/内嵌网页链接

会启用一个 <iframe> 并载入该链接。

内嵌网页无需设置 component ,但需设置 redirectname 属性,如果同时设置了 meta.linkmeta.link 优先级更高。

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

const routes: RouteRecordRaw = {
  path: '/xxx',
  component: () => import('@/layouts/index.vue'),
  redirect: '/xxx/iframe',
  meta: {
    title: '内嵌网页',
  },
  children: [
    {
      path: 'iframe',
      redirect: '',
      name: 'Iframe',
      meta: {
        title: 'Gitee 仓库',
        iframe: 'https://gitee.com/fantastic-admin/basic',
      },
    },
  ],
}

export default routes

内嵌网页同样支持使用 meta.cachemeta.noCache 属性来开启页面缓存,但考虑到 <iframe> 本身的性能问题,框架默认提供最大缓存数量为 3 个,超过 3 个则会自动清除最早的缓存页面。

如果需要修改最大缓存数量,请在应用配置中设置:

ts
const globalSettings: Settings.all = {
  mainPage: {
    iframeCacheMax: 3,
  },
}
v4.11.0 开始,增加了动态设置 iframe 链接,只需要配置一份如下路由:
ts
import type { RouteRecordRaw } from 'vue-router'

const routes: RouteRecordRaw = {
  path: '/xxx',
  component: () => import('@/layouts/index.vue'),
  redirect: '/xxx/iframe',
  meta: {
    title: '内嵌网页',
  },
  children: [
    {
      path: 'iframe',
      redirect: '',
      name: 'Iframe',
      meta: {
        title: 'Gitee 仓库',
        iframe: 'https://gitee.com/fantastic-admin/basic',
      },
    },
    {
      path: 'dynamic',
      redirect: '',
      name: 'Dynamic',
      meta: {
        title: '外部链接',
        menu: false,
        iframe: true,
      },
    },
  ],
}

export default routes

然后就可以通过跳转路由的方式动态设置 iframe 链接了:

ts
const router = useRouter()

router.push({
  name: 'Dynamic',
  // 这里需要使用到 query 参数,且约定参数名为 title 和 iframe
  query: {
    title: '自定义标题', // 非必须,默认使用该路由的 meta.title
    iframe: 'https://fantastic-admin.hurui.me/', // 必须
  },
})
类型默认值说明
boolean/该路由是否显示底部版权信息

该参数比应用配置里的 copyright.enable 优先级高,不设置则继承应用配置里的设置。

paddingBottom 专业版

类型默认值说明
string/该路由是否需要空出距离底部距离

当使用类似 <FixedActionBar /> 这类通过 position: fixed 固定在底部的组件时,需要手动设置该参数,目的是为了防止页面底部可能被遮挡。

ts
paddingBottom: '80px'

whiteList 专业版

类型默认值说明
boolean/是否开启白名单,开启后无需登录即可访问

这个属性比较特殊,因为基于后台框架的页面基本上都是需要登录后才能访问,如果希望增加免登录的页面(白名单页面),也就是脱离框架本身,相对独立的页面,你可以按照下面的方式处理:

首先在 /src/router/routes.tsconstantRoutes 配置免登录页面的路由,然后在 meta 对象里设置 whiteList: true ,例子如下:

ts
const constantRoutes: RouteRecordRaw[] = [
  {
    path: '/no/login/example',
    name: 'noLoginExample',
    component: () => import('@/views/no-login-example.vue'),
    meta: {
      title: '免登录页面',
      whiteList: true,
    },
  },
]

需要注意,请勿在系统路由动态路由上设置该属性,因为这里面的路由,它们的一级路由调用的是 Layout 组件,而 Layout 组件是必须登录才能正常使用。

小技巧

通常我们配置的路由都是这样的:

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

const routes: RouteRecordRaw = {
  path: '/banner',
  component: () => import('@/layouts/index.vue'),
  redirect: '/banner/list',
  name: 'banner',
  meta: {
    title: 'Banner 管理',
  },
  children: [
    {
      path: 'add',
      name: 'bannerAdd',
      component: () => import('@/views/banner/add.vue'),
      meta: {
        title: '新增 banner',
      },
    },
    {
      path: 'list',
      name: 'bannerList',
      component: () => import('@/views/banner/list.vue'),
      meta: {
        title: 'banner 列表',
      },
    },
  ],
}

export default routes

对应的展示效果如下:

有时候会遇到这样的需求,要求在不改变菜单导航结构的前提下,面包屑导航展示嵌套的结构:

要实现这个效果也很简单,根据图中的效果,可以确定路由需要有三级。我们只需在二级放置一个重定向的路由,将其重定向到三级里的某个真实路由上,同时将三级路由均设置成不在菜单导航上显示即可,最终实现代码如下:

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

const routes: RouteRecordRaw = {
  path: '/banner',
  component: () => import('@/layouts/index.vue'),
  redirect: '/banner/list',
  name: 'banner',
  meta: {
    title: 'Banner 管理',
  },
  children: [
    {
      path: 'add',
      redirect: '/banner/list/add',
      meta: {
        title: '新增 Banner',
      },
    },
    {
      path: 'list',
      meta: {
        title: 'Banner 列表'
      },
      children: [
        {
          path: 'add',
          name: 'bannerAdd',
          component: () => import('@/views/banner/add.vue'),
          meta: {
            title: '新增 Banner',
            menu: false,
            activeMenu: '/banner/add',
          }
        },
        {
          path: '',
          name: 'bannerList',
          component: () => import('@/views/banner/list.vue'),
          meta: {
            title: 'Banner 列表',
            menu: false,
            breadcrumb: false,
          }
        },
      ],
    },
  ],
}

export default routes

后端生成

不推荐!

导航后端配置并生成这个需求,基本上是后端开发者刚接触前端后台项目开发时最常问的一个问题,但当真正做过前端开发并了解 Vue 的开发模式后,会意识到这个需求是多此一举的,并且会导致框架提供的部分导航特性无法使用,是得不偿失的做法。

其根本原因在于,导航是通过路由生成的,而路由是与页面组件直接挂钩,即一个路由则对应着一个 .vue 的页面组件文件。即便将路由数据通过后端配置,也要确保路由对应的页面组件在项目中存在,这就导致在开发环境下,通过后端配置好路由数据后,还需要在项目中新增对应的 .vue 文件写业务代码,并不是后端新增一个路由,前端就能直接访问到该路由页面,这也就意味着在生产环境中不能随意修改路由数据,可能会导致导航无法访问,因为很多路由设置和业务逻辑是高度耦合的,例如页面跳转用到的 namepath 不能随意修改,component 不能设置不存在的页面组件。能交给后端动态配置的最多也就只有 titleicon 这两个属性,所以仅仅为了这个需求,而让开发流程复杂化,是得不偿失的一种做法。

如果你执意使用该特性,请确保你了解该特性在上面所说的优缺点,并谨慎使用!

在应用配置中设置:

ts
const globalSettings: Settings.all = {
  app: {
    routeBaseOn: 'backend'
  }
}

开启后在 /src/api/modules/app.ts 文件里找到 routeList() 这个函数,并修改这个函数的请求地址,请求返回的数据就是路由数据,你可以在 /src/mock/app.ts 里查看 mock 数据。

开启后端生成后,路由权限有两种做法,第一种是返回全部的路由数据,让框架自行处理(推荐),第二种是后端直接返回用户具备访问权限的路由数据。

两种做法的区别在于第一种做法对后端相对轻松,无需对数据做任何处理,并且对于无权限访问的路由,框架会以 403 页面进行展示;而第二种做法需要后端对处理进行处理,并且无需在 meta 对象里设置 auth 参数,但由于直接在数据源上就过滤掉了无权限的路由,所以在访问没有权限的路由时会直接显示 404 页面。

基于文件系统的路由

基于文件系统的路由是除后端生成路由外,另一种路由生成方式。如果你有后端生成路由的需求,不妨先了解下文件系统路由这一特性,它的优势在于将路由和导航菜单进行了解耦,后端无需再关心路由数据,只需提供导航菜单数据即可,详细可阅读《基于文件系统的路由》。