docs: api

Author: yyx990803

README.md

@@ -1,4 +1,4 @@
-# vue-router [![Build Status](https://img.shields.io/circleci/project/vuejs/vue-router/master.svg)](https://circleci.com/gh/vuejs/vue-router)
+# vue-router [![Build Status](https://img.shields.io/circleci/project/vuejs/vue-router/master.svg)](https://circleci.com/gh/vuejs/vue-router) [![npm package](https://img.shields.io/npm/v/vue-router.svg)](https://www.npmjs.com/package/vue-router)
 
 **Compatibility Note:** `vue-router` requires Vue.js 0.12.10+
 

docs/SUMMARY.md

@@ -1,4 +1,4 @@
-# vue-router documentation
+# vue-router documentation [![npm package](https://img.shields.io/npm/v/vue-router.svg)](https://www.npmjs.com/package/vue-router)
 
 - [Installation](installation.md)
 - [Basic Usage](basic.md)
@@ -17,12 +17,12 @@
   - [canReuse](pipeline/can-reuse.md)
 - [API Reference](api/README.md)
   - [Router instance properties](api/properties.md)
+  - [router.start](api/start.md)
+  - [router.stop](api/stop.md)
   - [router.map](api/map.md)
   - [router.on](api/on.md)
+  - [router.go](api/go.md)
+  - [router.replace](api/replace.md)
   - [router.redirect](api/redirect.md)
   - [router.alias](api/alias.md)
   - [router.beforeEach](api/before-each.md)
-  - [router.go](api/go.md)
-  - [router.replace](api/replace.md)
-  - [router.start](api/start.md)
-  - [router.stop](api/stop.md)

docs/api/README.md

@@ -0,0 +1,12 @@
+# API Reference
+
+- [Router instance properties](properties.md)
+- [router.start](start.md)
+- [router.stop](stop.md)
+- [router.map](map.md)
+- [router.on](on.md)
+- [router.go](go.md)
+- [router.replace](replace.md)
+- [router.redirect](redirect.md)
+- [router.alias](alias.md)
+- [router.beforeEach](before-each.md)

docs/api/alias.md

@@ -0,0 +1,25 @@
+# `router.alias(aliasMap)`
+
+Configures global alias rules for the router. The difference between alias and redirect is that instead of replacing the `fromPath` with `toPath`, an alias will preserve `fromPath` while matching it as `toPath`.
+
+For example, if we alias `/a` to `/a/b/c`, when we visit `/a`, the browser URL will display `/a`. However, the router will match the path as if we are visiting `/a/b/c` instead.
+
+### Arguments
+
+- `aliasMap {Object}`
+
+  The alias map object should be in the form of { fromPath: toPath, ... }. The paths can contain dynamic segments.
+
+### Example
+
+``` js
+router.alias({
+
+  // match /a as if it is /a/b/c
+  '/a': '/a/b/c',
+
+  // alias can contian dynamic segments
+  // the dynamic segment names must match
+  '/user/:userId': '/user/profile/:userId'
+})
+```

docs/api/before-each.md

