Synced recent updates to #dee0bfd

src/v2/api/index.md

@@ -105,15 +105,19 @@ type: api
 
 ### ignoredElements
 
-- **类型**：`Array<string>`
+- **类型**：`Array<string | RegExp>`
 
 - **默认值**：`[]`
 
 - **用法**：
 
   ``` js
   Vue.config.ignoredElements = [
-    'my-custom-web-component', 'another-web-component'
+    'my-custom-web-component',
+    'another-web-component',
+    // 用一个 `RegExp` 忽略所有“ion-”开头的元素
+    // 2.5+ only
+    /^ion-/
   ]
   ```
 
@@ -590,7 +594,8 @@ type: api
     data: {
       a: 1,
       b: 2,
-      c: 3
+      c: 3,
+      d: 4
     },
     watch: {
       a: function (val, oldVal) {
@@ -602,6 +607,11 @@ type: api
       c: {
         handler: function (val, oldVal) { /* ... */ },
         deep: true
+      },
+      // 该回调将会在监听开始之后被立即调用
+      d: {
+        handler: function (val, oldVal) { /* ... */ },
+        immediate: true
       }
     }
   })
@@ -845,6 +855,28 @@ type: api
 
 - **参考**：[生命周期图示](../guide/instance.html#生命周期图示)
 
+### errorCaptured
+
+> 2.5.0+ 新增
+
+- **类型**：`(err: Error, vm: Component, info: string) => ?boolean`
+
+- **详细**：
+
+  当捕获一个来自子孙组件的错误时被调用。此钩子会收到三个参数：错误本身、发生错误的组件实例以及一个包含错误来源信息的字符串。此钩子可以返回 `false` 以阻止该错误继续向上传播。
+
+  <p class="tip">你可以在此钩子中修改组件的状态。因此在你的模板或渲染函数中设置其它内容的短路条件非常重要，它可以防止当一个错误被捕获时该组件抛出一个无限的渲染循环。</p>
+
+  **错误传播规则**
+
+  - 默认情况下，如果全局的 `config.errorHandler` 被定义，所有的错误仍会发送它，因此这些错误仍让会向单一的分析服务的地方进行汇报。
+
+  - 如果一个组件的继承或父级从属链路中存在多个 `errorCaptured` 钩子，则它们将会被相同的错误同时唤起。
+
+  - 如果此 `errorCaptured` 钩子自身抛出了一个错误，则这个新错误和原本被捕获的错误都会发送给全局的 `config.errorHandler`。
+
+  - 一个 `errorCaptured` 钩子能够返回 `false` 以阻止错误继续向上传播。本质上是说“这个错误已经被搞定了且应该被忽略”。它会阻止其它任何会被这个错误唤起的 `errorCaptured` 钩子和全局的 `config.errorHandler`。
+
 ## 选项 / 资源
 
 ### directives
@@ -942,7 +974,7 @@ type: api
 
 - **类型**：
   - **provide**：`Object | () => Object`
-  - **inject**：`Array<string> | { [key: string]: string | Symbol }`
+  - **inject**：`Array<string> | { [key: string]: string | Symbol | Object }`
 
 - **详细**：
 
@@ -1024,6 +1056,42 @@ type: api
   }
   ```
 
+  > 在 2.5.0+ 的注入可以通过设置默认值使其变成可选项：
+
+  ``` js
+  const Child = {
+    inject: {
+      foo: { default: 'foo' }
+    }
+  }
+  ```
+
+  如果它需要从一个不同名字的属性注入，则使用 `from` 来表示其源属性：
+
+  ``` js
+  const Child = {
+    inject: {
+      foo: {
+        from: 'bar',
+        default: 'foo'
+      }
+    }
+  }
+  ```
+
+  对于 prop 的默认值来说是类似的，你需要对非原始值使用一个工厂方法：
+
+  ``` js
+  const Child = {
+    inject: {
+      foo: {
+        from: 'bar',
+        default: () => [1, 2, 3]
+      }
+    }
+  }
+  ```
+
 ## 选项 / 其它
 
 ### name

src/v2/examples/index.md

@@ -6,4 +6,4 @@ order: 0
 
 > 蠢萌的 Markdown 编辑器。
 
-<iframe width="100%" height="500" src="https://jsfiddle.net/chrisvfritz/rdjjpc7a/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="500" src="https://jsfiddle.net/chrisvfritz/0dzvcf4d/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>

src/v2/guide/class-and-style.md

@@ -105,7 +105,7 @@ data: {
 <div v-bind:class="[isActive ? activeClass : '', errorClass]"></div>
 ```
 
