add vue-router document

Author: dingyiming

src/about/awesome.md

@@ -0,0 +1,119 @@
+---
+title: 数据获取
+type: router
+order: 13
+---
+
+# Data Fetching
+
+Sometimes you need to fetch data from the server when a route is activated. For example, before rendering a user profile, you need to fetch the user's data from the server. We can achieve this in two different ways:
+
+- **Fetching After Navigation**: perform the navigation first, and fetch data in the incoming component's lifecycle hook. Display a loading state while data is being fetched.
+
+- **Fetching Before Navigation**: Fetch data before navigation in the route enter guard, and perform the navigation after data has been fetched.
+
+Technically, both are valid choices - it ultimately depends on the user experience you are aiming for.
+
+## Fetching After Navigation
+
+When using this approach, we navigate and render the incoming component immediately, and fetch data in the component's `created` hook. It gives us the opportunity to display a loading state while the data is being fetched over the network, and we can also handle loading differently for each view.
+
+Let's assume we have a `Post` component that needs to fetch the data for a post based on `$route.params.id`:
+
+``` html
+<template>
+  <div class="post">
+    <div class="loading" v-if="loading">
+      Loading...
+    </div>
+
+    <div v-if="error" class="error">
+      {{ error }}
+    </div>
+
+    <div v-if="post" class="content">
+      <h2>{{ post.title }}</h2>
+      <p>{{ post.body }}</p>
+    </div>
+  </div>
+</template>
+```
+
+``` js
+export default {
+  data () {
+    return {
+      loading: false,
+      post: null,
+      error: null
+    }
+  },
+  created () {
+    // fetch the data when the view is created and the data is
+    // already being observed
+    this.fetchData()
+  },
+  watch: {
+    // call again the method if the route changes
+    '$route': 'fetchData'
+  },
+  methods: {
+    fetchData () {
+      this.error = this.post = null
+      this.loading = true
+      // replace getPost with your data fetching util / API wrapper
+      getPost(this.$route.params.id, (err, post) => {
+        this.loading = false
+        if (err) {
+          this.error = err.toString()
+        } else {
+          this.post = post
+        }
+      })
+    }
+  }
+}
+```
+
+## Fetching Before Navigation
+
+With this approach we fetch the data before actually navigating to the new
+route. We can perform the data fetching in the `beforeRouteEnter` guard in the incoming component, and only call `next` when the fetch is complete:
+
+``` js
+export default {
+  data () {
+    return {
+      post: null,
+      error: null
+    }
+  },
+  beforeRouteEnter (route, redirect, next) {
+    getPost(route.params.id, (err, post) => {
+      if (err) {
+        // display some global error message
+      } else {
+        next(vm => {
+          vm.post = post
+        })
+      }
+    })
+  },
+  // when route changes when this component is already rendered,
+  // the logic will be slightly different.
+  watch: {
+    $route () {
+      this.post = null
+      getPost(this.$route.params.id, (err, post) => {
+        if (err) {
+          this.error = err.toString()
+        } else {
+          this.post = post
+        }
+      })
+    }
+  }
+}
+```
+
+The user will stay on the current view while the resource is being fetched for the incoming view. It is therefore recommended to display a progress bar or some kind of indicator while the data is being fetched. If the data fetch fails, it's also necessary to display some kind of global warning message.

src/router/advanced/data-fetching.md

