Sync updates from vuejs.org.

Jinjiang · Jinjiang · commit 1578f403f8ba · 2017-07-03T15:06:01.000+08:00
From: 8b7db5e380478a6876b8b3a4fb79c7654729421f (2.3.0)
to: c7a2852fd4aa1847738d343c813bf422b09e5dff

Except guide/comparison.md (this file will be updated separately).
diff --git a/src/v2/api/index.md b/src/v2/api/index.md
@@ -1198,7 +1198,7 @@ type: api
 
 - **用法：**
 
-  移除事件监听器。
+  移除自定义事件监听器。
 
   - 如果没有提供参数，则移除所有的事件监听器；
 
@@ -1762,6 +1762,31 @@ type: api
 
 - **参考：** [具名 Slots](../guide/components.html#具名-Slot)
 
+### is
+
+- **Expects:** `string`
+
+  Used for [dynamic components](../guide/components.html#Dynamic-Components) and to work around [limitations of in-DOM templates](../guide/components.html#DOM-Template-Parsing-Caveats).
+
+  For example:
+
+  ``` html
+  <!-- component changes when currentView changes -->
+  <component v-bind:is="currentView"></component>
+
+  <!-- necessary because <my-row> would be invalid inside -->
+  <!-- a <table> element and so would be hoisted out      -->
+  <table>
+    <tr is="my-row"></tr>
+  </table>
+  ```
+
+  For detailed usage, follow the links in the description above.
+
+- **See also:**
+  - [Dynamic Components](../guide/components.html#Dynamic-Components)
+  - [DOM Template Parsing Caveats](../guide/components.html#DOM-Template-Parsing-Caveats)
+
 ## 内置的组件
 
 ### component
@@ -1909,6 +1934,8 @@ type: api
   </transition>
   ```
 
+  Note, `<keep-alive>` is designed for the case where it has one direct child component that is being toggled. It does not work if you have `v-for` inside it. When there are multiple conditional children, as above, `<keep-alive>` requires that only one child is rendered at a time.
+
 - **`include` and `exclude`**
 
   > 2.1.0 新增
diff --git a/src/v2/guide/class-and-style.md b/src/v2/guide/class-and-style.md
@@ -202,6 +202,8 @@ data: {
 <div :style="{ display: ['-webkit-box', '-ms-flexbox', 'flex'] }">
 ```
 
+This will only render the last value in the array which the browser supports. In this example, it will render `display: flex` for browsers that support the unprefixed version of flexbox.
+
 ***
 
 > 原文：http://vuejs.org/guide/class-and-style.html
diff --git a/src/v2/guide/components.md b/src/v2/guide/components.md
@@ -426,6 +426,7 @@ Vue.component('example', {
 - Function
 - Object
 - Array
+- Symbol
 
 `type` 也可以是一个自定义构造器函数，使用 `instanceof` 检测。
 
@@ -611,7 +612,12 @@ Vue.component('currency-input', {
         // 删除两侧的空格符
         .trim()
         // 保留 2 小数位
-        .slice(0, value.indexOf('.') + 3)
+        .slice(
+          0,
+          value.indexOf('.') === -1
+            ? value.length
+            : value.indexOf('.') + 3
+        )
       // 如果值不统一，手动覆盖以保持一致
       if (formattedValue !== value) {
         this.$refs.input.value = formattedValue
@@ -644,7 +650,12 @@ Vue.component('currency-input', {
     updateValue: function (value) {
       var formattedValue = value
         .trim()
-        .slice(0, value.indexOf('.') + 3)
+        .slice(
+          0,
+          value.indexOf('.') === -1
+            ? value.length
+            : value.indexOf('.') + 3
+        )
       if (formattedValue !== value) {
         this.$refs.input.value = formattedValue
       }
@@ -665,14 +676,43 @@ new Vue({
 
 <iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/1oqjojjx/embedded/result,html,js" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
 
-事件接口不仅仅可以用来连接组件内部的表单输入，也很容易集成你自己创造的输入类型。想象一下：
+### Customizing Component `v-model`
+
+> New in 2.2.0
+
+By default, `v-model` on a component uses `value` as the prop and `input` as the event, but some input types such as checkboxes and radio buttons may want to use the `value` prop for a different purpose. Using the `model` option can avoid the conflict in such cases:
+
+``` js
+Vue.component('my-checkbox', {
+  model: {
+    prop: 'checked',
+    event: 'change'
+  },
+  props: {
+    checked: Boolean,
+    // this allows using the `value` prop for a different purpose
+    value: String
+  },
+  // ...
+})
+```
+
+``` html
+<my-checkbox v-model="foo" value="some value"></my-checkbox>
+```
+
+The above will be equivalent to:
 
 ``` html
-<voice-recognizer v-model="question"></voice-recognizer>
-<webcam-gesture-reader v-model="gesture"></webcam-gesture-reader>
-<webcam-retinal-scanner v-model="retinalImage"></webcam-retinal-scanner>
+<my-checkbox
+  :checked="foo"
+  @change="val => { foo = val }"
+  value="some value">
+</my-checkbox>
 ```
 
+<p class="tip">Note that you still have to declare the `checked` prop explicitly.</p>
+
 ### 非父子组件通信
 
 有时候两个组件也需要通信(非父子关系)。在简单的场景下，可以使用一个空的 Vue 实例作为中央事件总线：
@@ -1071,7 +1111,7 @@ const AsyncComp = () => ({
 
 ### 组件命名约定
 
-当注册组件（或者 props）时，可以使用 kebab-case ，camelCase ，或 TitleCase 。Vue 不关心这个。
+当注册组件（或者 props）时，可以使用 kebab-case，camelCase，或 PascalCase。
 
 ``` js
 // 在组件定义中
@@ -1080,8 +1120,8 @@ components: {
   'kebab-cased-component': { /* ... */ },
   // register using camelCase
   'camelCasedComponent': { /* ... */ },
-  // register using TitleCase
-  'TitleCasedComponent': { /* ... */ }
+  // register using PascalCase
+  'PascalCasedComponent': { /* ... */ }
 }
 ```
 
@@ -1094,15 +1134,33 @@ components: {
 <pascal-cased-component></pascal-cased-component>
 ```
 
-当使用字符串模式时，可以不受 HTML 的 case-insensitive 限制。这意味实际上在模版中，你可以使用 camelCase 、 TitleCase 或者 kebab-case 来引用：
+当使用字符串模式时，可以不受 HTML 的 case-insensitive 限制。这意味实际上在模版中，你可以使用下面的方式来引用你的组件：
+
+- kebab-case
+- camelCase 或 kebab-case 如果组件已经被定义为 camelCase
+- kebab-case，camelCase 或 PascalCase 如果组件已经被定义为 PascalCase
+
+``` js
+components: {
+  'kebab-cased-component': { /* ... */ },
+  camelCasedComponent: { /* ... */ },
+  PascalCasedComponent: { /* ... */ }
+}
+```
 
 ``` html
-<!-- 在字符串模版中可以用任何你喜欢的方式! -->
-<my-component></my-component>
-<myComponent></myComponent>
-<MyComponent></MyComponent>
+<kebab-cased-component></kebab-cased-component>
+
+<camel-cased-component></camel-cased-component>
+<camelCasedComponent></camelCasedComponent>
+
+<pascal-cased-component></pascal-cased-component>
+<pascalCasedComponent></pascalCasedComponent>
+<PascalCasedComponent></PascalCasedComponent>
 ```
 
+这意味着 PascalCase 是最通用的 _声明约定_ 而 kebab-case 是最通用的 _使用约定_。
+
 如果组件未经 `slot` 元素传递内容，你甚至可以在组件名后使用 `/` 使其自闭合：
 
 ``` html
diff --git a/src/v2/guide/forms.md b/src/v2/guide/forms.md
@@ -38,15 +38,15 @@ new Vue({
 
 ``` html
 <span>Multiline message is:</span>
-<p style="white-space: pre">{{ message }}</p>
+<p style="white-space: pre-line">{{ message }}</p>
 <br>
 <textarea v-model="message" placeholder="add multiple lines"></textarea>
 ```
 
 {% raw %}
 <div id="example-textarea">
   <span>Multiline message is:</span>
-  <p style="white-space: pre">{{ message }}</p>
+  <p style="white-space: pre-line">{{ message }}</p>
   <br>
   <textarea v-model="message" placeholder="add multiple lines"></textarea>
 </div>
diff --git a/src/v2/guide/index.md b/src/v2/guide/index.md
@@ -14,7 +14,7 @@ Vue.js（读音 /vjuː/，类似于 **view**） 是一套构建用户界面的**
 
 <p class="tip">官方指南假设你已有 HTML、CSS 和 JavaScript 中级前端知识。如果你刚开始学习前端开发，将框架作为你的第一步可能不是最好的主意——掌握好基础知识再来！之前有其他框架的使用经验对于学习 Vue.js 是有帮助的，但这不是必需的。</p>
 
-尝试 Vue.js 最简单的方法是使用 [JSFiddle Hello World 例子](https://jsfiddle.net/chrisvfritz/50wL7mdz/)。你可以在浏览器新标签页中打开它，跟着例子学习一些基础用法。或者你也可以创建一个本地的 `.html` 文件，然后通过如下方式引入 Vue：
+尝试 Vue.js 最简单的方法是使用 [JSFiddle Hello World 例子](https://jsfiddle.net/chrisvfritz/50wL7mdz/)。你可以在浏览器新标签页中打开它，跟着例子学习一些基础用法。或者你也可以<a href="https://gist.githubusercontent.com/chrisvfritz/7f8d7d63000b48493c336e48b3db3e52/raw/ed60c4e5d5c6fec48b0921edaed0cb60be30e87c/index.html" target="_blank" download="index.html">创建一个 <code>.html</code> 文件<a/>，然后通过如下方式引入 Vue：
 
 ``` html
 <script src="https://unpkg.com/vue/dist/vue.js"></script>
@@ -292,9 +292,16 @@ Vue.component('todo-item', {
 ``` html
 <div id="app-7">
   <ol>
-    <!-- 现在我们为每个todo-item提供待办项对象    -->
-    <!-- 待办项对象是变量，即其内容可以是动态的 -->
-    <todo-item v-for="item in groceryList" v-bind:todo="item"></todo-item>
+    <!--
+      现在我们为每个 todo-item 提供待办项对象
+      待办项对象是变量，即其内容可以是动态的。
+      我们也需要为每个组件提供一个“key”，晚些时候我们会做个解释。
+    -->
+    <todo-item
+      v-for="item in groceryList"
+      v-bind:todo="item"
+      v-bind:key="item.id">
+    </todo-item>
   </ol>
 </div>
 ```
@@ -309,17 +316,17 @@ var app7 = new Vue({
   el: '#app-7',
   data: {
     groceryList: [
-      { text: '蔬菜' },
-      { text: '奶酪' },
-      { text: '随便其他什么人吃的东西' }
+      { id: 0, text: '蔬菜' },
+      { id: 1, text: '奶酪' },
+      { id: 2, text: '随便其他什么人吃的东西' }
     ]
   }
 })
 ```
 {% raw %}
 <div id="app-7" class="demo">
   <ol>
-    <todo-item v-for="item in groceryList" v-bind:todo="item"></todo-item>
+    <todo-item v-for="item in groceryList" v-bind:todo="item" :key="item.id"></todo-item>
   </ol>
 </div>
 <script>
@@ -331,9 +338,9 @@ var app7 = new Vue({
   el: '#app-7',
   data: {
     groceryList: [
-      { text: '蔬菜' },
-      { text: '奶酪' },
-      { text: '随便其他什么人吃的东西' }
+      { id: 0, text: '蔬菜' },
+      { id: 1, text: '奶酪' },
+      { id: 2, text: '随便其他什么人吃的东西' }
     ]
   }
 })
diff --git a/src/v2/guide/list.md b/src/v2/guide/list.md
@@ -196,7 +196,7 @@ new Vue({
 
 ``` html
 <div>
-  <span v-for="n in 10">{{ n }}</span>
+  <span v-for="n in 10">{{ n }} </span>
 </div>
 ```
 
diff --git a/src/v2/guide/render-function.md b/src/v2/guide/render-function.md
@@ -104,15 +104,16 @@ createElement(
   },
 
   // {String | Array}
-  // 子节点(VNodes)，可以是一个字符串或者一个数组. 可选参数.
+  // 子节点 (VNodes)，由 `createElement()` 构建而成，
+  // 或简单的使用字符串来生成“文本结点”。可选参数。
   [
-    createElement('h1', 'hello world'),
+    '先写一些文字',
+    createElement('h1', '一则头条'),
     createElement(MyComponent, {
       props: {
-        someProp: 'foo'
+        someProp: 'foobar'
       }
-    }),
-    'bar'
+    })
   ]
 )
 ```
@@ -160,7 +161,7 @@ createElement(
   directives: [
     {
       name: 'my-custom-directive',
-      value: '2'
+      value: '2',
       expression: '1 + 1',
       arg: 'foo',
       modifiers: {
@@ -174,7 +175,7 @@ createElement(
     default: props => h('span', props.text)
   },
   // 如果组件是其他组件的子组件，需为slot指定名称
-  slot: 'name-of-slot'
+  slot: 'name-of-slot',
   // 其他特殊顶层属性
   key: 'myKey',
   ref: 'myRef'
@@ -470,7 +471,7 @@ Vue.component('my-component', {
 - `data`: 传递给组件的 data 对象
 - `parent`: 对父组件的引用
 - `listeners`: (2.3.0+) 一个包含了组件上所注册的 `v-on` 侦听器的对象。这只是一个指向 `data.on` 的别名。
-- `injections`: (2.3.0+) 如果使用了 [`inject`](https://vuejs.org/v2/api/#provide-inject) 选项, 则该对象包含了应当被注入的属性。
+- `injections`: (2.3.0+) 如果使用了 [`inject`](../api/#provide-inject) 选项, 则该对象包含了应当被注入的属性。
 
 
 在添加 `functional: true` 之后，锚点标题组件的 render 函数之间简单更新增加 `context` 参数，`this.$slots.default` 更新为 `context.children`，之后`this.level` 更新为 `context.props.level`。
diff --git a/src/v2/guide/state-management.md b/src/v2/guide/state-management.md
@@ -39,11 +39,11 @@ var store = {
     message: 'Hello!'
   },
   setMessageAction (newValue) {
-    this.debug && console.log('setMessageAction triggered with', newValue)
+    if (this.debug) console.log('setMessageAction triggered with', newValue)
     this.state.message = newValue
   },
   clearMessageAction () {
-    this.debug && console.log('clearMessageAction triggered')
+    if (this.debug) console.log('clearMessageAction triggered')
     this.state.message = 'clearMessageAction triggered'
   }
 }
diff --git a/src/v2/guide/syntax.md b/src/v2/guide/syntax.md
@@ -36,7 +36,7 @@ Mustache 标签将会被替代为对应数据对象上 `msg` 属性的值。无
 <div v-html="rawHtml"></div>
 ```
 
-被插入的内容都会被当做 HTML —— 数据绑定会被忽略。注意，你不能使用 `v-html` 来复合局部模板，因为 Vue 不是基于字符串的模板引擎。组件更适合担任 UI 重用与复合的基本单元。
+这个 `div` 的内容将会被替换成为属性值 `rawHtml`，直接作为 HTML —— 数据绑定会被忽略。注意，你不能使用 `v-html` 来复合局部模板，因为 Vue 不是基于字符串的模板引擎。组件更适合担任 UI 重用与复合的基本单元。
 
 <p class="tip">你的站点上动态渲染的任意 HTML 可能会非常危险，因为它很容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。请只对可信内容使用 HTML 插值，**绝不要**对用户提供的内容插值。</p>
 
diff --git a/src/v2/guide/transitioning-state.md b/src/v2/guide/transitioning-state.md
@@ -16,7 +16,7 @@ Vue 的过渡系统提供了非常多简单的方法设置进入、离开和列
 
 ## 状态动画 与 watcher
 
-通过 watcher 我们能监听到任何数值属性的数值更新。可能听起来很抽象，所以让我们先来看看使用Tweenjs一个例子：
+通过 watcher 我们能监听到任何数值属性的数值更新。可能听起来很抽象，所以让我们先来看看使用 [Tweenjs](https://github.com/tweenjs/tween.js) 一个例子：
 
 ``` html
 <script src="https://unpkg.com/tween.js@16.3.4"></script>
@@ -88,7 +88,7 @@ new Vue({
 </script>
 {% endraw %}
 
-当你把数值更新时，就会触发动画。这个是一个不错的演示，但是对于不能直接像数字一样存储的值，比如 CSS 中的 color 的值，通过下面的例子我们来通过 Color.js 实现一个例子：
+当你把数值更新时，就会触发动画。这个是一个不错的演示，但是对于不能直接像数字一样存储的值，比如 CSS 中的 color 的值，通过下面的例子我们来通过 [Color.js](https://github.com/brehaut/color-js) 实现一个例子：
 
 
 ``` html
diff --git a/src/v2/guide/transitions.md b/src/v2/guide/transitions.md

Original file line number	Diff line number	Diff line change
`@@ -39,11 +39,11 @@ var store = {`
`39`	`39`	`message: 'Hello!'`
`40`	`40`	`},`
`41`	`41`	`setMessageAction (newValue) {`
`42`		`- this.debug && console.log('setMessageAction triggered with', newValue)`
	`42`	`+ if (this.debug) console.log('setMessageAction triggered with', newValue)`
`43`	`43`	`this.state.message = newValue`
`44`	`44`	`},`
`45`	`45`	`clearMessageAction () {`
`46`		`- this.debug && console.log('clearMessageAction triggered')`
	`46`	`+ if (this.debug) console.log('clearMessageAction triggered')`
`47`	`47`	`this.state.message = 'clearMessageAction triggered'`
`48`	`48`	`}`
`49`	`49`	`}`