API 参考

<router-link>

<router-link> 组件支持用户在具有路由功能的应用中 (点击) 导航。 通过 to 属性指定目标地址，默认渲染成带有正确链接的 <a> 标签，可以通过配置 tag 属性生成别的标签.。另外，当目标路由成功激活时，链接元素自动设置一个表示激活的 CSS 类名。

<router-link> 比起写死的 <a href="..."> 会好一些，理由如下：

• 无论是 HTML5 history 模式还是 hash 模式，它的表现行为一致，所以，当你要切换路由模式，或者在 IE9 降级使用 hash 模式，无须作任何变动。
• 在 HTML5 history 模式下，router-link 会守卫点击事件，让浏览器不再重新加载页面。
• 当你在 HTML5 history 模式下使用 base 选项之后，所有的 to 属性都不需要写 (基路径) 了。

v-slot API (3.1.0 新增)

router-link 通过一个作用域插槽 (opens new window)暴露底层的定制能力。这是一个更高阶的 API，主要面向库作者，但也可以为开发者提供便利，多数情况用在一个类似 NavLink 这样的自定义组件里。

在使用 v-slot API 时，需要向 router-link 传入一个单独的子元素。否则 router-link 将会把子元素包裹在一个 span 元素内。

<router-link
  to="/about"
  custom
  v-slot="{ href, route, navigate, isActive, isExactActive }"
>
  <NavLink :active="isActive" :href="href" @click="navigate"
    >{{ route.fullPath }}</NavLink
  >
</router-link>

• href：解析后的 URL。将会作为一个 a 元素的 href attribute。
• route：解析后的规范化的地址。
• navigate：触发导航的函数。会在必要时自动阻止事件，和 router-link 同理。
• isActive：如果需要应用激活的 class 则为 true。允许应用一个任意的 class。
• isExactActive：如果需要应用精确激活的 class 则为 true。允许应用一个任意的 class。

示例：将激活的 class 应用在外层元素

有的时候我们可能想把激活的 class 应用到一个外部元素而不是 <a> 标签本身，这时你可以在一个 router-link 中包裹该元素并使用 v-slot property 来创建链接：

<router-link
  to="/foo"
  v-slot="{ href, route, navigate, isActive, isExactActive }"
  custom
>
  <li
    :class="[isActive && 'router-link-active', isExactActive && 'router-link-exact-active']"
  >
    <a :href="href" @click="navigate">{{ route.fullPath }}</a>
  </li>
</router-link>

提示

如果你在 <a> 元素上添加一个 target="_blank"，则 @click="navigate" 处理器会被忽略。

<router-link> Props

to

• 类型: string | Location

• required

  表示目标路由的链接。当被点击后，内部会立刻把 to 的值传到 router.push()，所以这个值可以是一个字符串或者是描述目标位置的对象。

  <!-- 字符串 -->
  <router-link to="home">Home</router-link>
  <!-- 渲染结果 -->
  <a href="home">Home</a>
  
  <!-- 使用 v-bind 的 JS 表达式 -->
  <router-link v-bind:to="'home'">Home</router-link>
  
  <!-- 不写 v-bind 也可以，就像绑定别的属性一样 -->
  <router-link :to="'home'">Home</router-link>
  
  <!-- 同上 -->
  <router-link :to="{ path: 'home' }">Home</router-link>
  
  <!-- 命名的路由 -->
  <router-link :to="{ name: 'user', params: { userId: 123 }}">User</router-link>
  
  <!-- 带查询参数，下面的结果为 /register?plan=private -->
  <router-link :to="{ path: 'register', query: { plan: 'private' }}"
    >Register</router-link
  >
  

replace

• 类型: boolean

• 默认值: false

  设置 replace 属性的话，当点击时，会调用 router.replace() 而不是 router.push()，于是导航后不会留下 history 记录。

  <router-link :to="{ path: '/abc'}" replace></router-link>
  

append

• 类型: boolean

