|
| 1 | +# Navigation Guards |
| 2 | + |
| 3 | +As the name suggests, the navigation guards provided by `vue-router` are primarily used to guard navigations either by redirecting it or canceling it. There are a number of ways to hook into the route navigation process: globally, per-route, or in-component. |
| 4 | + |
| 5 | +### Global Guards |
| 6 | + |
| 7 | +You can register global before guards using `router.beforeEach`: |
| 8 | + |
| 9 | +``` js |
| 10 | +const router = new VueRouter({ ... }) |
| 11 | + |
| 12 | +router.beforeEach((route, redirect, next) => { |
| 13 | + // ... |
| 14 | +}) |
| 15 | +``` |
| 16 | + |
| 17 | +Global before guards are called in creation order, whenever a navigation is triggered. Guards may be resolved asynchronously, and the navigation is considered **pending** before all hooks have been resolved. |
| 18 | + |
| 19 | +Every guard function receives three arguments: |
| 20 | + |
| 21 | +- `route: Route`: the target route object being navigated to. |
| 22 | + |
| 23 | +- `redirect: Function`: calling this function will abort the current navigation and start a new navigation towards the redirect target. |
| 24 | + |
| 25 | +- `next: Function`: resolve this guard and proceed to the next guard in the pipeline. If there are no hooks left, then the navigation is **confirmed**. |
| 26 | + |
| 27 | +**If neither `redirect` nor `next` is called, the navigation will be cancelled.** |
| 28 | + |
| 29 | +You can also register global after hooks, however unlike guards, these hooks are much simpler and cannot affect the navigation: |
| 30 | + |
| 31 | +``` js |
| 32 | +router.afterEach(route => { |
| 33 | + // ... |
| 34 | +}) |
| 35 | +``` |
| 36 | + |
| 37 | +### Per-Route Guard |
| 38 | + |
| 39 | +You can define `beforeEnter` guards directly on a route's configuration object: |
| 40 | + |
| 41 | +``` js |
| 42 | +const router = new VueRouter({ |
| 43 | + routes: [ |
| 44 | + { |
| 45 | + path: '/foo', |
| 46 | + component: Foo, |
| 47 | + beforeEnter: (route, redirect, next) => { |
| 48 | + // ... |
| 49 | + } |
| 50 | + } |
| 51 | + ] |
| 52 | +}) |
| 53 | +``` |
| 54 | + |
| 55 | +These guards have the exact same signature as global before guards. |
| 56 | + |
| 57 | +### In-Component Guards |
| 58 | + |
| 59 | +Finally, you can directly define route navigation guards inside route components with `beforeRouteEnter` and `beforeRouteLeave`: |
| 60 | + |
| 61 | +``` js |
| 62 | +const Foo = { |
| 63 | + template: `...`, |
| 64 | + beforeRouteEnter (route, redirect, next) => { |
| 65 | + // called before the route that renders this component is confirmed. |
| 66 | + // does NOT have access to `this` component instance, |
| 67 | + // because it has not been created yet when this guard is called! |
| 68 | + }, |
| 69 | + beforeRouteLeave (route, redirect, next) => { |
| 70 | + // called when the route that renders this component is about to |
| 71 | + // be navigated away from. |
| 72 | + // has access to `this` component instance. |
| 73 | + } |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +The `beforeRouteEnter` guard does **NOT** have access to `this`, because the guard is called before the navigation is confirmed, thus the new entering component has not even been created yet. |
| 78 | + |
| 79 | +However, you can access the instance by passing a callback to `next`. The callback will be called when the navigation is confirmed, and the component instance will be passed to the callback as the argument: |
| 80 | + |
| 81 | +``` js |
| 82 | +beforeRouteEnter (route, redirect, next) => { |
| 83 | + next(vm => { |
| 84 | + // access to component instance via `vm` |
| 85 | + }) |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +You can directly access `this` inside `beforeRouteLeave`. The leave guard is usually used to prevent the user from accidentally leaving the route with unsaved edits. The navigation can be canceled by simply not calling `next` or `redirect`. |
0 commit comments