@@ -0,0 +1,51 @@
+---
+title: 异步加载
+type: router
+order: 15
+---
+
+# Lazy Loading Routes
+
+When building apps with a bundler, the JavaScript bundle can become quite large and thus affecting page load time. It would be more efficient if we can split each route's components into a separate chunk, and only load them when the route is visited.
+
+Combining Vue's [async component feature](http://vuejs.org/guide/components.html#Async-Components) and Webpack's [code splitting feature](https://webpack.github.io/docs/code-splitting.html), it's trivially easy to
+lazy-load route components.
+
+All we need to do is defining our route components as async components:
+
+``` js
+const Foo = resolve => {
+  // require.ensure is Webpack's special syntax for a code-split point.
+  require.ensure(['./Foo.vue'], () => {
+    resolve(require('./Foo.vue'))
+  })
+}
+```
+
+There's also an alternative code-split syntax using AMD style require, so this can be simplified to:
+
+``` js
+const Foo = resolve => require(['./Foo.vue'], resolve)
+```
+
+Nothing needs to change in the route config, just use `Foo` as usual:
+
+``` js
+const router = new VueRouter({
+  routes: [
+    { path: '/foo', component: Foo }
+  ]
+})
+```
+
+### Grouping Components in the Same Chunk
+
+Sometimes we may want to group all the components nested under the same route into the same async chunk. To achieve that we need to use [named chunks](https://webpack.github.io/docs/code-splitting.html#named-chunks) by providing a chunk name to `require.ensure` as the 3rd argument:
+
+``` js
+const Foo = r => require.ensure([], () => r(require('./Foo.vue')), 'group-foo')
+const Bar = r => require.ensure([], () => r(require('./Bar.vue')), 'group-foo')
+const Baz = r => require.ensure([], () => r(require('./Baz.vue')), 'group-foo')
+```
+
+Webpack will group any async module with the same chunk name into the same async chunk - this also means we don't need to explicitly list dependencies for `require.ensure` anymore (thus passing an empty array).

src/router/advanced/lazy-loading.md

@@ -0,0 +1,57 @@
+---
+title: Route Meta Fields
+type: router
+order: 11
+---
+
+# Route Meta Fields
+
+You can include a `meta` field when defining a route:
+
+``` js
+const router = new VueRouter({
+  routes: [
+    {
+      path: '/foo',
+      component: Foo,
+      children: [
+        {
+          path: 'bar',
+          component: Bar,
+          // a meta field
+          meta: { requiresAuth: true }
+        }
+      ]
+    }
+  ]
+})
+```
+
+So how do we access this `meta` field?
+
+First, each route object in the `routes` configuration is called a **route record**. Route records may be nested. Therefore when a route is matched, it can potentially match more than one route record.
+
+For example, with the above route config, the URL `/foo/bar` will match both the parent route record and the child route record.
+
+All route records matched by a route are exposed on the `$route` object (and also route objects in navigation guards) as the `$route.matched` Array. Therefore, we will need to iterate over `$route.matched` to check for meta fields in route records.
+
+An example use case is checking for a meta field in the global navigation guard:
+
+``` js
+router.beforeEach((route, redirect, next) => {
+  if (route.matched.some(record => record.meta.requiresAuth)) {
+    // this route requires auth, check if logged in
+    // if not, redirect to login page.
+    if (!auth.loggedIn()) {
+      redirect({
+        path: '/login',
+        query: { redirect: route.fullPath }
+      })
+    } else {
+      next()
+    }
+  } else {
+    next()
+  }
+})
+```

src/router/advanced/meta.md

@@ -0,0 +1,95 @@
+---
+title: Navigation Guards
+type: router
+order: 10
+---
+
+# Navigation Guards
+
+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.
+
+### Global Guards
+
+You can register global before guards using `router.beforeEach`:
+
+``` js
+const router = new VueRouter({ ... })
+
+router.beforeEach((route, redirect, next) => {
+  // ...
+})
+```
+
+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.
+
+Every guard function receives three arguments:
+
+- `route: Route`: the target [Route Object](../api/route-object.md) being navigated to.
+
+- `redirect: Function`: calling this function will abort the current navigation and start a new navigation towards the redirect target.
+
+- `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**.
+
+**If neither `redirect` nor `next` is called, the navigation will be cancelled.**
+
+You can also register global after hooks, however unlike guards, these hooks are much simpler and cannot affect the navigation:
+
+``` js
+router.afterEach(route => {
+  // ...
+})
+```
+
+### Per-Route Guard
+
+You can define `beforeEnter` guards directly on a route's configuration object:
+
+``` js
+const router = new VueRouter({
+  routes: [
+    {
+      path: '/foo',
+      component: Foo,
+      beforeEnter: (route, redirect, next) => {
+        // ...
+      }
+    }
+  ]
+})
+```
+
+These guards have the exact same signature as global before guards.
+
+### In-Component Guards
+
+Finally, you can directly define route navigation guards inside route components with `beforeRouteEnter` and `beforeRouteLeave`:
+
+``` js
+const Foo = {
+  template: `...`,
+  beforeRouteEnter (route, redirect, next) => {
+    // called before the route that renders this component is confirmed.
+    // does NOT have access to `this` component instance,
+    // because it has not been created yet when this guard is called!
+  },
+  beforeRouteLeave (route, redirect, next) => {
+    // called when the route that renders this component is about to
+    // be navigated away from.
+    // has access to `this` component instance.
+  }
+}
+```
+
+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.
+
+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:
+
+``` js
+beforeRouteEnter (route, redirect, next) => {
+  next(vm => {
+    // access to component instance via `vm`
+  })
+}
+```
+
+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`.

src/router/advanced/navigation-guards.md

@@ -0,0 +1,67 @@
+---
+title: 滚动
+type: router
+order: 14
+---
+
+# Scroll Behavior
+
+When using client-side routing, we may want to scroll to top when navigating to a new route, or preserve the scrolling position of history entries just like real page reload does. `vue-router` allows you to achieve these and even better, allows you to completely customize the scroll behavior on route navigation.
+
+**Note: this feature only works in HTML5 history mode.**
+
+When creating the router instance, you can provide the `scrollBehavior` function:
+
+``` js
+const router = new VueRouter({
+  routes: [...],
+  scrollBehavior (to, from, savedPosition) {
+    // return desired position
+  }
+})
+```
+
+The `scrollBehavior` function receives the `to` and `from` route objects. The third argument, `savedPosition`, is only available if this is a `popstate` navigation (triggered by the browser's back/forward buttons).
+
+The function can return a scroll position object. The object could be in the form of:
+
+- `{ x: number, y: number }`
+- `{ selector: string }`
+
+If a falsy value or an empty object is returned, no scrolling will happen.
+
+For example:
+
+``` js
+scrollBehavior (to, from, savedPosition) {
+  return { x: 0, y: 0 }
+}
+```
+
+This will simply make the page scroll to top for all route navigations.
+
+Returning the `savedPosition` will result in a native-like behavior when navigating with back/forward buttons:
+
+``` js
+scrollBehavior (to, from, savedPosition) {
+  if (savedPosition) {
+    return savedPosition
+  } else {
+    return { x: 0, y: 0 }
+  }
+}
+```
+
+If you want to simulate the "scroll to anchor" behavior:
+
+``` js
+scrollBehavior (to, from, savedPosition) {
+  if (to.hash) {
+    return {
+      selector: to.hash
+    }
+  }
+}
+```
+
+We can also use [route meta fields](meta.md) to implement fine-grained scroll behavior control. Check out a full example [here](https://github.com/vuejs/vue-router/blob/next/examples/scroll-behavior/app.js).