version ^3.1.5

1. 两个标签

<router-view></router-view> 占位，在标签处进行渲染路由组件

<router-link></router-link> 组件支持用户在具有路由功能的应用中 (点击) 导航。

常用形式：

# to=“path” 跳转到 /home 路径
<router-link to="/home">Home</router-link>
# 可以单项数据绑定
<router-link :to="{ path:'/home' }">Home</router-link>
# 跳转至路由 name 为 HOME 的路由
<router-link :to="{ name:'HOME' }">Home</router-link>
# tag=“type” 这个元素可以被修饰成 span 标签 tag=“div” 修饰成div标签
<router-link to="/home" tag=“span”>Home</router-link>
# replace 导航后不会留下 history 记录
<router-link :to="{ path: '/abc'}" replace></router-link>

激活路由标签类

设置路由标签高亮

• active-class 设置链接激活时使用的 CSS 类名。

CSS类名：.router-link-active {}

• exact-active-class 配置当链接被精确匹配的时候应该激活的 class。

CSS类名：.router-link-exact-active {}

2. history 模式

当你使用 history 模式时，URL 就像正常的 url，例如 http://yoursite.com/user/id ，也好看！

const router = new VueRouter({
    mode: 'history',
    routes: [...]
})

3. 重定向

重定向是通过 routes 配置来完成

# router / index.js {
    path: '/a',
    redirect: '/b'
} {
    path: '/a',
    redirect: {
        name: 'foo'
    }
} {
    path: '/a',
    redirect: to => {
        // 方法接收 目标路由 作为参数
        // return 重定向的 字符串路径/路径对象
    }
}

注意导航守卫并没有应用在跳转路由上，而仅仅应用在其目标上。在下面这个例子中，为 /a 路由添加一个 beforeEach 或 beforeLeave 守卫并不会有任何效果。

4. 别名

“重定向”的意思是，当用户访问 /a 时，URL 将会被替换成 /b ，然后匹配路由为 /b ，那么“别名”又是什么呢？

** /a 的别名是 /b ，意味着，当用户访问 /b 时，URL 会保持为 /b ，但是路由匹配则为 /a ，就像用户访问 /a 一样。**

上面对应的路由配置为：

const router = new VueRouter({
    routes: [{
        path: '/a',
        component: A,
        alias: '/b'
    }]
})

“别名”的功能让你可以自由地将 UI 结构映射到任意的 URL，而不是受限于配置的嵌套路由结构。

5. 路由监听

在组件中，通过 Watch 进行监听

# components.vue
// 写法一
watch: {
        $route(to, from) {
            console.log(to.path);
        }
    },

    //写法二
    methods: {
        routeChange(to, from) {
            //具体操作
        }
    },
    watch: {
        $route: 'routeChange',
    },

6. 路由匹配

{
    // 会匹配所有路径
    path: '*'
} {
    // 会匹配以 `/user-` 开头的任意路径
    path: '/user-*'
}

// 给出一个路由 { path: '/user-*' }
this.$router.push('/user-admin')
this.$route.params.pathMatch // 'admin'
// 给出一个路由 { path: '*' }
this.$router.push('/non-existing')
this.$route.params.pathMatch // '/non-existing'

7. 参数传递

在组件中使用 $route 会使之与其对应路由形成高度耦合，从而使组件只能在某些特定的 URL 上使用，限制了其灵活性。

使用 props 将组件和路由解耦：

取代与 $route 的耦合

const User = {
    template: '<div>User {{ $route.params.id }}</div>'
}
const router = new VueRouter({
    routes: [{
        path: '/user/:id',
        component: User
    }]
})

通过 props 解耦

const User = {
    props: ['id'],
    template: '<div>User {{ id }}</div>'
}
const router = new VueRouter({
    routes: [{
            path: '/user/:id',
            component: User,
            props: true
        },

        // 对于包含命名视图的路由，你必须分别为每个命名视图添加 `props` 选项：
        {
            path: '/user/:id',
            components: {
                default: User,
                sidebar: Sidebar
            },
            props: {
                default: true,
                sidebar: false
            }
        }
    ]
})

这样你便可以在任何地方使用该组件，使得该组件更易于重用和测试。

布尔模式

如果 props 被设置为 true ， route.params 将会被设置为组件属性。

