从 Vue2 到 Vue3 ，你必须要掌握的路由差异和使用场景！

很多兄弟在使用 Vue3 了，但对 Vue3 的路由却了解的非常少。甚至只知道基本的跳转和参数获取，这样做一些稍微复杂的功能肯定不够用的。最近就把 Vue3 的路由（Vue-Router4）的版本差异和使用场景整理了一下分享给大家。会的兄弟可以复习一下，不会的兄弟抓紧学起来哦！

路由模式

Vue3 中不再使用 new Router() 创建 router ，而是调用 createRouter 方法：

import { createRouter } from 'vue-router'

const router = createRouter({
  // ...
})

路由模式 mode 配置改为 history ，属性值调整为：

• "history" => createWebHistory()
• "hash" => createWebHashHistory()
• "abstract" => createMemoryHistory()

import { createRouter, createWebHistory } from 'vue-router'
// createWebHashHistory 和 createMemoryHistory (SSR相关) 同理

createRouter({
  history: createWebHistory(),
  routes: []
})

基础路径 base 被作为 createWebHistory 的第一个参数进行传递（其他路由模式也是一样）：

import { createRouter, createWebHistory } from 'vue-router'
createRouter({
  history: createWebHistory('/base-url/'),
  routes: []
})

路由跳转

使用组件跳转，方式还是和 Vue2 一样：

<RouterLink to="/user">User</RouterLink>
<RouterLink :to="{ path: '/user', query: { username: 'Jack' } }">User</RouterLink>
<RouterLink :to="{ name: 'user', params: { username: 'Tom' } }">User</RouterLink>

当然，最常见的还是编程式导航，这时候需要引入 useRouter 方法：

import { useRouter } from 'vue-router'

const router = useRouter()

// 字符串路径
router.push('/user')

// 带有路径的对象
router.push({ path: '/user', query: { username: 'Jack' } })
router.push({ path: '/user', hash: '#team' })

// 带有命名的对象
router.push({ name: 'user', query: { username: 'Jack' } })
router.push({ name: 'user', params: { username: 'Tom' } })
router.push({ name: 'user', hash: '#team' })

注意：参数 params 不能和 path 一起使用。RouterLink 组件 to 属性与 router.push() 接受的参数相同，两者的规则也完全相同。

导航守卫

全局前置守卫

全局前置守卫通常用来做权限控制，使用 router.beforeEach 即可添加：

const router = createRouter({ ... })

router.beforeEach((to, from) => {
  // ...
  // 返回 false 以取消导航
  return false
})

每个守卫方法接收两个参数：

• to：即将进入的目标路由
• from：当前正要离开的路由

可以返回的值如下:

• false：取消当前的导航。
• true 或 undefined，调用下一个守卫。
• 一个路由地址：字符串或对象。表示中断当前导航，进行一个新的导航。

 router.beforeEach(async (to, from) => {
   // 检查用户是否已登录，并且避免无限重定向
   if (!isAuthenticated && to.name !== 'Login') {
     return { name: 'Login' } // 将用户重定向到登录页面
   }
 })

在之前的 Vue Router 版本中，也是可以使用第三个参数 next 的。目前，它仍然是被支持的，这意味着你可以向任何导航守卫传递第三个参数。在这种情况下，要确保 next 在导航守卫中只被调用一次。

全局解析守卫

router.beforeResolve 用法和 router.beforeEach 类似。它是在导航被确认之前，所有组件内守卫和异步路由组件被解析之后被调用。下面这个例子，确保用户可以访问自定义 meta 属性：

router.beforeResolve(async to => {
  if (to.meta.requiresCamera) {
    try {
      await askForCameraPermission()
    } catch (error) {
      if (error instanceof NotAllowedError) {
        // ... 处理错误，然后取消导航
        return false
      } else {
        // 意料之外的错误，取消导航并把错误传给全局处理器
        throw error
      }
    }
  }
})

router.beforeResolve 是获取数据或执行任何其他操作（进入所有页面后都执行的操作）的理想位置。

全局后置钩子

和守卫不同的是，全局后置钩子不接受 next 函数，也不能跳转到其他的路由地址：

router.afterEach((to, from) => {
  sendToAnalytics(to.fullPath)
})

但它可以接收 failure 作为第三个参数：

router.afterEach((to, from, failure) => {
  if (!failure) sendToAnalytics(to.fullPath)
})

router.afterEach 对于访问分析、更改页面标题、声明页面等辅助功能都很有帮助。

路由独享的守卫

我们可以直接在路由配置上定义 beforeEnter 守卫：

const routes = [
  {
    path: '/users/:id',
    component: UserDetails,
    beforeEnter: (to, from) => {
      // 取消导航
      return false
    },
  },
]

beforeEnter 守卫只在进入路由时触发，不会在 params、query 或 hash 改变时触发。例如，从 /users/2 进入到 /users/3 或者从 /users/2#info 进入到 /users/2#projects 不会触发。

我们也可以将一个函数数组传递给 beforeEnter，这在为不同的路由重用守卫时很有用：