-这样写将始终添加 `errorClass`，但是只有在 `isActive` 是 `true` 时才添加 `activeClass`。
+这样写将始终添加 `errorClass`，但是只有在 `isActive` 是 [truthy](https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy) 时才添加 `activeClass`。
 
 不过，当有多个条件 class 时这样写有些繁琐。所以在数组语法中也可以使用对象语法：
 

src/v2/guide/comparison.md

@@ -223,9 +223,7 @@ Polymer 自定义的元素是用 HTML 文件来创建的，这会限制使用 Ja
 
 ## Riot
 
-Riot 2.0 提供了一个类似于基于组件的开发模型 (在 Riot 中称之为 Tag)，它提供了小巧精美的 API。Riot 和 Vue 在设计理念上可能有许多相似处。尽管相比 Riot ，Vue 要显得重一点，Vue 还是有很多显著优势的：
+Riot 3.0 提供了一个类似于基于组件的开发模型 (在 Riot 中称之为 Tag)，它提供了小巧精美的 API。Riot 和 Vue 在设计理念上可能有许多相似处。尽管相比 Riot ，Vue 要显得重一点，Vue 还是有很多显著优势的：
 
-- [过渡效果系统](transitions.html)。Riot 现在还没有提供。
-- 功能更加强大的路由机制，Riot 的路由功能的 API 是极少的。
 - 更好的性能。Riot 使用了 [遍历 DOM 树](http://riotjs.com/compare/#virtual-dom-vs-expressions-binding) 而不是虚拟 DOM，但实际上用的还是脏检查机制，因此和 AngularJS 患有相同的性能问题。
 - 更多成熟工具的支持。Vue 提供官方支持 [webpack](https://github.com/vuejs/vue-loader) 和 [Browserify](https://github.com/vuejs/vueify)，而 Riot 是依靠社区来建立集成系统。

src/v2/guide/components.md

@@ -999,9 +999,9 @@ Vue.component('child-component', {
 ``` html
 <my-awesome-list :items="items">
   <!-- 作用域插槽也可以是具名的 -->
-  <li 
-    slot="item" 
-    slot-scope="props" 
+  <li
+    slot="item"
+    slot-scope="props"
     class="my-fancy-item">
     {{ props.text }}
   </li>
@@ -1162,6 +1162,7 @@ Vue.component('async-webpack-example', function (resolve) {
 ``` js
 Vue.component(
   'async-webpack-example',
+  // 该 `import` 函数返回一个 `Promise` 对象。
   () => import('./my-async-component')
 )
 ```

src/v2/guide/conditional.md

@@ -182,7 +182,7 @@ new Vue({
 
 不同的是带有 `v-show` 的元素始终会被渲染并保留在 DOM 中。`v-show` 只是简单地切换元素的 CSS 属性 `display`。
 
-<p class="tip">注意，`v-show` 不支持 `<template>` 语法，也不支持 `v-else`。</p>
+<p class="tip">注意，`v-show` 不支持 `<template>` 元素，也不支持 `v-else`。</p>
 
 ## `v-if` vs `v-show`
 

src/v2/guide/custom-directive.md

@@ -42,8 +42,10 @@ Vue.directive('focus', {
 ``` js
 directives: {
   focus: {
-    // 指令的定义---
-    inserted: function (el) {}
+    // 指令的定义
+    inserted: function (el) {
+      el.focus()
+    }
   }
 }
 ```

src/v2/guide/deployment.md

@@ -50,6 +50,22 @@ module.exports = {
 NODE_ENV=production browserify -g envify -e main.js | uglifyjs -c -m > build.js
 ```
 
+- 或者在 Gulp 中使用 [envify](https://github.com/hughsk/envify)：
+
+  ``` js
+  // 使用 envify 自定义模块来定制环境变量
+  var envify = require('envify/custom')
+
+  browserify(browserifyOptions)
+    .transform(vueify),
+    .transform(
+      // 必填项，以处理 node_modules 里的文件
+      { global: true },
+      envify({ NODE_ENV: 'production' })
+    )
+    .bundle()
+  ```
+
 #### Rollup
 
 使用 [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace)：

src/v2/guide/installation.md

@@ -2,11 +2,11 @@
 title: 安装
 type: guide
 order: 1
-vue_version: 2.4.4
-dev_size: "262.63"
-min_size: "80.76"
-gz_size: "29.35"
-ro_gz_size: "20.60"
+vue_version: 2.5.1
+dev_size: "271.12"
+min_size: "83.13"
+gz_size: "30.33"
+ro_gz_size: "21.04"
 ---
 
 ### 兼容性

src/v2/guide/instance.md

@@ -117,7 +117,7 @@ new Vue({
 
 也有一些其它的钩子，在实例生命周期的不同场景下调用，如 [`mounted`](../api/#mounted)、[`updated`](../api/#updated)、[`destroyed`](../api/#destroyed)。钩子的 `this` 指向调用它的 Vue 实例。
 
-<p class="tip">不要在选项属性或回调上使用[箭头函数](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions)，比如 `created: () => console.log(this.a)` 或 `vm.$watch('a', newValue => this.myMethod())`。因为箭头函数是和父级上下文绑定在一起的，`this` 不会是如你所预期的 Vue 实例，且 `this.a` 或 `this.myMethod` 也会是未定义的。</p>
+<p class="tip">不要在选项属性或回调上使用[箭头函数](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions)，比如 `created: () => console.log(this.a)` 或 `vm.$watch('a', newValue => this.myMethod())`。因为箭头函数是和父级上下文绑定在一起的，`this` 不会是如你所预期的 Vue 实例，经常导致 `Uncaught TypeError: Cannot read property of undefined` 或 `Uncaught TypeError: this.myMethod is not a function` 之类的错误。</p>
 
 ## 生命周期图示
 

src/v2/guide/single-file-components.md

@@ -15,7 +15,7 @@ order: 402
 - **不支持 CSS (No CSS support)** 意味着当 HTML 和 JavaScript 组件化时，CSS 明显被遗漏
 - **没有构建步骤 (No build step)** 限制只能使用 HTML 和 ES5 JavaScript,  而不能使用预处理器，如 Pug (formerly Jade) 和 Babel
 
-文件扩展名为 `.vue` 的 **single-file components(单文件组件)** 为以上所有问题提供了解决方法，并且还可以使用 Webpack 或 Browserify 等构建工具。
+文件扩展名为 `.vue` 的 **single-file components(单文件组件)** 为以上所有问题提供了解决方法，并且还可以使用 webpack 或 Browserify 等构建工具。
 
 这是一个文件名为 `Hello.vue` 的简单实例：
 
@@ -31,7 +31,7 @@ order: 402
 
 <img src="/images/vue-component-with-preprocessors.png" style="display: block; margin: 30px auto;">
 
-这些特定的语言只是例子，你可以只是简单地使用 Babel，TypeScript，SCSS，PostCSS - 或者其他任何能够帮助你提高生产力的预处理器。如果搭配 `vue-loader` 使用 Webpack，它也是把 CSS Modules 当作第一公民来对待的。
+这些特定的语言只是例子，你可以只是简单地使用 Babel，TypeScript，SCSS，PostCSS - 或者其他任何能够帮助你提高生产力的预处理器。如果搭配 `vue-loader` 使用 webpack，它也是把 CSS Modules 当作第一公民来对待的。
 
 ### 怎么看待关注点分离？
 
@@ -50,6 +50,10 @@ order: 402
 
 ## 起步
 
+### 例子沙箱
+
+如果你希望深入了解并开始使用单文件组件，请来 CodeSandbox [看看这个简单的 todo 应用](https://codesandbox.io/s/o29j95wx9)。
+
 ### 针对刚接触 JavaScript 模块开发系统的用户
 
 有了 `.vue` 组件，我们就进入了高级 JavaScript 应用领域。如果你没有准备好的话，意味着还需要学会使用一些附加的工具：
@@ -58,14 +62,12 @@ order: 402
 
 - **Modern JavaScript with ES2015/16**：阅读 Babel 的 [Learn ES2015 guide](https://babeljs.io/docs/learn-es2015/)。你不需要立刻记住每一个方法，但是你可以保留这个页面以便后期参考。
 
-在你花一些时日了解这些资源之后，我们建议你参考 [webpack-simple](https://github.com/vuejs-templates/webpack-simple)。只要遵循指示，你就能很快地运行一个用到 `.vue` 组件，ES2015 和 热重载 (hot-reloading) 的 Vue 项目!
-
-这个模板使用 [Webpack](https://webpack.github.io/)，一个能将多个模块打包成最终应用的模块打包工具。想学习更多 Webpack 的知识，请移步[它们的官方文档](https://webpack.js.org/configuration/)以及 [Webpack Academy](https://webpack.academy/p/the-core-concepts)。
+在你花一些时日了解这些资源之后，我们建议你参考 [webpack](https://github.com/vuejs-templates/webpack)。只要遵循指示，你就能很快地运行一个用到 `.vue` 组件，ES2015 和 热重载 (hot-reloading) 的 Vue 项目!
 
-在 Webpack 中，每个模块被打包到 bundle 之前都由一个相应的 "loader" 来转换，Vue 也提供 [vue-loader](https://github.com/vuejs/vue-loader) 插件来执行 `.vue` 单文件组件 的转换。这个 [webpack-simple](https://github.com/vuejs-templates/webpack-simple) 模板已经为你准备好了所有的东西，但是如果你想了解更多关于 `.vue` 组件和 Webpack 如何一起运转的信息，你可以阅读 [vue-loader 的文档](https://vue-loader.vuejs.org)。
+想学习更多 webpack 的知识，请移步[它们的官方文档](https://webpack.js.org/configuration/)以及 [webpack learning academy](https://webpack.academy/p/the-core-concepts)。在 webpack 中，每个模块被打包到 bundle 之前都由一个相应的 "loader" 来转换，Vue 也提供 [vue-loader](https://github.com/vuejs/vue-loader) 插件来执行 `.vue` 单文件组件 的转换。
 
 ### 针对高级用户
 
-无论你更钟情 Webpack 或是 Browserify，我们为简单的和更复杂的项目都提供了一些文档模板。我们建议浏览 [github.com/vuejs-templates](https://github.com/vuejs-templates)，找到你需要的部分，然后参考 README 中的说明，使用 [vue-cli](https://github.com/vuejs/vue-cli) 工具生成新的项目。
+无论你更钟情 webpack 或是 Browserify，我们为简单的和更复杂的项目都提供了一些文档模板。我们建议浏览 [github.com/vuejs-templates](https://github.com/vuejs-templates)，找到你需要的部分，然后参考 README 中的说明，使用 [vue-cli](https://github.com/vuejs/vue-cli) 工具生成新的项目。
 
-模板中使用 [Webpack](https://webpack.js.org/)，一个模块加载器加载多个模块然后构建成最终应用。为了进一步了解 Webpack，可以看 [官方介绍视频](https://www.youtube.com/watch?v=WQue1AN93YU)。如果你有基础，可以看 [在 Egghead.io 上的 Webpack 进阶教程](https://egghead.io/courses/using-webpack-for-production-javascript-applications)。
+模板中使用 [webpack](https://webpack.js.org/)，一个模块加载器加载多个模块然后构建成最终应用。为了进一步了解 webpack，可以看 [官方介绍视频](https://www.youtube.com/watch?v=WQue1AN93YU)。如果你有基础，可以看 [在 Egghead.io 上的 webpack 进阶教程](https://egghead.io/courses/using-webpack-for-production-javascript-applications)。

src/v2/guide/syntax.md

@@ -95,15 +95,15 @@ Mustache 语法不能作用在 HTML 特性上，遇到这种情况应该使用 [
 一些指令能够接收一个“参数”，在指令名称之后以冒号表示。例如，`v-bind` 指令可以用于响应式地更新 HTML 属性：
 
 ``` html
-<a v-bind:href="url"></a>
+<a v-bind:href="url">...</a>
 ```
 
 在这里 `href` 是参数，告知 `v-bind` 指令将该元素的 `href` 属性与表达式 `url` 的值绑定。
 
 另一个例子是 `v-on` 指令，它用于监听 DOM 事件：
 
 ``` html
-<a v-on:click="doSomething">
+<a v-on:click="doSomething">...</a>
 ```
 
 在这里参数是监听的事件名。我们也会更详细地讨论事件处理。
@@ -113,7 +113,7 @@ Mustache 语法不能作用在 HTML 特性上，遇到这种情况应该使用 [
 修饰符 (Modifiers) 是以半角句号 `.` 指明的特殊后缀，用于指出一个指令应该以特殊方式绑定。例如，`.prevent` 修饰符告诉 `v-on` 指令对于触发的事件调用 `event.preventDefault()`：
 
 ``` html
-<form v-on:submit.prevent="onSubmit"></form>
+<form v-on:submit.prevent="onSubmit">...</form>
 ```
 
 在接下来对 [`v-on`](events.html#事件修饰符) 和 [`v-for`](forms.html#修饰符) 等功能的探索中，你会看到修饰符的其它例子。
@@ -126,20 +126,20 @@ Mustache 语法不能作用在 HTML 特性上，遇到这种情况应该使用 [
 
 ``` html
 <!-- 完整语法 -->
-<a v-bind:href="url"></a>
+<a v-bind:href="url">...</a>
 
 <!-- 缩写 -->
-<a :href="url"></a>
+<a :href="url">...</a>
 ```
 
 ### `v-on` 缩写
 
 ``` html
 <!-- 完整语法 -->
-<a v-on:click="doSomething"></a>
+<a v-on:click="doSomething">...</a>
 
 <!-- 缩写 -->
-<a @click="doSomething"></a>
+<a @click="doSomething">...</a>
 ```
 
 它们看起来可能与普通的 HTML 略有不同，但 `:` 与 `@` 对于特性名来说都是合法字符，在所有支持 Vue.js 的浏览器都能被正确地解析。而且，它们不会出现在最终渲染的标记中。缩写语法是完全可选的，但随着你更深入地了解它们的作用，你会庆幸拥有它们。