@@ -0,0 +1,38 @@
+# `router.beforeEach(hook)`
+
+Set the global before hook, which will be called before every route transition starts. This is before the entire transition pipeline; if the hook rejects the transition, the pipeline won't even be started.
+
+Note you can only have one global before hook at a time; however you can implement your own middleware system inside this hook.
+
+### Arguments
+
+- `hook {Function}`
+
+  The hook function receives a single argument which is a [Transition Object](../pipeline/hooks.html#transition-object).
+
+### Example
+
+Basic
+
+``` js
+router.beforeEach(function (transition) {
+  if (transition.to.path === '/forbidden') {
+    transition.abort()
+  } else {
+    transition.next()
+  }
+})
+```
+
+Promise + ES6
+
+``` js
+router.beforeEach(function ({ to, next }) {
+  if (to.path === '/auth-required') {
+    // return a Promise that resolves to true or false
+    return AuthService.isLoggedIn()
+  } else {
+    next()
+  }
+})
+```

docs/api/go.md

@@ -0,0 +1,9 @@
+# `router.go(path)`
+
+Programatically navigate to a new route.
+
+### Arguments
+
+- `path: String`
+
+  The path must be a plain path (i.e. no dynamic segments or star segments). The the path doesn't start with `/`, it will be resolved relative to the current active path.

docs/api/map.md

@@ -0,0 +1,47 @@
+# `router.map(routeMap)`
+
+The main method to define route mappings for the router.
+
+### Arguments
+
+- `routeMap: Object`
+
+  An object whose keys are paths and values are route config objects. For path matching rules, see [Route Matching](../route.html#route-matching).
+
+### Route Config Object
+
+A route config object can contain two fields:
+
+- `component`: The Vue component to render into the top-level `<router-view>` outlet when this path is matched. The value could either be a constructor returned by calling `Vue.extend`, or a plain component options object. In the latter case the router will implicitly call `Vue.extend` for you.
+
+- `subRoutes`: You can nest another sub route-map here. For each sub path in the `routeRoutes` map, the router will match it against the full path by appending it to the parent path. The matched component will be rendered into the parent route component's `<router-view>` outlet.
+
+### Example
+
+``` js
+router.map({
+  // component constructor
+  '/a': {
+    component: Vue.extend({ /* ... */ })
+  },
+  // plain component options object
+  '/b': {
+    component: {
+      template: '<p>Hello from /b</p>'
+    }
+  },
+  // nested routes
+  '/c': {
+    component: {
+      // simply render the child view
+      template: '<router-view></router-view>'
+    },
+    subRoutes: {
+      // rendered when the path is /c/d
+      '/d': { component: { template: 'D' }},
+      // rendered when the path is /c/e
+      '/e': { component: { template: 'E' }}
+    }
+  }
+})
+```

docs/api/on.md

@@ -0,0 +1,18 @@
+# `router.on(path, config)`
+
+Add a single root-level route configuration. Internally, `router.map()` simply calls `router.on()` for each key-value pair in the router map object it receives.
+
+### Arguments
+
+- `path: String` - see [Route Matching](../route.md#route-matching)
+- `config: Object` - see [Route Config Object](map.html#route-config-object).
+
+### Example
+
+``` js
+router.on('/user/:userId', {
+  component: {
+    template: '<div>{{$route.params.userId}}</div>'
+  }
+})
+```

docs/api/properties.md

@@ -0,0 +1,21 @@
+# Router Instance Properties
+
+> Only public properties are documented here.
+
+### `router.app`
+
+- type: `Vue`
+
+  The root Vue instance managed by the router instance. This instance is created from the Vue component contructor you passed into `router.start()`.
+
+### `router.mode`
+
+- type: `String`
+
+  One of `html5`, `hash` or `abstract`.
+
+  - **`html5`**: uses HTML5 history API and listens to `popstate` events. Supports [`saveScrollPosition`](../options.html#savescrollposition).
+
+  - **`hash`**: uses `location.hash` and listens to `hashchange` events. When you specify `history: true` when creating the router, it will fallback into hash mode in browsers that do not support the history API.
+
+  - **`abstract`**: does not listen to any events. Will auto-fallback into this mode if `window` is not present.

docs/api/redirect.md

@@ -0,0 +1,23 @@
+# `router.redirect(redirectMap)`
+
+Configures global redirection rules for the router. Global redirections are performed before matching the current path. If a redirection is found, the originally visited path will simply be skipped and will not leave a record in the history.
+
+### Arguments
+
+- `redirectMap: Object`
+
+  The redirect map object should be in the form of `{ fromPath: toPath, ... }`. The paths can contain dynamic segments.
+
+### Example
+
+``` js
+router.rediect({
+
+  // redirect any navigation to /a to /b
+  '/a': '/b',
+
+  // redirect can contian dynamic segments
+  // the dynamic segment names must match
+  '/user/:userId': '/profile/:userId'
+})
+```