// 清除 query 参数
function removeQueryParams(to) {
  if (Object.keys(to.query).length)
    return { path: to.path, query: {}, hash: to.hash }
}
// 清除 hash 值
function removeHash(to) {
  if (to.hash) return { path: to.path, query: to.query, hash: '' }
}

const routes = [
  {
    path: '/users/:id',
    component: UserDetails,
    beforeEnter: [removeQueryParams, removeHash]
  },
  {
    path: '/about',
    component: UserDetails,
    beforeEnter: [removeQueryParams]
  }
]

当然，你也可以通过使用路由的 meta 属性和 全局导航守卫 来实现以上功能。

组件内的守卫

使用声明式 API ，你可以为组件添加以下守卫：

• beforeRouteEnter
• beforeRouteUpdate
• beforeRouteLeave

beforeRouteEnter 守卫不能访问 this，因为此时组件还没有被创建。你可以通过传一个回调给 next 来访问组件实例。在导航被确认的时候执行回调，并且把组件实例作为回调方法的参数：

beforeRouteEnter (to, from, next) {
  next(vm => {
    // 通过 `vm` 访问组件实例
  })
}

注意：beforeRouteEnter 是支持 next 传递回调函数的唯一守卫。

beforeRouteUpdate 在当前路由改变，但是该组件被复用时调用。比如，对于一个带有动态参数的路径 /users/:id，在 /users/1 和 /users/2 之间跳转的时候被调用。因为这种情况发生的时候，组件已经挂载好了，导航守卫可以访问组件实例 this。

beforeRouteUpdate (to, from) {
  // 可以使用 this
  this.name = to.params.name
}

beforeRouteLeave 通常用来预防用户在还未保存修改前突然离开。该守卫可以通过返回 false 来取消导航。

beforeRouteLeave (to, from) {
  const answer = window.confirm('Do you really want to leave? you have unsaved changes!')
  // 取消导航并停留在当前页面
  if (!answer) return false
}

使用组合式 API，你可以为组件添加 onBeforeRouteUpdate 、onBeforeRouteLeave 导航守卫：

<script setup lang="ts">
import { ref } from 'vue'
import { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router'

const userData = ref()

onBeforeRouteUpdate(async (to, from) => {
  //仅当 id 更改时才获取用户信息
  if (to.params.id !== from.params.id) {
    userData.value = await fetchUser(to.params.id)
  }
})

onBeforeRouteLeave((to, from) => {
  const answer = window.confirm('Do you really want to leave? you have unsaved changes!')
  // 取消导航并停留在当前页面
  if (!answer) return false
})
</script>

注意：由于 setup 函数调用时机的问题，使用组合式 API 不存在 onBeforeRouteEnter。

路由组件传参

当我们获取路由参数时，通常在模板中使用 $route ，在逻辑中调用 useRoute() 方法，如：

<template>
  <div>User {{ $route.params.id }}</div>
</template>

<script setup lang="ts">
import { useRoute } from 'vue-router'
const route = useRoute()
console.log(route.params.id)
</script>

以上方法比较麻烦，而且与路由紧密耦合，不利于组件封装。我们可以在创建路由时通过 props 配置来解除这种行为：

const routes = [
  {
    path: '/user/:id',
    name: 'user',
    component: User,
    props: true
  }
]

此时 route.params 将直接被设置为组件的 props，这样组件就和路由参数解耦了：

<template>
  <div>User {{ id }}</div>
</template>

<script setup lang="ts">
const props = defineProps<{
  id: string
}>()
console.log(props.id)
</script>

布尔模式

当 props 设置为 true 时，route.params 将被设置为组件的 props。

命名视图

对于有命名视图的路由，你必须为每个命名视图定义 props 配置：

const routes = [
  {
    path: '/user/:id',
    components: { default: User, sidebar: Sidebar },
    props: { default: true, sidebar: false }
  }
]

对象模式

当 props 是一个对象时，它会将此对象设置为组件 props 。当 props 是静态的时候很有用。

const routes = [
  {
    path: '/user',
    component: User,
    props: { newsletterPopup: false }
  }
]

函数模式

我们也可以创建一个返回 props 的函数。这允许你将参数转换为其他类型：

const routes = [
  {
    path: '/user',
    component: User,
    props: route => ({ id: route.query.userId })
  }
]

如 /user?userId=123 参数会被转为 { id: '123' } 作为 props 传给 User 组件。

滚动行为

我们可以通过 vue-router 自定义路由切换时页面如何滚动。比如，当跳转到新路由时，页面滚动到某个位置；切换路由时页面回到之前的滚动位置。

当创建路由实例时，我们只需要提供一个 scrollBehavior 方法：

const router = createRouter({
  history: createWebHashHistory(),
  routes: [...],
  scrollBehavior (to, from, savedPosition) {
    // return 期望滚动到哪个的位置
  }
})

scrollBehavior 函数接收 to和 from 路由对象。第三个参数 savedPosition，只有当这是一个 popstate 导航时才可用（点击浏览器的后退/前进按钮，或者调用 router.go() 方法）。

滚动到固定距离

该函数可以返回一个 ScrollToOptions 位置对象：

const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    // 始终滚动到顶部
    return { top: 0 }
  },
})