对象模式

如果 props 是一个对象，它会被按原样设置为组件属性。当 props 是静态的时候有用。

const router = new VueRouter({
    routes: [{
        path: '/promotion/from-newsletter',
        component: Promotion,
        props: {
            newsletterPopup: false
        }
    }]
})

函数模式函数模式

你可以创建一个函数返回 props 。这样你便可以将参数转换成另一种类型，将静态值与基于路由的值结合等等。

const router = new VueRouter({
    routes: [{
        path: '/search',
        component: SearchUser,
        props: (route) => ({
            query: route.query.q
        })
    }]
})

URL /search?q=vue 会将 {query: 'vue'} 作为属性传递给 SearchUser 组件。

请尽可能保持 props 函数为无状态的，因为它只会在路由发生变化时起作用。如果你需要状态来定义 props ，请使用包装组件，这样 Vue 才可以对状态变化做出反应。

8. 命名视图

有时候想同时 (同级) 展示多个视图，而不是嵌套展示，例如创建一个布局，有 sidebar (侧导航) 和 main (主内容) 两个视图，这个时候命名视图就派上用场了。你可以在界面中拥有多个单独命名的视图，而不是只有一个单独的出口。如果 router-view 没有设置名字，那么默认为 default 。

<router-view class="view one"></router-view>
<router-view class="view two" name="a"></router-view>
<router-view class="view three" name="b"></router-view>

一个视图使用一个组件渲染，因此对于同个路由，多个视图就需要多个组件。确保正确使用 components 配置 (带上 s)：

const router = new VueRouter({
    routes: [{
        path: '/',
        components: {
            default: Foo,
            a: Bar,
            b: Baz
        }
    }]
})

嵌套命名视图

我们也有可能使用命名视图创建嵌套视图的复杂布局。这时你也需要命名用到的嵌套 router-view 组件。我们以一个设置面板为例：

/settings/emails                                       /settings/profile
+-----------------------------------+                  +------------------------------+
| UserSettings                      |                  | UserSettings                 |
| +-----+-------------------------+ |                  | +-----+--------------------+ |
| | Nav | UserEmailsSubscriptions | |  +------------>  | | Nav | UserProfile        | |
| |     +-------------------------+ |                  | |     +--------------------+ |
| |     |                         | |                  | |     | UserProfilePreview | |
| +-----+-------------------------+ |                  | +-----+--------------------+ |
+-----------------------------------+                  +------------------------------+

• Nav 只是一个常规组件。
• UserSettings 是一个视图组件。
• UserEmailsSubscriptions、UserProfile、UserProfilePreview 是嵌套的视图组件。

注意：我们先忘记 HTML/CSS 具体的布局的样子，只专注在用到的组件上。