• 默认值: false

  设置 append 属性后，则在当前 (相对) 路径前添加基路径。例如，我们从 /a 导航到一个相对路径 b，如果没有配置 append，则路径为 /b，如果配了，则为 /a/b

  <router-link :to="{ path: 'relative/path'}" append></router-link>
  

tag

• 类型: string

• 默认值: "a"

  有时候想要 <router-link> 渲染成某种标签，例如 <li>。 于是我们使用 tag prop 类指定何种标签，同样它还是会监听点击，触发导航。

  <router-link to="/foo" tag="li">foo</router-link>
  <!-- 渲染结果 -->
  <li>foo</li>
  

active-class

• 类型: string

• 默认值: "router-link-active"

  设置链接激活时使用的 CSS 类名。默认值可以通过路由的构造选项 linkActiveClass 来全局配置。

exact

• 类型: boolean

• 默认值: false

  “是否激活”默认类名的依据是包含匹配。 举个例子，如果当前的路径是 /a 开头的，那么 <router-link to="/a"> 也会被设置 CSS 类名。

  按照这个规则，每个路由都会激活 <router-link to="/">！想要链接使用“精确匹配模式”，则使用 exact 属性：

  <!-- 这个链接只会在地址为 / 的时候被激活 -->
  <router-link to="/" exact></router-link>
  

  查看更多关于激活链接类名的例子可运行 (opens new window)

event

• 类型: string | Array<string>

• 默认值: 'click'

  声明可以用来触发导航的事件。可以是一个字符串或是一个包含字符串的数组。

exact-active-class

• 类型: string

• 默认值: "router-link-exact-active"

  配置当链接被精确匹配的时候应该激活的 class。注意默认值也是可以通过路由构造函数选项 linkExactActiveClass 进行全局配置的。

aria-current-value

• 类型: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'

• 默认值: "page"

  当链接根据精确匹配规则激活时配置的 aria-current 的值。这个值应该是 ARIA 规范中允许的 aria-current 的值 (opens new window)。在绝大多数场景下，默认值 page 应该是最合适的。

<router-view>

<router-view> 组件是一个 functional 组件，渲染路径匹配到的视图组件。<router-view> 渲染的组件还可以内嵌自己的 <router-view>，根据嵌套路径，渲染嵌套组件。

其他属性 (非 router-view 使用的属性) 都直接传给渲染的组件， 很多时候，每个路由的数据都是包含在路由参数中。

因为它也是个组件，所以可以配合 <transition> 和 <keep-alive> 使用。如果两个结合一起用，要确保在内层使用 <keep-alive>：

<transition>
  <keep-alive>
    <router-view></router-view>
  </keep-alive>
</transition>

<router-view> Props

name

• 类型: string

• 默认值: "default"

  如果 <router-view>设置了名称，则会渲染对应的路由配置中 components 下的相应组件。查看 命名视图 中的例子。

Router 构建选项

routes

• 类型: Array<RouteConfig>

  RouteConfig 的类型定义：

  interface RouteConfig = {
    path: string,
    component?: Component,
    name?: string, // 命名路由
    components?: { [name: string]: Component }, // 命名视图组件
    redirect?: string | Location | Function,
    props?: boolean | Object | Function,
    alias?: string | Array<string>,
    children?: Array<RouteConfig>, // 嵌套路由
    beforeEnter?: (to: Route, from: Route, next: Function) => void,
    meta?: any,
  
    // 2.6.0+
    caseSensitive?: boolean, // 匹配规则是否大小写敏感？(默认值：false)
    pathToRegexpOptions?: Object // 编译正则的选项
  }
  

mode

• 类型: string

• 默认值: "hash" (浏览器环境) | "abstract" (Node.js 环境)

• 可选值: "hash" | "history" | "abstract"

  配置路由模式:

  • hash: 使用 URL hash 值来作路由。支持所有浏览器，包括不支持 HTML5 History Api 的浏览器。

  • history: 依赖 HTML5 History API 和服务器配置。查看 HTML5 History 模式。

  • abstract: 支持所有 JavaScript 运行环境，如 Node.js 服务器端。如果发现没有浏览器的 API，路由会自动强制进入这个模式。

