入门

用 Vue + Vue Router 创建单页应用非常简单：通过 Vue.js，我们已经用组件组成了我们的应用。当加入 Vue Router 时，我们需要做的就是将我们的组件映射到路由上，让 Vue Router 知道在哪里渲染它们。下面是一个基本的例子：

HTML

<script src="https://unpkg.com/vue@3"></script>
<script src="https://unpkg.com/vue-router@4"></script>

<div id="app">
  <h1>Hello App!</h1>
  <p>
    <!--使用 router-link 组件进行导航 -->
    <!--通过传递 `to` 来指定链接 -->
    <!--`<router-link>` 将呈现一个带有正确 `href` 属性的 `<a>` 标签-->
    <router-link to="/">Go to Home</router-link>
    <router-link to="/about">Go to About</router-link>
  </p>
  <!-- 路由出口 -->
  <!-- 路由匹配到的组件将渲染在这里 -->
  <router-view></router-view>
</div>

router-link

请注意，我们没有使用常规的a 标签，而是使用一个自定义组件router-link 来创建链接。这使得 Vue Router 可以在不重新加载页面的情况下更改 URL，处理 URL 的生成以及编码。我们将在后面看到如何从这些功能中获益。

router-view

router-view 将显示与 url 对应的组件。你可以把它放在任何地方，以适应你的布局。

JavaScript

// 1. 定义路由组件.
// 也可以从其他文件导入
const Home = { template: '<div>Home</div>' }
const About = { template: '<div>About</div>' }

// 2. 定义一些路由
// 每个路由都需要映射到一个组件。
// 我们后面再讨论嵌套路由。
const routes = [
  { path: '/', component: Home },
  { path: '/about', component: About },
]

// 3. 创建路由实例并传递 `routes` 配置
// 你可以在这里输入更多的配置，但我们在这里
// 暂时保持简单
const router = VueRouter.createRouter({
  // 4. 内部提供了 history 模式的实现。为了简单起见，我们在这里使用 hash 模式。
  history: VueRouter.createWebHashHistory(),
  routes, // `routes: routes` 的缩写
})

// 5. 创建并挂载根实例
const app = Vue.createApp({})
//确保 _use_ 路由实例使
//整个应用支持路由。
app.use(router)

app.mount('#app')

// 现在，应用已经启动了！

通过调用app.use(router)，我们可以在任意组件中以this.$router 的形式访问它，并且以this.$route 的形式访问当前路由：

// Home.vue
export default {
  computed: {
    username() {
      // 我们很快就会看到 `params` 是什么
      return this.$route.params.username
    },
  },
  methods: {
    goToDashboard() {
      if (isAuthenticated) {
        this.$router.push('/dashboard')
      } else {
        this.$router.push('/login')
      }
    },
  },
}

要在setup 函数中访问路由，请调用useRouter 或useRoute 函数。我们将在Composition API 中了解更多信息。

在整个文档中，我们会经常使用router 实例，请记住，this.$router 与直接使用通过createRouter 创建的router 实例完全相同。我们使用this.$router 的原因是，我们不想在每个需要操作路由的组件中都导入路由。

带参数的动态路由匹配

很多时候，我们需要将给定匹配模式的路由映射到同一个组件。例如，我们可能有一个User 组件，它应该对所有用户进行渲染，但用户 ID 不同。在 Vue Router 中，我们可以在路径中使用一个动态字段来实现，我们称之为路径参数 ：

const User = {
  template: '<div>User</div>',
}

// 这些都会传递给 `createRouter`
const routes = [
  // 动态字段以冒号开始
  { path: '/users/:id', component: User },
]

现在像/users/johnny 和/users/jolyne 这样的 URL 都会映射到同一个路由。

路径参数 用冒号: 表示。当一个路由被匹配时，它的params 的值将在每个组件中以this.$route.params 的形式暴露出来。因此，我们可以通过更新User 的模板来呈现当前的用户 ID：

const User = {
  template: '<div>User {{ $route.params.id }}</div>',
}

你可以在同一个路由中设置有多个路径参数，它们会映射到$route.params 上的相应字段。例如：

除了$route.params 之外，$route 对象还公开了其他有用的信息，如$route.query（如果 URL 中存在参数）、$route.hash 等。你可以在API 参考中查看完整的细节。

