Merge branch 'lang-ja' into guide/migration/attrs-includes-class-style

Author: naokie

src/.vuepress/config.js

@@ -115,9 +115,11 @@ const sidebar = {
         'migration/async-components',
         'migration/attribute-coercion',
         'migration/attrs-includes-class-style',
+        'migration/children',
         'migration/custom-directives',
         'migration/custom-elements-interop',
         'migration/data-option',
+        'migration/emits-option',
         'migration/events-api',
         'migration/filters',
         'migration/fragments',

src/guide/migration/array-refs.md

@@ -25,7 +25,9 @@ export default {
   },
   methods: {
     setItemRef(el) {
-      this.itemRefs.push(el)
+      if (el) {
+        this.itemRefs.push(el)
+      }
     }
   },
   beforeUpdate() {
@@ -40,13 +42,15 @@ export default {
 コンポジション API を使う場合
 
 ```js
-import { ref, onBeforeUpdate, onUpdated } from 'vue'
+import { onBeforeUpdate, onUpdated } from 'vue'
 
 export default {
   setup() {
     let itemRefs = []
     const setItemRef = el => {
-      itemRefs.push(el)
+      if (el) {
+        itemRefs.push(el)
+      }
     }
     onBeforeUpdate(() => {
       itemRefs = []
@@ -55,7 +59,6 @@ export default {
       console.log(itemRefs)
     })
     return {
-      itemRefs,
       setItemRef
     }
   }

src/guide/migration/async-components.md

@@ -66,8 +66,8 @@ const asyncPageWithOptions = defineAsyncComponent({
   loader: () => import('./NextPage.vue'),
   delay: 200,
   timeout: 3000,
-  error: ErrorComponent,
-  loading: LoadingComponent
+  errorComponent: ErrorComponent,
+  loadingComponent: LoadingComponent
 })
 ```
 

src/guide/migration/children.md

@@ -0,0 +1,40 @@
+---
+badges:
+  - removed
+---
+
+# $children <MigrationBadges :badges="$frontmatter.badges" />
+
+## 概要
+
+インスタンスプロパティの `$children` は、Vue 3.0 から削除され、サポートされなくなりました。
+
+## 2.x の構文
+
+2.x では、開発者は `this.$children` を使って、現在のインスタンスの直接の子コンポーネントにアクセスすることができました。
+
+```vue
+<template>
+  <div>
+    <img alt="Vue logo" src="./assets/logo.png">
+    <my-button>Change logo</my-button>
+  </div>
+</template>
+
+<script>
+import MyButton from './MyButton'
+
+export default {
+  components: {
+    MyButton
+  },
+  mounted() {
+    console.log(this.$children) // [VueComponent]
+  }
+}
+</script>
+```
+
+## 3.x の更新
+
+3.x では、 `$children` プロパティが削除され、サポートされなくなりました。代わりに、もし子コンポーネントのインスタンスにアクセスする必要がある場合は、 [$refs](/guide/component-template-refs.html#template-refs) を使用することをお勧めします。

src/guide/migration/custom-directives.md

@@ -7,11 +7,7 @@ badges:
 
 ## 概要
 
-変更点の概要は次のとおりです。
-
-- API は、コンポーネントのライフサイクルとの整合性を高めるために名前が変更されました
-
-詳細については、以下をお読みください。
+コンポーネントのライフサイクルに合わせて、ディレクティブのフック関数の名称が変更されました。
 
 ## 2.x の文法
 
@@ -44,6 +40,7 @@ Vue.directive('highlight', {
 
 ただし、Vue 3 では、カスタムディレクティブ用のよりまとまりのある API を作成しました。Vue 2 では、似たようなイベントにフックしているにもかかわらず、コンポーネントのライフサイクルメソッドとは大きく異なります。これらを次のように統合しました。
 
+- **created** - 追加されました! これは、要素の属性やイベントリスナーが適用される前に呼び出されます。
 - bind → **beforeMount**
 - inserted → **mounted**
 - **beforeUpdate**: 追加されました! これは、コンポーネントのライフサイクルフックのように、要素自体が更新される前に呼び出されます。
@@ -58,7 +55,7 @@ Vue.directive('highlight', {
 const MyDirective = {
   beforeMount(el, binding, vnode, prevVnode) {},
   mounted() {},
-  beforeUpdate() {},
+  beforeUpdate() {}, // 追加
   updated() {},
   beforeUnmount() {}, // 追加
   unmounted() {}
@@ -104,5 +101,5 @@ mounted(el, binding, vnode) {
 ```
 
 :::warning
-[fragments](/guide/migration/fragments.html#overview) のサポートにより、コンポーネントは複数のルートノードを持つ可能性があります。マルチルートコンポーネントに適用すると、ディレクティブは無視され、警告がスローされます。
-:::
+[fragments](/guide/migration/fragments.html#overview) のサポートにより、コンポーネントは複数のルートノードを持つ可能性があります。マルチルートコンポーネントに適用すると、ディレクティブは無視され、警告がログ出力されます。
+:::

src/guide/migration/custom-elements-interop.md

@@ -7,7 +7,7 @@ badges:
 
 ## 概要
 
-- **BREAKING:** カスタム要素のホワイトリスト化はテンプレートのコンパイル中に実行されるようになりました。そのためランタイム設定ではなくコンパイラオプションで設定する必要があります。
+- **BREAKING:** タグをカスタム要素として扱うかのチェックは、テンプレートのコンパイル中に実行されるようになりました。そのためランタイム設定ではなくコンパイラオプションで設定する必要があります。
 - **BREAKING:** 特別な `is` プロパティの使用は予約済みの `<component>` タグのみに制限されます。
 - **NEW:** 新しい `v-is` ディレクティブが追加され、ネイティブ HTML のパース制限を回避するためにネイティブ要素で `is` が使用されていた 2.x のユースケースをサポートするようになりました。
 
@@ -21,7 +21,7 @@ Vue の外部で定義されたカスタム要素を追加したい場合（例
 
 ### 2.x での構文
 
-Vue 2.x では、カスタム要素としてのタグのホワイトリスト化は `Vue.config.ignoredElements` で行われていました。
+Vue 2.x では、カスタム要素としてタグを設定するには `Vue.config.ignoredElements` を使用していました。
 
 ```js
 // 以下で Vue は Vue の外部で定義されたカスタム要素を無視するようになります

src/guide/migration/data-option.md

@@ -8,7 +8,9 @@ badges:
 
 ## 概要
 
-`data` コンポーネントオプション宣言はプレーンな JavaScript `object` を受け入れず、`function` 宣言を期待します。
+- **非互換**: `data` コンポーネントオプション宣言はプレーンな JavaScript `object` を受け入れず、`function` 宣言を期待します。
+
+- **非互換**: ミックスインや継承で複数の `data` 返り値をマージする場合、マージはディープではなくシャローになりました（ルートレベルのプロパティのみマージされます）。
 
 ## 2.x での構文
 
@@ -60,9 +62,60 @@ badges:
 </script>
 ```
 
+## ミックスインをマージする挙動の変更
+
+このほか、コンポーネントとそのミックスインや継承元の `data()` がマージされる際に、マージは*シャロー*で行われるようになりました。
+
+```js
+const Mixin = {
+  data() {
+    return {
+      user: {
+        name: 'Jack',
+        id: 1
+      }
+    }
+  }
+}
+
+const CompA = {
+  mixins: [Mixin],
+  data() {
+    return {
+      user: {
+        id: 2
+      }
+    }
+  }
+}
+```
+
+Vue 2.x での `$data` の結果は:
+
+```json
+{
+  user: {
+    id: 2,
+    name: 'Jack'
+  }
+}
+```
+
+3.0 では、このような結果に:
+
+```json
+{
+  user: {
+    id: 2
+  }
+}
+```
+
 ## 移行の戦略
 
 オブジェクト宣言を利用しているユーザーには以下を推奨します:
 
 - 共有データを外部オブジェクトとして抽出し、それを `data` のプロパティとして使う
 - 共有データへの参照、新しい共有オブジェクトを指すようにを書き換える
+
+ミックスインのディープマージに依存しているユーザーには、そのような依存を完全に避けるためにコードをリファクタリングすることをお勧めします。ミックスインのディープマージは非常に暗黙的であり、コードロジックの理解やデバッグがより難しくなる可能性があります。

src/guide/migration/emits-option.md

@@ -0,0 +1,97 @@
+---
+title: emits オプション
+badges:
+  - new
+---
+
+# `emits` オプション <MigrationBadges :badges="$frontmatter.badges" />
+
+## 概要
+
+Vue 3 では `emits` オプションが、既存の `props` オプションと同様に提供されるようになりました。このオプションを使用して、コンポーネントが親に発行できるイベントを定義することができます。
+
+## 2.x の挙動
+
+Vue 2 では、コンポーネントが受け取るプロパティを定義することはできますが、コンポーネントが発行できるイベントを宣言することはできません。
+
+```vue
+<template>
+  <div>
+    <p>{{ text }}</p>
+    <button v-on:click="$emit('accepted')">OK</button>
+  </div>
+</template>
+<script>
+  export default {
+    props: ['text']
+  }
+</script>
+```
+
+## 3.x の挙動
+
+プロパティと同様に、コンポーネントが発行するイベントは `emits` オプションで定義できるようになりました。
+
+```vue
+<template>
+  <div>
+    <p>{{ text }}</p>
+    <button v-on:click="$emit('accepted')">OK</button>
+  </div>
+</template>
+<script>
+  export default {
+    props: ['text'],
+    emits: ['accepted']
+  }
+</script>
+```
+
+このオプションはオブジェクトも受け取ります。これにより開発者は、発行されたイベントと一緒に渡される引数のバリデータを `props` 定義のバリデータと同様に定義できます。
+
+詳細については、[この機能の API ドキュメント](../../api/options-data.md#emits)をお読みください。
+
+## 移行方針
+
+各コンポーネントから発行されたすべてのイベントを、 `emits` を使って発行することを強くお勧めします。
+
+これは [`.native` 修飾子の削除](./v-on-native-modifier-removed.md) のために特に重要です。 `emits` で宣言されていないイベントのリスナーは、コンポーネントの `$attrs` に含まれるようになり、デフォルトではコンポーネントのルートノードに束縛されます。
+
+### 例
+
+ネイティブイベントを親に再発行するコンポーネントでは、これにより2つのイベントが発火することになります。
+
+```vue
+<template>
+  <button v-on:click="$emit('click', $event)">OK</button>
+</template>
+<script>
+export default {
+  emits: [] // 宣言されていないイベント
+}
+</script>
+```
+
+親がコンポーネントの `click` イベントをリッスンする場合:
+
+```html
+<my-button v-on:click="handleClick"></my-button>
+```
+
+これは _2回_ 引き起こされます。
+
+- `$emit()` から一度。
+- ルート要素に適用されたネイティブイベントリスナから一度。
+
+ここでは2つの選択肢があります。
+
+1. `click` イベントを適切に宣言する。これは `<my-button>` のイベントハンドラに何らかのロジックを実際に追加する場合で役立ちます。
+2. `.native` を追加しなくても、親は簡単にネイティブイベントをリッスンできるので、イベントの再発行を削除します。とにかく明らかにイベントを再発行するだけの場合に適しています。
+
+## 関連情報
+
+- [関連する RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0030-emits-option.md)
+- [移行ガイド - `.native` 修飾子の削除](./v-on-native-modifier-removed.md)
+- [移行ガイド - `$listeners` の削除](./listeners-removed.md)
+- [移行ガイド - `class` と `style` を含む `$attrs`](./attrs-includes-class-style.md)
+- [移行ガイド - Render 関数 API の変更](./render-function-api.md)