UserSettings 组件的 ` 部分应该是类似下面的这段代码：

<!-- UserSettings.vue -->
<div>
    <h1>User Settings</h1>
    <NavBar />
    <router-view />
    <router-view name="helper" />
</div>

嵌套的视图组件在此已经被忽略了，但是你可以在这里找到完整的源代码。

然后你可以用这个路由配置完成该布局：

{
    path: '/settings',
    // 你也可以在顶级路由就配置命名视图
    component: UserSettings,
    children: [{
        path: 'emails',
        component: UserEmailsSubscriptions
    }, {
        path: 'profile',
        components: {
            default: UserProfile,
            helper: UserProfilePreview
        }
    }]
}

9. 高级匹配模式

// 命名参数必须有"单个字符"[A-Za-z09]组成

// ?可选参数
{
    path: '/optional-params/:foo?'
}
// 路由跳转是可以设置或者不设置foo参数，可选
<
router - link to = "/optional-params" > /optional-params</router - link >
    <
    router - link to = "/optional-params/foo" > /optional-params/foo < /router-link>

// 零个或多个参数
{
    path: '/optional-params/*'
} <
router - link to = "/number" > 没有参数 < /router-link> <
router - link to = "/number/foo000" > 一个参数 < /router-link> <
router - link to = "/number/foo111/fff222" > 多个参数 < /router-link>

// 一个或多个参数
{
    path: '/optional-params/:foo+'
} <
router - link to = "/number/foo" > 一个参数 < /router-link> <
router - link to = "/number/foo/foo111/fff222" > 多个参数 < /router-link>

// 自定义匹配参数
// 可以为所有参数提供一个自定义的regexp，它将覆盖默认值（[^\/]+）
{
    path: '/optional-params/:id(\\d+)'
} {
    path: '/optional-params/(foo/)?bar'
}

10. push和replace的第二个第三个参数

在 2.2.0+，可选的在 router.push 或 router.replace 中提供 onComplete 和 onAbort 回调作为第二个和第三个参数。这些回调将会在导航成功完成 (在所有的异步钩子被解析之后) 或终止 (导航到相同的路由、或在当前导航完成之前导航到另一个不同的路由) 的时候进行相应的调用。在 3.1.0+，可以省略第二个和第三个参数，此时如果支持 Promise，router.push 或 router.replace 将返回一个 Promise。

// 组件1跳转组件2

// 组件1
this.$router.push({
    name: 'number'
}, () => {
    console.log('组件1：onComplete回调');
}, () => {
    console.log('组件1：onAbort回调');
});
// 组件2
beforeRouteEnter(to, from, next) {
        console.log('组件2：beforeRouteEnter');
        next();
    },
    beforeCreate() {
        console.log('组件2：beforeCreate');
    },
    created() {
        console.log('组件2：created');
    }

// 组件2：beforeCreate
// 组件1：onComplete回调
// 组件2：beforeCreate
// 组件2：created

同一组件内跳转

不带参数

// 组件2跳转组件2（不带参数）
this.$router.push({
    name: 'number'
}, () => {
    console.log('组件2：onComplete回调');
}, () => {
    console.log('组件2,自我跳转：onAbort回调');
});

//组件2,自我跳转：onAbort回调

带参数

// 组件2跳转组件2（带参数）

this.$router.push({
    name: 'number',
    params: {
        foo: this.number
    }
}, () => {
    console.log('组件2：onComplete回调');
}, () => {
    console.log('组件2,自我跳转：onAbort回调');
});

// 组件2：beforeRouteEnter

11. 路由守卫

11.1 全局守卫

• router.beforeEach 全局前置守卫 进入路由之前。
• router.beforeResolve 全局解析守卫2.5.0新增。在beforeRouteEnter调用之后调用。
• router.afterEach 全局后置钩子 进入路由之后。

// 入口文件
import router from './router'

// 全局前置守卫
router.beforeEach((to, from, next) => {
    console.log('beforeEach 全局前置守卫');
    next();
});
// 全局解析守卫
router.beforeResolve((to, from, next) => {
    console.log('beforeResolve 全局解析守卫');
    next();
});
// 全局后置守卫
router.afterEach((to, from) => {
    console.log('afterEach 全局后置守卫');
});

11.2 路由独享守卫

1. beforeEnter全局前置守卫 进入路由之前。

{
    path: '/number/:name',
    props: true,
    name: 'number',
    // 路由独享守卫
    beforeEnter: (to, from, next) => {
        console.log('beforeEnter 路由独享守卫');
        next();
    },
    component: () => import( /* webpackChunkName: "number" */ './views/Number.vue')
}

11.3 组件内守卫

• beforeRouteEnter
• beforeRouteUpdate(2.2新增)
• beforeRouteLeave

beforeRouteEnter(to, from, next) {
    // 在渲染该组件的对应路由被 confirm 前调用
    // 不！能！获取组件实例 `this`
    // 因为当守卫执行前，组件实例还没被创建
    console.log('beforeRouteEnter 组件内进入守卫');
    next();
},
beforeRouteUpdate(to, from, next) {
    // 在当前路由改变，但是该组件被复用时调用
    // 举例来说，对于一个带有动态参数的路径 /foo/:id，在 /foo/1 和 /foo/2 之间跳转的时候，
    // 由于会渲染同样的 Foo 组件，因此组件实例会被复用。而这个钩子就会在这个情况下被调用。
    // 可以访问组件实例 `this`
    console.log('beforeRouteUpdate 组件内更新守卫');
    next();
},
beforeRouteLeave(to, from, next) {
    // 导航离开该组件的对应路由时调用
    // 可以访问组件实例 `this`
    console.log('beforeRouteLeave 组件内离开守卫');
    next();
}

11.4 完整的导航解析流程

1. 导航被触发。
2. 在失活的组件里调用离开守卫。
3. 调用全局的 beforeEach 守卫。
4. 在重用的组件里调用 beforeRouteUpdate 守卫 (2.2+)。
5. 在路由配置里调用 beforeEnter。
6. 解析异步路由组件。
7. 在被激活的组件里调用 beforeRouteEnter。
8. 调用全局的 beforeResolve 守卫 (2.5+)。
9. 导航被确认。
10. 调用全局的 afterEach 钩子。
11. 触发 DOM 更新。
12. 用创建好的实例调用 beforeRouteEnter 守卫中传给 next 的回调函数。

11.5 守卫的next方法

next: Function: 一定要调用该方法来 resolve 这个钩子。执行效果依赖 next 方法的调用参数。

• next(): 进行管道中的下一个钩子。如果全部钩子执行完了，则导航的状态就是 confirmed (确认的)。
• next(false): 中断当前的导航。如果浏览器的 URL 改变了 (可能是用户手动或者浏览器后退按钮)，那么 URL 地址会重置到 from 路由对应的地址。
• next('/') 或者 next({ path: '/' }): 跳转到一个不同的地址。当前的导航被中断，然后进行一个新的导航。你可以向 next 传递任意位置对象，且允许设置诸如 replace: true、name: 'home' 之类的选项以及任何用在 router-link 的 to prop 或 router.push 中的选项。
• next(error): (2.4.0+) 如果传入 next 的参数是一个 Error 实例，则导航会被终止且该错误会被传递给 router.onError() 注册过的回调。

12. 滚动行为

官方文档：滚动行为 | Vue Router

使用前端路由，当切换到新路由时，想要页面滚到顶部，或者是保持原先的滚动位置，就像重新加载页面那样。 vue-router 能做到，而且更好，它让你可以自定义路由切换时页面如何滚动。

注意: 这个功能只在支持 history.pushState 的浏览器中可用。

// 一般滚动
scrollBehavior(to, from, savedPosition) {
    if (savedPosition) {
        // 在浏览器按下 后退/前进按钮时
        return savedPosition
    } else {
        return { x: 0, y: 0 }
    }
}

// 锚点滚动
scrollBehavior(to, from, savedPosition) {
    if (to.hash) {
        return {
            selector: to.hash
        }
    }
}

// 异步滚动  2.8.0 新增
scrollBehavior(to, from, savedPosition) {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            resolve({ x: 0, y: 0 })
        }, 500)
    })
}

13. 路由元信息

定义路由的时候可以配置 meta 字段：

const router = new VueRouter({
    routes: [{
        path: '/foo',
        component: Foo,
        children: [{
            path: 'bar',
            component: Bar,
            // a meta field
            meta: {
                requiresAuth: true
            }
        }]
    }]
})

那么如何访问这个 meta 字段呢？

首先，我们称呼 routes 配置中的每个路由对象为 路由记录。路由记录可以是嵌套的，因此，当一个路由匹配成功后，他可能匹配多个路由记录

例如，根据上面的路由配置， /foo/bar 这个 URL 将会匹配父路由记录以及子路由记录。

一个路由匹配到的所有路由记录会暴露为 $route 对象 (还有在导航守卫中的路由对象) 的 $route.matched 数组。因此，我们需要遍历 $route.matched 来检查路由记录中的 meta 字段。

下面例子展示在全局导航守卫中检查元字段：

router.beforeEach((to, from, next) => {
    if (to.matched.some(record => record.meta.requiresAuth)) {
        // this route requires auth, check if logged in
        // if not, redirect to login page.
        if (!auth.loggedIn()) {
            next({
                path: '/login',
                query: {
                    redirect: to.fullPath
                }
            })
        } else {
            next()
        }
    } else {
        next() // 确保一定要调用 next()
    }
})

14. 编程式的导航

除了使用 <router-link> 创建 a 标签来定义导航链接，我们还可以借助 router 的实例方法，通过编写代码来实现。

14.1 router.push(location, onComplete?, onAbort?)

// 路由跳转

// 在 Vue 实例内部，你可以通过 $router 访问路由实例。因此你可以调用this.$router.push
this.$router.push(location, onComplete ? , onAbort ? )

想要导航到不同的 URL，则使用 router.push 方法。这个方法会向 history 栈添加一个新的记录，所以，当用户点击浏览器后退按钮时，则回到之前的 URL。

该方法的参数可以是一个字符串路径，或者一个描述地址的对象。例如：

// 字符串
router.push('home')

// 对象
router.push({
    path: 'home'
})

// 命名的路由
router.push({
    name: 'user',
    params: {
        userId: '123'
    }
})

// 带查询参数，变成 /register?plan=private
router.push({
    path: 'register',
    query: {
        plan: 'private'
    }
})

注意：如果提供了 path ， params 会被忽略，上述例子中的 query 并不属于这种情况。取而代之的是下面例子的做法，你需要提供路由的 name 或手写完整的带有参数的 path ：

const userId = '123'
router.push({
    name: 'user',
    params: {
        userId
    }
}) // -> /user/123
router.push({
    path: `/user/${userId}`
}) // -> /user/123
// 这里的 params 不生效
router.push({
    path: '/user',
    params: {
        userId
    }
}) // -> /user

同样的规则也适用于 router-link 组件的 to 属性。

在 2.2.0+，可选的在 router.push 或 router.replace 中提供 onComplete 和 onAbort 回调作为第二个和第三个参数。这些回调将会在导航成功完成 (在所有的异步钩子被解析之后) 或终止 (导航到相同的路由、或在当前导航完成之前导航到另一个不同的路由) 的时候进行相应的调用。在 3.1.0+，可以省略第二个和第三个参数，此时如果支持 Promise， router.push 或 router.replace 将返回一个 Promise。

注意： 如果目的地和当前路由相同，只有参数发生了改变 (比如从一个用户资料到另一个 /users/1 -> /users/2 )，你需要使用 beforeRouteUpdate 来响应这个变化 (比如抓取用户信息)。

14.2 router.replace(location, onComplete?, onAbort?)

跟 router.push 很像，唯一的不同就是，它不会向 history 添加新记录，而是跟它的方法名一样 —— 替换掉当前的 history 记录

14.3 router.go(n)

这个方法的参数是一个整数，意思是在 history 记录中向前或者后退多少步，类似 window.history.go(n) 。

例子

// 在浏览器记录中前进一步，等同于 history.forward()
router.go(1)

// 后退一步记录，等同于 history.back()
router.go(-1)

// 前进 3 步记录
router.go(3)

// 如果 history 记录不够用，那就默默地失败呗
router.go(-100)
router.go(100)

Vue Router 的导航方法 ( push 、 replace 、 go ) 在各类路由模式 ( history 、 hash 和 abstract ) 下表现一致。

15. 路由懒加载

当打包构建应用时，JavaScript 包会变得非常大，影响页面加载。如果我们能把不同路由对应的组件分割成不同的代码块，然后当路由被访问的时候才加载对应组件，这样就更加高效了。

结合 Vue 的异步组件和 Webpack 的代码分割功能，轻松实现路由组件的懒加载。

首先，可以将异步组件定义为返回一个 Promise 的工厂函数 (该函数返回的 Promise 应该 resolve 组件本身)：

const Foo = () => Promise.resolve({
    /* 组件定义对象 */
})

第二，在 Webpack 2 中，我们可以使用动态 import语法来定义代码分块点 (split point)：

import('./Foo.vue') // 返回 Promise

注意

如果您使用的是 Babel，你将需要添加 syntax-dynamic-import 插件，才能使 Babel 可以正确地解析语法。

结合这两者，这就是如何定义一个能够被 Webpack 自动代码分割的异步组件。

const Foo = () => import('./Foo.vue')

在路由配置中什么都不需要改变，只需要像往常一样使用 Foo：

const router = new VueRouter({
    routes: [{
        path: '/foo',
        component: Foo
    }]
})

把组件按组分块

有时候我们想把某个路由下的所有组件都打包在同个异步块 (chunk) 中。只需要使用 命名 chunk，一个特殊的注释语法来提供 chunk name (需要 Webpack > 2.4)。

const Foo = () => import( /* webpackChunkName: "group-foo" */ './Foo.vue')
const Bar = () => import( /* webpackChunkName: "group-foo" */ './Bar.vue')
const Baz = () => import( /* webpackChunkName: "group-foo" */ './Baz.vue')

Webpack 会将任何一个异步模块与相同的块名称组合到相同的异步块中。