这个例子的 demo 可以在这里找到。

响应路由参数的变化

使用带有参数的路由时需要注意的是，当用户从/users/johnny 导航到/users/jolyne 时，相同的组件实例将被重复使用。因为两个路由都渲染同个组件，比起销毁再创建，复用则显得更加高效。不过，这也意味着组件的生命周期钩子不会被调用。

要对同一个组件中参数的变化做出响应的话，你可以简单地 watch$route 对象上的任意属性，在这个场景中，就是$route.params ：

const User = {
  template: '...',
  created() {
    this.$watch(
      () => this.$route.params,
      (toParams, previousParams) => {
        // 对路由变化做出响应...
      }
    )
  },
}

或者，使用beforeRouteUpdate导航守卫，它也可以取消导航：

const User = {
  template: '...',
  async beforeRouteUpdate(to, from) {
    // 对路由变化做出响应...
    this.userData = await fetchUser(to.params.id)
  },
}

捕获所有路由或 404 Not found 路由

常规参数只匹配 url 片段之间的字符，用/ 分隔。如果我们想匹配任意路径，我们可以使用自定义的路径参数 正则表达式，在路径参数 后面的括号中加入 正则表达式 :

const routes = [
  // 将匹配所有内容并将其放在 `$route.params.pathMatch` 下
  { path: '/:pathMatch(.*)*', name: 'NotFound', component: NotFound },
  // 将匹配以 `/user-` 开头的所有内容，并将其放在 `$route.params.afterUser` 下
  { path: '/user-:afterUser(.*)', component: UserGeneric },
]

在这个特定的场景中，我们在括号之间使用了自定义正则表达式，并将pathMatch 参数标记为可选可重复。这样做是为了让我们在需要的时候，可以通过将path 拆分成一个数组，直接导航到路由：

this.$router.push({
  name: 'NotFound',
  params: { pathMatch: this.$route.path.split('/') },
})

更多内容请参见重复参数部分。

如果你正在使用历史模式，请务必按照说明正确配置你的服务器。

高级匹配模式

Vue Router 使用自己的路径匹配语法，其灵感来自于express，因此它支持许多高级匹配模式，如可选的参数，零或多个 / 一个或多个，甚至自定义的正则匹配规则。请查看高级匹配文档来探索它们。

路由的匹配语法

大多数应用都会使用/about 这样的静态路由和/users/:userId 这样的动态路由，就像我们刚才在动态路由匹配中看到的那样，但是 Vue Router 可以提供更多的方式！

TIP

为了简单起见，所有的路由都省略了component 属性，只关注path 值。

在参数中自定义正则

当定义像:userId 这样的参数时，我们内部使用以下的正则([^/]+) (至少有一个字符不是斜杠/ )来从 URL 中提取参数。这很好用，除非你需要根据参数的内容来区分两个路由。想象一下，两个路由/:orderId 和/:productName，两者会匹配完全相同的 URL，所以我们需要一种方法来区分它们。最简单的方法就是在路径中添加一个静态部分来区分它们：

const routes = [
  // 匹配 /o/3549
  { path: '/o/:orderId' },
  // 匹配 /p/books
  { path: '/p/:productName' },
]

但在某些情况下，我们并不想添加静态的/o/p 部分。由于，orderId 总是一个数字，而productName 可以是任何东西，所以我们可以在括号中为参数指定一个自定义的正则：

const routes = [
  // /:orderId -> 仅匹配数字
  { path: '/:orderId(\\d+)' },
  // /:productName -> 匹配其他任何内容
  { path: '/:productName' },
]

现在，转到/25 将匹配/:orderId，其他情况将会匹配/:productName。routes 数组的顺序并不重要!

TIP

确保转义反斜杠(\ )，就像我们对\d (变成\\d)所做的那样，在 JavaScript 中实际传递字符串中的反斜杠字符。

可重复的参数

如果你需要匹配具有多个部分的路由，如/first/second/third，你应该用*（0 个或多个）和+（1 个或多个）将参数标记为可重复：

const routes = [
  // /:chapters ->  匹配 /one, /one/two, /one/two/three, 等
  { path: '/:chapters+' },
  // /:chapters -> 匹配 /, /one, /one/two, /one/two/three, 等
  { path: '/:chapters*' },
]

