Merge pull request #188 from vuejs/master

获取vuejs.org官方文档更新

Author: dingyiming

src/api/index.md

@@ -77,6 +77,8 @@ type: api
 
   Assign a handler for uncaught errors during component render and watchers. The handler gets called with the error and the Vue instance.
 
+  > [Sentry](https://sentry.io), an error tracking service, provides [official integration](https://sentry.io/for/vue/) using this option.
+
 ### keyCodes
 
 - **Type:** `{ [key: string]: number }`
@@ -86,10 +88,14 @@ type: api
 - **Usage:**
 
   ``` js
-  Vue.config.keyCodes = { esc: 27 }
+  Vue.config.keyCodes = {
+    v: 86,
+    f1: 112,
+    mediaPlayPause: 179
+  }
   ```
 
-  Define custom key aliases for v-on.
+  Define custom key alias(es) for v-on.
 
 ## Global API
 
@@ -1170,7 +1176,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc
 
   // or, render off-document and append afterwards:
   var component = new MyComponent().$mount()
-  document.getElementById('app').appendChild(vm.$el)
+  document.getElementById('app').appendChild(component.$el)
   ```
 
 - **See also:**

src/examples/firebase.md

@@ -6,4 +6,4 @@ order: 2
 
 > This example uses [Firebase](https://firebase.google.com/) as the data persistence backend and syncs between clients in real time (you can try opening it in multiple browser tabs). In addition, it performs instant validation using computed properties and triggers CSS transitions when adding/removing items.
 
-<iframe width="100%" height="500" src="https://jsfiddle.net/yyx990803/hkrxmp0h/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="500" src="https://jsfiddle.net/chrisvfritz/pyLbpzzx/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>

src/guide/comparison.md

@@ -1,7 +1,7 @@
 ---
 title: Comparison with Other Frameworks
 type: guide
-order: 26
+order: 28
 ---
 
 This is definitely the most difficult page in the guide to write, but we do feel it's important. Odds are, you've had problems you tried to solve and you've used another library to solve them. You're here because you want to know if Vue can solve your specific problems better. That's what we hope to answer for you.

src/guide/components.md

@@ -213,8 +213,6 @@ new Vue({
 </script>
 {% endraw %}
 
-The `el` option also requires a function value when used in a component instance, for exactly the same reason.
-
 ### Composing Components
 
 Components are meant to be used together, most commonly in parent-child relationships: component A may use component B in its own template. They inevitably need to communicate to one another: the parent may need to pass data down to the child, and the child may need to inform the parent of something that happened in the child. However, it is also very important to keep the parent and the child as decoupled as possible via a clearly-defined interface. This ensures each component's code can be written and reasoned about in relative isolation, thus making them more maintainable and potentially easier to reuse.

src/guide/deployment.md

@@ -0,0 +1,60 @@
+---
+title: Deploying For Production
+type: guide
+order: 20
+---
+
+## Stripping Out Warnings
+
+The minified standalone build of Vue has already stripped out all the warnings for you for a smaller file size, but when you are using tools like Webpack or Browserify, you will need some additional configuration to achieve this.
+
+### Webpack
+
+Use Webpack's [DefinePlugin](http://webpack.github.io/docs/list-of-plugins.html#defineplugin) to indicate a production environment, so that warning blocks can be automatically dropped by UglifyJS during minification. Example config:
+
+``` js
+var webpack = require('webpack')
+
+module.exports = {
+  // ...
+  plugins: [
+    // ...
+    new webpack.DefinePlugin({
+      'process.env': {
+        NODE_ENV: '"production"'
+      }
+    }),
+    new webpack.optimize.UglifyJsPlugin({
+      compress: {
+        warnings: false
+      }
+    })
+  ]
+}
+```
+
+### Browserify
+
+- Run your bundling command with `NODE_ENV` set to `"production"`. This tells `vueify` to avoid including hot-reload and development related code.
+- Apply a global [envify](https://github.com/hughsk/envify) transform to your bundle. This allows the minifier to strip out all the warnings in Vue's source code wrapped in env variable conditional blocks. For example:
+
+
+``` bash
+NODE_ENV=production browserify -g envify -e main.js | uglifyjs -c -m > build.js
+```
+
+- To extract styles to a separate css file use a extract-css plugin which is included in vueify.
+
+``` bash
+NODE_ENV=production browserify -g envify -p [ vueify/plugins/extract-css -o build.css ] -e main.js | uglifyjs -c -m > build.js
+```
+
+## Tracking Runtime Errors
+
+If a runtime error occurs during a component's render, it will be passed to the global `Vue.config.errorHandler` config function if it has been set. It might be a good idea to leverage this hook together with an error-tracking service like [Sentry](https://sentry.io), which provides [an official integration](https://sentry.io/for/vue/) for Vue.
+
+## Extracting CSS
+
+When using [Single-File Components](./single-file-components.html), the `<style>` tags are injected dynamically at runtime during development. In production you may want to extract the styles across all components into a single CSS file. For details on how to achieve this, consult the respective documentation for [vue-loader](http://vue-loader.vuejs.org/en/configurations/extract-css.html) and [vueify](https://github.com/vuejs/vueify#css-extraction).
+
+The official `webpack` template from `vue-cli` has this already configured out of the box.

src/guide/events.md

@@ -173,7 +173,7 @@ To address this problem, Vue provides **event modifiers** for `v-on`. Recall tha
 <form v-on:submit.prevent="onSubmit"></form>
 
 <!-- modifiers can be chained -->
-<a v-on:click.stop.prevent="doThat">
+<a v-on:click.stop.prevent="doThat"></a>
 
 <!-- just the modifier -->
 <form v-on:submit.prevent></form>
@@ -217,13 +217,7 @@ Here's the full list of key modifier aliases:
 - left
 - right
 
-Single letter key aliases are also supported.
-
-``` html
-<input v-on:keyup.v="say('That is the first letter in Vue')">
-```
-
-If necessary, you can even define custom key modifier aliases:
+You can also [define custom key modifier aliases](/api/#keyCodes) via the global `config.keyCodes` object:
 
 ``` js
 // enable v-on:keyup.f1

src/guide/forms.md

@@ -36,7 +36,7 @@ new Vue({
 
 ``` html
 <span>Multiline message is:</span>
-<p>{{ message }}</p>
+<p style="white-space: pre">{{ message }}</p>
 <br>
 <textarea v-model="message" placeholder="add multiple lines"></textarea>
 ```

src/guide/installation.md

@@ -56,7 +56,7 @@ By default, the NPM package exports the **runtime-only** build. To use the stand
 ``` js
 resolve: {
   alias: {
-    vue: 'vue/dist/vue.js'
+    'vue$': 'vue/dist/vue.js'
   }
 }
 ```

src/guide/instance.md

@@ -73,7 +73,7 @@ vm.$watch('a', function (newVal, oldVal) {
 })
 ```
 
-<p class="tip">Note that __you should not use arrow functions on an instance property or callback__ (e.g. `vm.$watch('a', newVal => this.myMethod())`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.myMethod` will be undefined.</p>
+<p class="tip">Don't use [arrow functions](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions) on an instance property or callback (e.g. `vm.$watch('a', newVal => this.myMethod())`). As arrow functions are bound to the parent context, `this` will not be the Vue instance as you'd expect and `this.myMethod` will be undefined.</p>
 
 Consult the [API reference](/api) for the full list of instance properties and methods.
 

src/guide/join.md

@@ -1,7 +1,7 @@
 ---
 title: Join the Vue.js Community!
 type: guide
-order: 27
+order: 29
 ---
 
 Vue's community is growing incredibly fast and if you're reading this, there's a good chance you're ready to join it. So... welcome!

src/guide/migration-vue-router.md

@@ -1,12 +1,49 @@
 ---
 title: Migration from Vue Router 0.7.x
 type: guide
-order: 25
+order: 26
 ---
 
 > Only Vue Router 2 is compatible with Vue 2, so if you're updating Vue, you'll have to update Vue Router as well. That's why we've included details on the migration path here in the main docs. For a complete guide on using the new Vue Router, see the [Vue Router docs](http://router.vuejs.org/en/).
 
-<p class="tip">The list of deprecations below should be relatively complete, but the migration helper is still being updated to catch them.</p>
+## Router Initialization
+
+### `router.start` <sup>deprecated</sup>
+
+There is no longer a special API to initialize an app with Vue Router. That means instead of:
+
+``` js
+router.start({
+  template: '<router-view></router-view>'
+}, '#app')
+```
+
+You'll just pass a router property to a Vue instance:
+
+``` js
+new Vue({
+  el: '#app',
+  router: router,
+  template: '<router-view></router-view>'
+})
+```
+
+Or, if you're using the runtime-only build of Vue:
+
+``` js
+new Vue({
+  el: '#app',
+  router: router,
+  render: h => h('router-view')
+})
+```
+
+{% 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 <code>router.start</code> being called.</p>
+</div>
+{% endraw %}
 
 ## Route Definitions
 
@@ -91,14 +128,14 @@ router.match = createMatcher(
 </div>
 {% endraw %}
 
-### `subroutes` <sup>deprecated</sup>
+### `subRoutes` <sup>deprecated</sup>
 
 [Renamed to `children`](http://router.vuejs.org/en/essentials/nested-routes.html) for consistency within Vue and with other routing libraries.
 
 {% 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>subroutes</code> option.</p>
+  <p>Run the <a href="https://github.com/vuejs/vue-migration-helper">migration helper</a> on your codebase to find examples of the <code>subRoutes</code> option.</p>
 </div>
 {% endraw %}
 
@@ -161,6 +198,44 @@ alias: ['/manage', '/administer', '/administrate']
 </div>
 {% endraw %}
 
+### Arbitrary Route Properties
+
+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:
+
+``` js
+'/admin': {
+  component: AdminPanel,
+  requiresAuth: true
+}
+```
+
+Then you would now update it to:
+
+``` js
+{
+  path: '/admin',
+  component: AdminPanel,
+  meta: {
+    requiresAuth: true
+  }
+}
+```
+
+Then when later accessing this property on a route, you will still go through meta. For example:
+
+``` js
+if (route.meta.requiresAuth) {
+  // ...
+}
+```
+
+{% 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 arbitrary route properties not scoped under meta.</p>
+</div>
+{% endraw %}
+
 ## Route Matching
 
 Route matching now uses [path-to-regexp](https://github.com/pillarjs/path-to-regexp) under the hood, making it much more flexible than previously.
@@ -230,12 +305,12 @@ The `<a>` will be the actual link (and will get the correct href), but the activ
 
 ### `router.go`
 
-[Renamed to `router.push`](http://router.vuejs.org/en/essentials/navigation.html#routerpushlocation) for consistency with terminology used in the [HTML5 History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API).
+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.
 
 {% 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 <code>router.go</code> being called.</p>
+  <p>Run the <a href="https://github.com/vuejs/vue-migration-helper">migration helper</a> on your codebase to find examples of <code>router.go</code> being used where <code>router.push</code> should be used instead.</p>
 </div>
 {% endraw %}
 
@@ -453,20 +528,22 @@ data: function () {
 },
 watch: {
   '$route': function () {
-    this.isLoading = true
-    this.fetchData().then(() => {
-      this.isLoading = false
+    var self = this
+    self.isLoading = true
+    self.fetchData().then(function () {
+      self.isLoading = false
     })
   }
 },
 methods: {
   fetchData: function () {
+    var self = this
     return axios.get('/api/posts')
       .then(function (response) {
-        this.posts = response.data.posts
+        self.posts = response.data.posts
       })
       .catch(function (error) {
-        this.fetchError = error
+        self.fetchError = error
       })
   }
 }