Vue Router的API参考

一时失言乱红尘 2022-01-20 02:07 195阅读 0赞

### <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` 属性都不需要写 (基路径) 了。

### 将激活calss应用在外层元素 ###

有时候我们要让激活class应用在外层元素，而不是<a> 标签本身，那么可以用 <router-link> 渲染外层元素，包裹着内层的原生 <a> 标签：

<router-link tag="li" to="/foo">
      <a>/foo</a>
    </router-link>

在这种情况下，`<a>` 将作为真实的链接 (它会获得正确的 `href` 的)，而 "激活时的 CSS 类名" 则设置到外层的 `<li>`。

### <router-link> Props ###

--------------------

**to**

*  类型： string | Location
 *  required

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

<router-link to="home">Home</router-link>
    
    <a href="home">Home</a>
    
    
    <router-link v-bind:to="'home'">Home</router-link>
    
    
    <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>
    
    
    <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

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

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

<router-link to="/" exact>

**event**

*  类型：string | Array<string>
 *  默认值： 'click'

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

**exact-active-class**

*  类型：string
 *  默认值："router-link-exact-active"

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

### <router-view> ###

--------------------

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

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

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

### <router-view> Props ###

**name**

*  类型：string
 *  默认值： "default"

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

### Router 构建选项 ###

**routes**

*  类型：Array<RouteConfig>

RouteConfig的类型定义：

declare type 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"

配置路由模式：

1.  hash：使用URL hash值来做路由。支持所有浏览器，包括不支持HTML5 History Api的浏览器。
2.  history：依赖HTML5 History API和服务器配置。查看 [HTML5 History 模式][HTML5 History]。
3.  abstract：支持所有Javascript运行环境，如Node.js服务器端。**如果发现没有浏览器的API，路由会自动强制进入这个模式。**

**base**

*  类型：String
 *  默认值： "/"

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

**linkActiveClass**

*  类型：string
 *  默认值： "router-link-exact-active"

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

**scrollBehavior**

*  类型：Function

签名：

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

更多详情参考[滚动行为][Link 1]

**parseQuery / stringifyQuery**

*  类型：boolean

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

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

### Router 实例属性 ###

**router.app**

*  类型：Vue instance

配置了router 的Vue根实例

**router.mode**

*  类型：string

路由使用的[模式][Link 2]

**router.currentRoute**

*  类型：Route

当前路由对应的[路由信息对象][Link 3]

### Router 实例方法 ###

--------------------

**router.beforeEach**

**router.beforeResolve**

**router.afterEach**

函数签名：

router.beforeEach((to, from, next) => {
      /* must call `next` */
    })
    
    router.beforeResolve((to, from, next) => {
      /* must call `next` */
    })
    
    router.afterEach((to, from) => {})

增加全局的导航守卫。参考[导航守卫][Link 4]

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

**router.push**

**router.replace**

**router.go**

**router.back**

**router.forward**

函数签名：

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

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

**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.addRoutes(routes: Array<RouteConfig>)

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

**router.onReady**

函数签名：

router.onReady(callback, [errorCallback])

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

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

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

**router.onError**

函数签名：

router.onError(callback)

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

*  错误在一个路由守卫函数中被同步抛出；
 *  错误在一个路由守卫函数中通过 next(err)的方式异步捕获并处理；
 *  渲染一个路由的过程中，需要尝试解析一个异步组件时发生错误。

### 路由对象 ###

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

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

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

*  在组件内，即 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**

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

*  **$route.redirectedFrom**

如果存在重定向，即为重定向来源的路由的名字。

### 组建注入 ###

--------------------

**注入的属性**

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

*  **this.$router**

router实例

*  **this.$route**

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

**增加的组件配置选项**

*  beforeRouteEnter
 *  beforeRouteUpdate
 *  beforeRouteLeave

[HTML5 History]: https://router.vuejs.org/zh/guide/essentials/history-mode.html
[router-link]: https://router.vuejs.org/zh/api/#router-link
[Link 1]: https://router.vuejs.org/zh/guide/advanced/scroll-behavior.html
[Link 2]: https://router.vuejs.org/zh/api/#mode
[Link 3]: https://router.vuejs.org/zh/api/#%E8%B7%AF%E7%94%B1%E5%AF%B9%E8%B1%A1
[Link 4]: https://router.vuejs.org/zh/guide/advanced/navigation-guards.html
[Link 5]: https://router.vuejs.org/zh/guide/essentials/navigation.html
[Link 6]: https://router.vuejs.org/zh/guide/essentials/named-routes.html