滚动到元素位置

也可以通过 el 传递一个 CSS 选择器或一个 DOM 元素。在这种情况下，top 和 left 将被视为该元素的相对偏移量。

const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    // 始终在元素 #main 上方滚动 10px
    return {
      // 也可以这么写
      // el: document.getElementById('main'),
      el: '#main',
      top: -10,
    }
  },
})

滚动到锚点位置

还可以模拟 “滚动到锚点” ：

const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    if (to.hash) {
      return {
        el: to.hash,
      }
    }
  },
})

滚动到之前的位置

返回 savedPosition，在按下浏览器 后退/前进 按钮，或者调用 router.go() 方法时，页面会回到之前的滚动位置：

const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    if (savedPosition) {
      return savedPosition
    } else {
      return { top: 0 }
    }
  },
})

提示：如果返回一个 falsy 的值，或者是一个空对象，则不会发生滚动。我们还可以在返回的对象中添加 behavior: 'smooth' ，让滚动更加丝滑。

延迟滚动

有时候，我们不希望立即执行滚动行为。例如，当页面做了过渡动效，我们希望过渡结束后再执行滚动。要做到这一点，我们可以返回一个 Promise ：

const router = createRouter({
  scrollBehavior(to, from, savedPosition) {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        resolve({ left: 0, top: 0 })
      }, 500)
    })
  }
})

过渡动效

基本用法

如果想要在路由组件上使用转场，对导航进行动画处理，我可以使用 v-slot 结合 Animete.css 来实现：

<RouterView v-slot="{ Component }">
  <transition enter-active-class="animate__animated animate__fadeIn">
    <component :is="Component" />
  </transition>
</RouterView>

单个路由的过渡

上面的用法会对所有的路由使用相同的过渡。如果你想让每个路由的组件有不同的过渡，可以将 元信息 和动态的 enter-active-class 结合在一起，放在<transition> 上：

const routes = [
  {
    path: '/home',
    component: Home,
    meta: { transition: 'animate__fadeIn' },
  },
  {
    path: '/user',
    component: User,
    meta: { transition: 'animate__bounceIn' },
  },
]

<RouterView v-slot="{ Component }">
  <transition :enter-active-class="`animate__animated ${$route.meta.transition}`">
    <component :is="Component" />
  </transition>
</RouterView>

复用的组件之间进行过渡

const routes = [
  {
    path: '/user/:id',
    component: User,
    meta: { transition: 'animate__bounceIn' },
  },
]

定义以上路由，当从 /user/123 切换到 /user/456 时是没有任何过渡效果的。这时候我们可以添加一个 key 属性来强制进行过渡，key 值只要不同就行了。说白了就是让 Dom 不要被复用，和 v-for 的 key 属性原理刚好相反。

<router-view v-slot="{ Component, route }">
  <transition :enter-active-class="`animate__animated ${$route.meta.transition}`">
    <component :is="Component" :key="route.path" />
  </transition>
</router-view>

动态路由

添加路由

当我们做用户权限的时候，添加路由非常有用。可以使用 router.addRoute() 来添加一个路由：

router.addRoute({ path: '/about', name: 'about', component: About })

注意：跟之前版本不同的是，路由只能一个一个添加，不能批量添加。

删除路由

以下几个方法都可以删除路由：

1、通过使用 router.removeRoute() 按名称删除路由：

router.addRoute({ path: '/about', name: 'about', component: About })
// 删除路由
router.removeRoute('about')

2、通过添加一个名称相同的路由，替换掉之前的路由：

router.addRoute({ path: '/about', name: 'about', component: About })
// 这将会删除之前已经添加的路由，因为他们具有相同的名字且名字必须是唯一的
router.addRoute({ path: '/other', name: 'about', component: Other })

3、通过调用 router.addRoute() 返回的回调函数：

const removeRoute = router.addRoute(routeRecord)
removeRoute() // 删除路由如果存在的话

当路由没有名称时，这种方法非常有用。

添加嵌套路由

要将嵌套路由添加到现有的路由中，可以将路由的 name 作为第一个参数传递给 router.addRoute() ，这和通过 children 添加的效果一样：

router.addRoute({ name: 'admin', path: '/admin', component: Admin })
// 添加嵌套路由
router.addRoute('admin', { path: 'settings', component: AdminSettings })

这相当于：

router.addRoute({
  name: 'admin',
  path: '/admin',
  component: Admin,
  children: [{ path: 'settings', component: AdminSettings }]
})

小结

今天把 Vue-Router4 的主要功能跟大家过了一遍，大部分来自官网，也有一些来自自己的实践心得。希望对你的开发工作有所帮助。当然这并不是 Vue-Router4 的所有内容，比如还有路由匹配、重定向和别名等等，大家可以自行在官网查看。后面我会分享更多 Vue3 相关的干货，欢迎大家关注我，关注我的专栏。

如果今天的分享对你有所帮助，不要忘记点个赞呦🌹

参考文档：Vue Router 官网