Merge pull request #241 from vuejs/master

获取官方文档更新

Author: dingyiming

src/api/index.md

@@ -79,6 +79,22 @@ type: api
 
   > [Sentry](https://sentry.io), an error tracking service, provides [official integration](https://sentry.io/for/vue/) using this option.
 
+### ignoredElements
+
+- **Type:** `Array<string>`
+
+- **Default:** `[]`
+
+- **Usage:**
+
+  ``` js
+  Vue.config.ignoredElements = [
+    'my-custom-web-component', 'another-web-component'
+  ]
+  ```
+
+  Make Vue ignore custom elements defined outside of Vue (e.g., using the Web Components APIs). Otherwise, it will throw a warning about an `Unknown custom element`, assuming that you forgot to register a global component or misspelled a component name.
+
 ### keyCodes
 
 - **Type:** `{ [key: string]: number }`
@@ -249,7 +265,7 @@ type: api
 
 - **Usage:**
 
-  Register or retrieve a global component.
+  Register or retrieve a global component. Registration also automatically sets the component's `name` with the given `id`.
 
   ``` js
   // register an extended constructor
@@ -813,7 +829,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc
 
 - **Type:** `Array<string>`
 
-- **default:** `["{{", "}}"]`
+- **default:** `{% raw %}["{{", "}}"]{% endraw %}`
 
 - **Details:**
 
@@ -1508,7 +1524,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc
 
 - **Does not expect expression**
 
-- **Usage**
+- **Usage:**
 
   Skip compilation for this element and all its children. You can use this for displaying raw mustache tags. Skipping large numbers of nodes with no directives on them can also speed up compilation.
 

src/examples/index.md

@@ -6,4 +6,4 @@ order: 0
 
 > Dead simple Markdown editor.
 
-<iframe width="100%" height="500" src="https://jsfiddle.net/yyx990803/pq22eoj5/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="500" src="https://jsfiddle.net/chrisvfritz/rdjjpc7a/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>

src/examples/todomvc.md

@@ -6,4 +6,6 @@ order: 9
 
 > This is a fully spec-compliant TodoMVC implementation in under 120 effective lines of JavaScript (excluding comments and blank lines).
 
+<p class="tip">Note that if your web browser is configured to block 3rd-party data/cookies, the example below will not work, as the `localStorage` data will fail to be saved from JSFiddle. You'll have to click on `Edit in JSFiddle` to see the live result.</p>
+
 <iframe width="100%" height="500" src="https://jsfiddle.net/yyx990803/4dr2fLb7/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>

src/guide/.npmignore

@@ -324,6 +324,6 @@ Riot 2.0 provides a similar component-based development model (which is called a
 
 - True conditional rendering. Riot renders all if branches and simply shows/hides them.
 - A far more powerful router. Riot’s routing API is extremely minimal.
-- More mature tooling support. Vue provides official support for [Webpack](https://github.com/vuejs/vue-loader), [Browserify](https://github.com/vuejs/vueify), and [SystemJS](https://github.com/vuejs/systemjs-plugin-vue), while Riot relies on community support for build system integration.
+- More mature tooling support. Vue provides official support for [Webpack](https://github.com/vuejs/vue-loader) and [Browserify](https://github.com/vuejs/vueify), while Riot relies on community support for build system integration.
 - [Transition effect system](transitions.html). Riot has none.
 - Better performance. [Despite advertising](https://github.com/vuejs/vuejs.org/issues/346) use of a virtual DOM, Riot in fact uses dirty checking and thus suffers from the same performance issues as Angular 1.

src/guide/comparison.md

@@ -419,15 +419,17 @@ When a prop validation fails, Vue will produce a console warning (if using the d
 
 ## Custom Events
 
-We have learned that the parent can pass data down to the child using props, but how do we communicate back to the parent when something happens? This is where custom events come in.
+We have learned that the parent can pass data down to the child using props, but how do we communicate back to the parent when something happens? This is where Vue's custom event system comes in.
 
 ### Using `v-on` with Custom Events
 
-Every Vue instance implements the [Events interface](/api/#Instance-Methods-Events), which means it can:
+Every Vue instance implements an [events interface](/api/#Instance-Methods-Events), which means it can:
 
 - Listen to an event using `$on(eventName)`
 - Trigger an event using `$emit(eventName)`
 
+<p class="tip">Note that Vue's event system is separate from the browser's [EventTarget API](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget). Though they work similarly, `$on` and `$emit` are __not__ aliases for `addEventListener` and `dispatchEvent`.</p>
+
 In addition, a parent component can listen to the events emitted from a child component using `v-on` directly in the template where the child component is used.
 
 Here's an example:
@@ -981,12 +983,26 @@ Again, this _only_ works within string templates, as self-closing custom element
 
 Components can recursively invoke themselves in their own template. However, they can only do so with the `name` option:
 
+``` js
+name: 'unique-name-of-my-component'
+```
+
+When you register a component globally using `Vue.component`, the global ID is automatically set as the component's `name` option.
+
+``` js
+Vue.component('unique-name-of-my-component', {
+  // ...
+})
+```
+
+If you're not careful, recursive components can also lead to infinite loops:
+
 ``` js
 name: 'stack-overflow',
 template: '<div><stack-overflow></stack-overflow></div>'
 ```
 
-A component like the above will result in a "max stack size exceeded" error, so make sure recursive invocation is conditional (i.e. uses a `v-if` that will eventually be false). When you register a component globally using `Vue.component`, the global ID is automatically set as the component's `name` option.
+A component like the above will result in a "max stack size exceeded" error, so make sure recursive invocation is conditional (i.e. uses a `v-if` that will eventually be `false`).
 
 ### Inline Templates
 

src/guide/components.md

@@ -6,6 +6,7 @@ vue_version: 2.0.3
 dev_size: "188.88"
 min_size: "62.54"
 gz_size: "22.86"
+ro_gz_size: "16"
 ---
 
 ### Compatibility Note
@@ -49,9 +50,9 @@ There are two builds available, the standalone build and the runtime-only build.
 
 - The standalone build includes the compiler and supports the `template` option. **It also relies on the presence of browser APIs so you cannot use it for server-side rendering.**
 
-- The runtime-only build does not include the template compiler, and does not support the `template` option. You can only use the `render` option when using the runtime-only build, but it works with single-file components, because single-file components' templates are pre-compiled into `render` functions during the build step. The runtime-only build is roughly 30% lighter-weight than the standalone build, weighing only 16kb min+gzip.
+- The runtime-only build does not include the template compiler, and does not support the `template` option. You can only use the `render` option when using the runtime-only build, but it works with single-file components, because single-file components' templates are pre-compiled into `render` functions during the build step. The runtime-only build is roughly 30% lighter-weight than the standalone build, weighing only {{ro_gz_size}}kb min+gzip.
 
-By default, the NPM package exports the **runtime-only** build. To use the standalone build, add the following alias to your webpack config:
+By default, the NPM package exports the **runtime-only** build. To use the standalone build, add the following alias to your Webpack config:
 
 ``` js
 resolve: {

src/guide/installation.md

@@ -8,7 +8,7 @@ order: 26
 
 ## Router Initialization
 
-### `router.start` <sup>deprecated</sup>
+### `router.start` <sup>replaced</sup>
 
 There is no longer a special API to initialize an app with Vue Router. That means instead of:
 
@@ -47,7 +47,7 @@ new Vue({
 
 ## Route Definitions
 
-### `router.map` <sup>deprecated</sup>
+### `router.map` <sup>replaced</sup>
 
 Routes are now defined as an array on a [`routes` option](http://router.vuejs.org/en/essentials/getting-started.html#javascript) at router instantiation. So these routes for example:
 
@@ -82,7 +82,7 @@ The array syntax allows more predictable route matching, since iterating over an
 </div>
 {% endraw %}
 
-### `router.on` <sup>deprecated</sup>
+### `router.on` <sup>removed</sup>
 
 If you need to programmatically generate routes when starting up your app, you can do so by dynamically pushing definitions to a routes array. For example:
 
@@ -128,7 +128,7 @@ router.match = createMatcher(
 </div>
 {% endraw %}
 
-### `subRoutes` <sup>deprecated</sup>
+### `subRoutes` <sup>renamed</sup>
 
 [Renamed to `children`](http://router.vuejs.org/en/essentials/nested-routes.html) for consistency within Vue and with other routing libraries.
 
@@ -139,7 +139,7 @@ router.match = createMatcher(
 </div>
 {% endraw %}
 
-### `router.redirect` <sup>deprecated</sup>
+### `router.redirect` <sup>replaced</sup>
 
 This is now an [option on route definitions](http://router.vuejs.org/en/essentials/redirect-and-alias.html). So for example, you will update:
 
@@ -165,7 +165,7 @@ to a definition like below in your `routes` configuration:
 </div>
 {% endraw %}
 
-### `router.alias` <sup>deprecated</sup>
+### `router.alias` <sup>replaced</sup>
 
 This is now an [option on the definition for the route](http://router.vuejs.org/en/essentials/redirect-and-alias.html) you'd like to alias to. So for example, you will update:
 
@@ -198,7 +198,7 @@ alias: ['/manage', '/administer', '/administrate']
 </div>
 {% endraw %}
 
-### Arbitrary Route Properties
+### Arbitrary Route Properties <sup>replaced</sup>
 
 Arbitrary route properties must now be scoped under the new meta property, to avoid conflicts with future features. So for example, if you had defined:
 
@@ -240,20 +240,20 @@ if (route.meta.requiresAuth) {
 
 Route matching now uses [path-to-regexp](https://github.com/pillarjs/path-to-regexp) under the hood, making it much more flexible than previously.
 
-### One or More Named Parameters
+### One or More Named Parameters <sup>changed</sup>
 
 The syntax has changed slightly, so `/category/*tags` for example, should be updated to `/category/:tags+`.
 
 {% raw %}
 <div class="upgrade-path">
   <h4>Upgrade Path</h4>
-  <p>Run the <a href="https://github.com/vuejs/vue-migration-helper">migration helper</a> on your codebase to find examples of the deprecated route syntax.</p>
+  <p>Run the <a href="https://github.com/vuejs/vue-migration-helper">migration helper</a> on your codebase to find examples of the obsolete route syntax.</p>
 </div>
 {% endraw %}
 
 ## Links
 
-### `v-link` <sup>deprecated</sup>
+### `v-link` <sup>replaced</sup>
 
 The `v-link` directive has been replaced with a new [`<router-link>` component](http://router.vuejs.org/en/api/router-link.html), as this sort of job is now solely the responsibility of components in Vue 2. That means whenever wherever you have a link like this:
 
@@ -267,16 +267,18 @@ You'll need to update it like this:
 <router-link to="/about">About</router-link>
 ```
 
+Note that `target="_blank"` is not supported on `<router-link>`, so if you need to open a link in a new tab, you have to use `<a>` instead.
+
 {% raw %}
 <div class="upgrade-path">
   <h4>Upgrade Path</h4>
   <p>Run the <a href="https://github.com/vuejs/vue-migration-helper">migration helper</a> on your codebase to find examples of the <code>v-link</code> directive.</p>
 </div>
 {% endraw %}
 
-### `v-link-active` <sup>deprecated</sup>
+### `v-link-active` <sup>replaced</sup>
 
-The `v-link-active` directive has also been deprecated in favor of specifying a separate tag on [the `<router-link>` component](http://router.vuejs.org/en/api/router-link.html). So for example, you'll update this:
+The `v-link-active` directive has also been replaced by the `tag` attribute on [the `<router-link>` component](http://router.vuejs.org/en/api/router-link.html). So for example, you'll update this:
 
 ``` html
 <li v-link-active>
@@ -303,7 +305,7 @@ The `<a>` will be the actual link (and will get the correct href), but the activ
 
 ## Programmatic Navigation
 
-### `router.go`
+### `router.go` <sup>changed</sup>
 
 For consistency with the [HTML5 History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API), `router.go` is now only used for [back/forward navigation](https://router.vuejs.org/en/essentials/navigation.html#routergon), while [`router.push`](http://router.vuejs.org/en/essentials/navigation.html#routerpushlocation) is used to navigate to a specific page.
 
@@ -316,7 +318,7 @@ For consistency with the [HTML5 History API](https://developer.mozilla.org/en-US
 
 ## Router Options: Modes
 
-### `hashbang: false` <sup>deprecated</sup>
+### `hashbang: false` <sup>removed</sup>
 
 Hashbangs are no longer required for Google to crawl a URL, so they are no longer the default (or even an option) for the hash strategy.
 
@@ -327,7 +329,7 @@ Hashbangs are no longer required for Google to crawl a URL, so they are no longe
 </div>
 {% endraw %}
 
-### `history: true` <sup>deprecated</sup>
+### `history: true` <sup>replaced</sup>
 
 All routing mode options have been condensed into a single [`mode` option](http://router.vuejs.org/en/api/options.html#mode). Update:
 
@@ -352,7 +354,7 @@ var router = new VueRouter({
 </div>
 {% endraw %}
 
-### `abstract: true` <sup>deprecated</sup>
+### `abstract: true` <sup>replaced</sup>
 
 All routing mode options have been condensed into a single [`mode` option](http://router.vuejs.org/en/api/options.html#mode). Update:
 
@@ -379,7 +381,7 @@ var router = new VueRouter({
 
 ## Route Options: Misc
 
-### `saveScrollPosition` <sup>deprecated</sup>
+### `saveScrollPosition` <sup>replaced</sup>
 
 This has been replaced with a [`scrollBehavior` option](http://router.vuejs.org/en/advanced/scroll-behavior.html) that accepts a function, so that the scroll behavior is completely customizable - even per route. This opens many new possibilities, but to simply replicate the old behavior of:
 
@@ -402,7 +404,7 @@ scrollBehavior: function (to, from, savedPosition) {
 </div>
 {% endraw %}
 
-### `root` <sup>deprecated</sup>
+### `root` <sup>renamed</sup>
 
 Renamed to `base` for consistency with [the HTML `<base>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base).
 
@@ -413,7 +415,7 @@ Renamed to `base` for consistency with [the HTML `<base>` element](https://devel
 </div>
 {% endraw %}
 
-### `transitionOnLoad` <sup>deprecated</sup>
+### `transitionOnLoad` <sup>removed</sup>
 
 This option is no longer necessary now that Vue's transition system has explicit [`appear` transition control](transitions.html#Transitions-on-Initial-Render).
 
@@ -424,7 +426,7 @@ This option is no longer necessary now that Vue's transition system has explicit
 </div>
 {% endraw %}
 
-### `suppressTransitionError` <sup>deprecated</sup>
+### `suppressTransitionError` <sup>removed</sup>
 
 Removed due to hooks simplification. If you really must suppress transition errors, you can use [`try`...`catch`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) instead.
 
@@ -437,7 +439,7 @@ Removed due to hooks simplification. If you really must suppress transition erro
 
 ## Route Hooks
 
-### `activate` <sup>deprecated</sup>
+### `activate` <sup>replaced</sup>
 
 Use [`beforeRouteEnter`](http://router.vuejs.org/en/advanced/navigation-guards.html#incomponent-guards) in the component instead.
 
@@ -448,7 +450,7 @@ Use [`beforeRouteEnter`](http://router.vuejs.org/en/advanced/navigation-guards.h
 </div>
 {% endraw %}
 
-### `canActivate` <sup>deprecated</sup>
+### `canActivate` <sup>replaced</sup>
 
 Use [`beforeEnter`](http://router.vuejs.org/en/advanced/navigation-guards.html#perroute-guard) in the route instead.
 
@@ -459,7 +461,7 @@ Use [`beforeEnter`](http://router.vuejs.org/en/advanced/navigation-guards.html#p
 </div>
 {% endraw %}
 
-### `deactivate` <sup>deprecated</sup>
+### `deactivate` <sup>removed</sup>
 
 Use the component's [`beforeDestroy`](/api/#beforeDestroy) or [`destroyed`](/api/#destroyed) hooks instead.
 
@@ -470,7 +472,7 @@ Use the component's [`beforeDestroy`](/api/#beforeDestroy) or [`destroyed`](/api
 </div>
 {% endraw %}
 
-### `canDeactivate` <sup>deprecated</sup>
+### `canDeactivate` <sup>replaced</sup>
 
 Use [`beforeRouteLeave`](http://router.vuejs.org/en/advanced/navigation-guards.html#incomponent-guards) in the component instead.
 
@@ -481,7 +483,7 @@ Use [`beforeRouteLeave`](http://router.vuejs.org/en/advanced/navigation-guards.h
 </div>
 {% endraw %}
 
-### `canReuse: false` <sup>deprecated</sup>
+### `canReuse: false` <sup>removed</sup>
 
 There's no longer a use case for this in the new Vue Router.
 
@@ -492,9 +494,9 @@ There's no longer a use case for this in the new Vue Router.
 </div>
 {% endraw %}
 
-### `data` <sup>deprecated</sup>
+### `data` <sup>replaced</sup>
 
-The `$route` property is reactive, so you can just use a watcher to react to route changes, like this:
+The `$route` property is now reactive, so you can just use a watcher to react to route changes, like this:
 
 ``` js
 watch: {
@@ -514,7 +516,7 @@ methods: {
 </div>
 {% endraw %}
 
-### `$loadingRouteData` <sup>deprecated</sup>
+### `$loadingRouteData` <sup>removed</sup>
 
 Define your own property (e.g. `isLoading`), then update the loading state in a watcher on the route. For example, if fetching data with [axios](https://github.com/mzabriskie/axios):