这将为你提供一个参数数组，而不是一个字符串，并且在使用命名路由时也需要你传递一个数组：

// 给定 { path: '/:chapters*', name: 'chapters' },
router.resolve({ name: 'chapters', params: { chapters: [] } }).href
// 产生 /
router.resolve({ name: 'chapters', params: { chapters: ['a', 'b'] } }).href
// 产生 /a/b

// 给定 { path: '/:chapters+', name: 'chapters' },
router.resolve({ name: 'chapters', params: { chapters: [] } }).href
// 抛出错误，因为 `chapters` 为空

这些也可以通过在右括号后添加它们与自定义正则结合使用：

const routes = [
  // 仅匹配数字
  // 匹配 /1, /1/2, 等
  { path: '/:chapters(\\d+)+' },
  // 匹配 /, /1, /1/2, 等
  { path: '/:chapters(\\d+)*' },
]

可选参数

你也可以通过使用? 修饰符(0 个或 1 个)将一个参数标记为可选：

const routes = [
  // 匹配 /users 和 /users/posva
  { path: '/users/:userId?' },
  // 匹配 /users 和 /users/42
  { path: '/users/:userId(\\d+)?' },
]

请注意，* 在技术上也标志着一个参数是可选的，但? 参数不能重复。

调试

如果你需要探究你的路由是如何转化为正则的，以了解为什么一个路由没有被匹配，或者，报告一个 bug，你可以使用路径排名工具。它支持通过 URL 分享你的路由。

嵌套路由

一些应用程序的 UI 由多层嵌套的组件组成。在这种情况下，URL 的片段通常对应于特定的嵌套组件结构，例如：

/user/johnny/profile                     /user/johnny/posts
+------------------+                  +-----------------+
| User             |                  | User            |
| +--------------+ |                  | +-------------+ |
| | Profile      | |  +------------>  | | Posts       | |
| |              | |                  | |             | |
| +--------------+ |                  | +-------------+ |
+------------------+                  +-----------------+

通过 Vue Router，你可以使用嵌套路由配置来表达这种关系。

接着上节创建的 app ：

<div id="app">
  <router-view></router-view>
</div>

const User = {
  template: '<div>User {{ $route.params.id }}</div>',
}

// 这些都会传递给 `createRouter`
const routes = [{ path: '/user/:id', component: User }]

这里的<router-view> 是一个顶层的router-view。它渲染顶层路由匹配的组件。同样地，一个被渲染的组件也可以包含自己嵌套的<router-view>。例如，如果我们在User 组件的模板内添加一个<router-view>：

const User = {
  template: `
    <div class="user">
      <h2>User {{ $route.params.id }}</h2>
      <router-view></router-view>
    </div>
  `,
}

要将组件渲染到这个嵌套的router-view 中，我们需要在路由中配置children：

const routes = [
  {
    path: '/user/:id',
    component: User,
    children: [
      {
        // 当 /user/:id/profile 匹配成功
        // UserProfile 将被渲染到 User 的 <router-view> 内部
        path: 'profile',
        component: UserProfile,
      },
      {
        // 当 /user/:id/posts 匹配成功
        // UserPosts 将被渲染到 User 的 <router-view> 内部
        path: 'posts',
        component: UserPosts,
      },
    ],
  },
]

注意，以/ 开头的嵌套路径将被视为根路径。这允许你利用组件嵌套，而不必使用嵌套的 URL。

如你所见，children 配置只是另一个路由数组，就像routes 本身一样。因此，你可以根据自己的需要，不断地嵌套视图。

此时，按照上面的配置，当你访问/user/eduardo 时，在User 的router-view 里面什么都不会呈现，因为没有匹配到嵌套路由。也许你确实想在那里渲染一些东西。在这种情况下，你可以提供一个空的嵌套路径：

const routes = [
  {
    path: '/user/:id',
    component: User,
    children: [
      // 当 /user/:id 匹配成功
      // UserHome 将被渲染到 User 的 <router-view> 内部
      { path: '', component: UserHome },

      // ...其他子路由
    ],
  },
]

这个例子的 demo 可以在这里找到。