base

• 类型: string

• 默认值: "/"

  应用的基路径。例如，如果整个单页应用服务在 /app/ 下，然后 base 就应该设为 "/app/"。

linkActiveClass

• 类型: string

• 默认值: "router-link-active"

  全局配置 <router-link> 默认的激活的 class。参考 router-link。

linkExactActiveClass

• 类型: string

• 默认值: "router-link-exact-active"

  全局配置 <router-link> 默认的精确激活的 class。可同时翻阅 router-link。

scrollBehavior

• 类型: Function

  签名:

  type PositionDescriptor =
    { x: number, y: number } |
    { selector: string } |
    void
  
  type scrollBehaviorHandler = (
    to: Route,
    from: Route,
    savedPosition?: { x: number, y: number }
  ) => PositionDescriptor | Promise<PositionDescriptor>
  

  更多详情参考滚动行为。

parseQuery / stringifyQuery

• 类型: Function

  提供自定义查询字符串的解析/反解析函数。覆盖默认行为。

fallback

• 类型: boolean

• 默认值: true

  当浏览器不支持 history.pushState 控制路由是否应该回退到 hash 模式。默认值为 true。

  在 IE9 中，设置为 false 会使得每个 router-link 导航都触发整页刷新。它可用于工作在 IE9 下的服务端渲染应用，因为一个 hash 模式的 URL 并不支持服务端渲染。

Router 实例属性

router.app

• 类型: Vue instance

  配置了 router 的 Vue 根实例。

router.mode

• 类型: string

  路由使用的模式。

router.currentRoute

• 类型: Route

  当前路由对应的路由信息对象。

router.START_LOCATION

• 类型：Route

  以路由对象的格式展示初始路由地址，即路由开始的地方。可用在导航守卫中以区分初始导航。

  import VueRouter from 'vue-router'
  
  const router = new VueRouter({
    // ...
  })
  
  router.beforeEach((to, from) => {
    if (from === VueRouter.START_LOCATION) {
      // 初始导航
    }
  })
  

Router 实例方法

router.beforeEach

router.beforeResolve

router.afterEach

函数签名：

router.beforeEach((to, from, next) => {
  /* 必须调用 `next` */
})

router.beforeResolve((to, from, next) => {
  /* 必须调用 `next` */
})

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

增加全局的导航守卫。参考导航守卫。

在 2.5.0+ 这三个方法都返回一个移除已注册的守卫/钩子的函数。

router.push

router.replace

router.go

router.back

router.forward

函数签名：

router.push(location, onComplete?, onAbort?)
router.push(location).then(onComplete).catch(onAbort)
router.replace(location, onComplete?, onAbort?)
router.replace(location).then(onComplete).catch(onAbort)
router.go(n)
router.back()
router.forward()

动态的导航到一个新 URL。参考编程式导航。

这些函数仅在安装路由插件并将其传递给 Vue 根实例后调用，如起步所示。

router.getMatchedComponents

函数签名：

const matchedComponents: Array<Component> = router.getMatchedComponents(location?)

返回目标位置或是当前路由匹配的组件数组 (是数组的定义/构造类，不是实例)。通常在服务端渲染的数据预加载时使用。

router.resolve

函数签名：

const resolved: {
  location: Location;
  route: Route;
  href: string;
} = router.resolve(location, current?, append?)

解析目标位置 (格式和 <router-link> 的 to prop 一样)。

• current 是当前默认的路由 (通常你不需要改变它)
• append 允许你在 current 路由上附加路径 (如同 router-link)

router.addRoutes

已废弃：使用 router.addRoute() 代替。

函数签名：

router.addRoutes(routes: Array<RouteConfig>)

动态添加更多的路由规则。参数必须是一个符合 routes 选项要求的数组。

router.addRoute

添加一条新路由规则。如果该路由规则有 name，并且已经存在一个与之相同的名字，则会覆盖它。

函数签名:

addRoute(route: RouteConfig): () => void

router.addRoute

