Skip to content
该翻译已同步到了 的版本,其对应的 commit hash 是 d842b6f

入门

Vue Router 是 Vue 官方的客户端路由解决方案。

客户端路由的作用是在单页应用 (SPA) 中将浏览器的 URL 和用户看到的内容绑定起来。当用户在应用中浏览不同页面时,URL 会随之更新,但页面不需要从服务器重新加载。

Vue Router 基于 Vue 的组件系统构建,你可以通过配置路由来告诉 Vue Router 为每个 URL 路径显示哪些组件。

学习基础

这份指南假设你已经对 Vue 有了一定的了解。你不必是 Vue 的专家,但你也许偶尔需要查看 Vue 的文档来了解某些特性。

示例

为了引入一些核心概念,我们将使用如下的示例:

让我们首先来看根组件, App.vue

App.vue

vue
<template>
  <h1>Hello App!</h1>
  <p>
    <strong>Current route path:</strong> {{ $route.fullPath }}
  </p>
  <nav>
    <RouterLink to="/">Go to Home</RouterLink>
    <RouterLink to="/about">Go to About</RouterLink>
  </nav>
  <main>
    <RouterView />
  </main>
</template>

在这个 template 中使用了两个由 Vue Router 提供的组件: RouterLinkRouterView

不同于常规的 <a> 标签,我们使用组件 RouterLink 来创建链接。这使得 Vue Router 能够在不重新加载页面的情况下改变 URL,处理 URL 的生成、编码和其他功能。我们将会在之后的部分深入了解 RouterLink 组件。

RouterView 组件可以使 Vue Router 知道你想要在哪里渲染当前 URL 路径对应的路由组件。它不一定要在 App.vue 中,你可以把它放在任何地方,但它需要在某处被导入,否则 Vue Router 就不会渲染任何东西。

上述示例还使用了 {{ $route.fullPath }} 。你可以在组件模板中使用 $route 来访问当前的路由对象。

Vue Mastery Logo Get the Vue Router Cheat Sheet from Vue Mastery

创建路由器实例

路由器实例是通过调用 createRouter() 函数创建的:

js
import { createMemoryHistory, createRouter } from 'vue-router'

import HomeView from './HomeView.vue'
import AboutView from './AboutView.vue'

const routes = [
  { path: '/', component: HomeView },
  { path: '/about', component: AboutView },
]

const router = createRouter({
  history: createMemoryHistory(),
  routes,
})

这里的 routes 选项定义了一组路由,把 URL 路径映射到组件。其中,由 component 参数指定的组件就是先前在 App.vue 中被 <RouterView> 渲染的组件。这些路由组件通常被称为视图,但本质上它们只是普通的 Vue 组件。

其他可以设置的路由选项我们会在之后介绍,目前我们只需要 pathcomponent

这里的 history 选项控制了路由和 URL 路径是如何双向映射的。在演练场的示例里,我们使用了 createMemoryHistory(),它会完全忽略浏览器的 URL 而使用其自己内部的 URL。 这在演练场中可以正常工作,但是未必是你想要在实际应用中使用的。通常,你应该使用 createWebHistory()createWebHashHistory()。我们将在不同的历史记录模式的部分详细介绍这个主题。

注册路由器插件

一旦创建了我们的路由器实例,我们就需要将其注册为插件,这一步骤可以通过调用 use() 来完成。

js
createApp(App)
  .use(router)
  .mount('#app')

或等价地:

js
const app = createApp(App)
app.use(router)
app.mount('#app')

和大多数的 Vue 插件一样,use() 需要在 mount() 之前调用。

如果你好奇这个插件做了什么,它的职责包括:

  1. 全局注册 RouterViewRouterLink 组件。
  2. 添加全局 $router$route 属性。
  3. 启用 useRouter()useRoute() 组合式函数。
  4. 触发路由器解析初始路由。

访问路由器和当前路由

你很可能想要在应用的其他地方访问路由器。

如果你是从 ES 模块导出路由器实例的,你可以将路由器实例直接导入到你需要它的地方。在一些情况下这是最好的方法,但如果我们在组件内部,那么我们还有其他选择。

在组件模板中,路由器实例将被暴露为 $router。这与同样被暴露的 $route 一样,但注意前者最后有一个额外的 r

如果我们使用选项式 API,我们可以在 JavaScript 中如下访问这两个属性:this.$routerthis.$route。在演练场示例中的 HomeView.vue 组件中,路由器就是这样获取的。

js
export default {
  methods: {
    goToAbout() {
      this.$router.push('/about')
    },
  },
}

这里调用了 push(),这是用于编程式导航的方法。我们会在后面详细了解。

对于组合式 API,我们不能通过 this 访问组件实例,所以 Vue Router 给我们提供了一些组合式函数。演练场示例中的 AboutView.vue 组件使用了这种方法:

vue
<script setup>
import { computed } from 'vue'
import { useRoute, useRouter } from 'vue-router'

const router = useRouter()
const route = useRoute()

const search = computed({
  get() {
    return route.query.search ?? ''
  },
  set(search) {
    router.replace({ query: { search } })
  }
})
</script>

你现在不一定要完全理解这段代码,关键是要知道可以通过 useRouter()useRoute() 来访问路由器实例和当前路由。

下一步

如果你想要在 Vite 中使用完整的示例,你可以使用 create-vue 工具,它提供了在项目加入 Vue Router 的选项:

bash
npm create vue@latest
bash
yarn create vue
bash
pnpm create vue

上述通过 create-vue 创建的示例项目使用了与我们在这里看到的类似的功能,对于探索后续介绍的其他功能而言,也许你会觉得这是一个不错的起点。

本教程的约定

单文件组件

Vue Router 经常在配合打包工具 (如 Vite) 和单文件组件 (即 .vue 文件) 的应用中使用。本教程大多数的示例都是如此,但是 Vue Router 本身并不要求你使用构建工具或单文件组件。

例如,若你要使用 VueVue Router 的使用全局构建版本,这些库将被暴露为全局对象,而不是导入:

js
const { createApp } = Vue
const { createRouter, createWebHistory } = VueRouter

组件 API 风格

Vue Router 可以使用组合式 API 或选项式 API 。在必要时,示例将会同时使用两种风格,组合式 API 示例通常会使用 <script setup>,而不是显式的 setup 函数。

如果你对于这两种风格不熟悉,可以参考 Vue - API 风格

routerroute

在本教程中,我们常常以 router 作为路由器实例提及。即由 createRouter() 返回的对象。在应用中,访问该对象的方式取决于上下文。例如,在组合式 API 中,它可以通过调用 useRouter() 来访问。在选项式 API 中,它可以通过 this.$router 来访问。

类似地,当前路由会以 route 被提及。基于不同 API 风格的组件,它可以通过 useRoute()this.$route 来访问。

组件 RouterViewRouterLink 都是全局注册的,因此它们不需要在组件模板中导入。但你也可以通过局部导入它们,例如 import { RouterLink } from 'vue-router'

在模板中,组件的名字可以是 PascalCase 风格或 kebab-case 风格的。Vue 的模板编译器支持两种格式,因此 <RouterView><router-view> 通常是等效的。此时应该遵循你自己项目中使用的约定。

如果使用 DOM 内模板,那么需要注意:组件名字必须使用 kebab-case 风格且不支持自闭合标签。因此你不能直接写 <RouterView />,而需要使用 <router-view></router-view>

Released under the MIT License.