添加一条新的路由规则记录作为现有路由的子路由。如果该路由规则有 name，并且已经存在一个与之相同的名字，则会覆盖它。

函数签名:

addRoute(parentName: string, route: RouteConfig): () => void

router.getRoutes

获取所有活跃的路由记录列表。注意只有文档中记录下来的 property 才被视为公共 API，避免使用任何其它 property，例如 regex，因为它在 Vue Router 4 中不存在。

函数签名:

getRoutes(): RouteRecord[]

router.onReady

函数签名：

router.onReady(callback, [errorCallback])

该方法把一个回调排队，在路由完成初始导航时调用，这意味着它可以解析所有的异步进入钩子和路由初始化相关联的异步组件。

这可以有效确保服务端渲染时服务端和客户端输出的一致。

第二个参数 errorCallback 只在 2.4+ 支持。它会在初始化路由解析运行出错 (比如解析一个异步组件失败) 时被调用。

router.onError

函数签名：

router.onError(callback)

注册一个回调，该回调会在路由导航过程中出错时被调用。注意被调用的错误必须是下列情形中的一种：

• 错误在一个路由守卫函数中被同步抛出；

• 错误在一个路由守卫函数中通过调用 next(err) 的方式异步捕获并处理；

• 渲染一个路由的过程中，需要尝试解析一个异步组件时发生错误。

路由对象

一个路由对象 (route object) 表示当前激活的路由的状态信息，包含了当前 URL 解析得到的信息，还有 URL 匹配到的路由记录 (route records)。

路由对象是不可变 (immutable) 的，每次成功的导航后都会产生一个新的对象。

路由对象出现在多个地方:

• 在组件内，即 this.$route

• 在 $route 观察者回调内

• router.match(location) 的返回值

• 导航守卫的参数：

  router.beforeEach((to, from, next) => {
    // `to` 和 `from` 都是路由对象
  })
  

• scrollBehavior 方法的参数:

  const router = new VueRouter({
    scrollBehavior(to, from, savedPosition) {
      // `to` 和 `from` 都是路由对象
    }
  })
  

路由对象属性

• $route.path

  • 类型: string

    字符串，对应当前路由的路径，总是解析为绝对路径，如 "/foo/bar"。

• $route.params

  • 类型: Object

    一个 key/value 对象，包含了动态片段和全匹配片段，如果没有路由参数，就是一个空对象。

• $route.query

  • 类型: Object

    一个 key/value 对象，表示 URL 查询参数。例如，对于路径 /foo?user=1，则有 $route.query.user == 1，如果没有查询参数，则是个空对象。

• $route.hash

  • 类型: string

    当前路由的 hash 值 (带 #) ，如果没有 hash 值，则为空字符串。

• $route.fullPath

  • 类型: string

    完成解析后的 URL，包含查询参数和 hash 的完整路径。

• $route.matched

  • 类型: Array<RouteRecord>

  一个数组，包含当前路由的所有嵌套路径片段的路由记录 。路由记录就是 routes 配置数组中的对象副本 (还有在 children 数组)。

  const router = new VueRouter({
    routes: [
      // 下面的对象就是路由记录
      {
        path: '/foo',
        component: Foo,
        children: [
          // 这也是个路由记录
          { path: 'bar', component: Bar }
        ]
      }
    ]
  })
  

  当 URL 为 /foo/bar，$route.matched 将会是一个包含从上到下的所有对象 (副本)。

• $route.name

  当前路由的名称，如果有的话。(查看命名路由)

• $route.redirectedFrom

  如果存在重定向，即为重定向来源的路由的名字。(参阅重定向和别名)

组件注入

注入的属性

通过在 Vue 根实例的 router 配置传入 router 实例，下面这些属性成员会被注入到每个子组件。

• this.$router

  router 实例。

• this.$route

  当前激活的路由信息对象。这个属性是只读的，里面的属性是 immutable (不可变) 的，不过你可以 watch (监测变化) 它。

增加的组件配置选项

• beforeRouteEnter

• beforeRouteUpdate

• beforeRouteLeave

  查看组件内的守卫。