diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 75293509..566a26f9 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -171,6 +171,7 @@ const sidebar = { ], migration: [ '/guide/migration/introduction', + '/guide/migration/migration-build', { title: '詳細', collapsable: false, diff --git a/src/guide/migration/array-refs.md b/src/guide/migration/array-refs.md index eaef8dc2..45646ec1 100644 --- a/src/guide/migration/array-refs.md +++ b/src/guide/migration/array-refs.md @@ -69,4 +69,11 @@ export default { - `itemRefs` は配列である必要はありません。 反復キーで参照できるオブジェクトでも構いません。 -- これにより、必要に応じて `itemRefs` をリアクティブにして監視することもできます。 \ No newline at end of file +- これにより、必要に応じて `itemRefs` をリアクティブにして監視することもできます。 + +## 移行の戦略 + +[移行ビルドのフラグ:](migration-build.html#compat-の設定) + +- `V_FOR_REF` +- `COMPILER_V_FOR_REF` diff --git a/src/guide/migration/async-components.md b/src/guide/migration/async-components.md index d7b7aba3..e11ab5ec 100644 --- a/src/guide/migration/async-components.md +++ b/src/guide/migration/async-components.md @@ -95,3 +95,4 @@ const asyncComponent = defineAsyncComponent( 非同期コンポーネントの使い方のさらなる情報は、以下を見てください: - [ガイド: 動的 & 非同期コンポーネント](/guide/component-dynamic-async.html#動的コンポーネントにおける-keep-alive-の利用) +- [移行ビルドのフラグ: `COMPONENT_ASYNC`](migration-build.html#compat-の設定) diff --git a/src/guide/migration/attribute-coercion.md b/src/guide/migration/attribute-coercion.md index fd02af49..112f65f3 100644 --- a/src/guide/migration/attribute-coercion.md +++ b/src/guide/migration/attribute-coercion.md @@ -125,7 +125,7 @@ badges: "false" - その他の非ブール属性
例えば + その他の非ブール属性
例えば aria-checked、tabindex、altなど undefined, null, false undefined, null @@ -138,3 +138,8 @@ badges: + +[移行ビルドのフラグ:](migration-build.html#compat-の設定) + +- `ATTR_FALSE_VALUE` +- `ATTR_ENUMERATED_COERSION` diff --git a/src/guide/migration/attrs-includes-class-style.md b/src/guide/migration/attrs-includes-class-style.md index fef228b7..b2176d9f 100644 --- a/src/guide/migration/attrs-includes-class-style.md +++ b/src/guide/migration/attrs-includes-class-style.md @@ -60,6 +60,8 @@ export default { `inheritAttrs: false` を使用しているコンポーネントでは、スタイルの適用が意図したとおりに動作することを確認してください。もし以前に `class` や `style` の特別な動作に依存していた場合、これらの属性が別の要素に適用されている可能性があるため、一部の見た目が崩れている可能性があります。 +[移行ビルドのフラグ: `INSTANCE_ATTRS_CLASS_STYLE`](migration-build.html#compat-の設定) + ## 参照 - [関連する RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0031-attr-fallthrough.md) diff --git a/src/guide/migration/children.md b/src/guide/migration/children.md index 13fd84d8..a3a3fa28 100644 --- a/src/guide/migration/children.md +++ b/src/guide/migration/children.md @@ -38,3 +38,7 @@ export default { ## 3.x の更新 3.x では、 `$children` プロパティが削除され、サポートされなくなりました。代わりに、もし子コンポーネントのインスタンスにアクセスする必要がある場合は、 [$refs](/guide/component-template-refs.html#template-refs) を使用することをお勧めします。 + +## 移行の戦略 + +[移行ビルドのフラグ: `INSTANCE_CHILDREN`](migration-build.html#compat-の設定) diff --git a/src/guide/migration/custom-directives.md b/src/guide/migration/custom-directives.md index 5c1b84ba..d37a7449 100644 --- a/src/guide/migration/custom-directives.md +++ b/src/guide/migration/custom-directives.md @@ -37,7 +37,6 @@ Vue.directive('highlight', { ## 3.x での構文 - ただし、Vue 3 では、カスタムディレクティブ用のよりまとまりのある API を作成しました。Vue 2 では、似たようなイベントにフックしているにもかかわらず、コンポーネントのライフサイクルメソッドとは大きく異なります。これらを次のように統合しました。 - **created** - 追加されました! これは、要素の属性やイベントリスナーが適用される前に呼び出されます。 @@ -103,3 +102,7 @@ mounted(el, binding, vnode) { :::warning [fragments](/guide/migration/fragments.html#overview) のサポートにより、コンポーネントは複数のルートノードを持つ可能性があります。マルチルートコンポーネントに適用すると、ディレクティブは無視され、警告がログ出力されます。 ::: + +## 移行の戦略 + +[移行ビルドのフラグ: `CUSTOM_DIR`](migration-build.html#compat-の設定) diff --git a/src/guide/migration/custom-elements-interop.md b/src/guide/migration/custom-elements-interop.md index 8a4fe5da..d4de0cc2 100644 --- a/src/guide/migration/custom-elements-interop.md +++ b/src/guide/migration/custom-elements-interop.md @@ -96,6 +96,8 @@ Vue では、ブラウザで普遍的に利用できるようになる前のネ document.createElement('button', { is: 'plastic-button' }) ``` +[移行ビルドのフラグ: `COMPILER_IS_ON_ELEMENT`](migration-build.html#compat-の設定) + ## `v-is` は In-DOM テンプレートパースのための回避策 > 注: このセクションは、Vue テンプレートがページの HTML に直接記述されている場合にのみ影響します。 diff --git a/src/guide/migration/data-option.md b/src/guide/migration/data-option.md index cc283e7a..fc2367b1 100644 --- a/src/guide/migration/data-option.md +++ b/src/guide/migration/data-option.md @@ -111,6 +111,8 @@ Vue 2.x での `$data` の結果は: } ``` +[移行ビルドのフラグ: `OPTIONS_DATA_FN`](migration-build.html#compat-の設定) + ## 移行の戦略 オブジェクト宣言を利用しているユーザーには以下を推奨します: @@ -119,3 +121,8 @@ Vue 2.x での `$data` の結果は: - 共有データへの参照、新しい共有オブジェクトを指すようにを書き換える ミックスインのディープマージに依存しているユーザーには、そのような依存を完全に避けるためにコードをリファクタリングすることをお勧めします。ミックスインのディープマージは非常に暗黙的であり、コードロジックの理解やデバッグがより難しくなる可能性があります。 + +[移行ビルドのフラグ:](migration-build.html#compat-の設定) + +- `OPTIONS_DATA_FN` +- `OPTIONS_DATA_MERGE` diff --git a/src/guide/migration/events-api.md b/src/guide/migration/events-api.md index f62de245..19ec835e 100644 --- a/src/guide/migration/events-api.md +++ b/src/guide/migration/events-api.md @@ -79,3 +79,5 @@ export default { これは Vue 2 と同じような Event Emitter API を提供します。 これらのメソッドは、Vue 3 の将来の互換ビルドでもサポートされる可能性があります。 + +[移行ビルドのフラグ: `INSTANCE_EVENT_EMITTER`](migration-build.html#compat-の設定) diff --git a/src/guide/migration/filters.md b/src/guide/migration/filters.md index 390de51c..c7f37a6c 100644 --- a/src/guide/migration/filters.md +++ b/src/guide/migration/filters.md @@ -73,6 +73,11 @@ badges: フィルタを使う代わりに、算出プロパティか関数に置き換えることを推奨します。 +[移行ビルドのフラグ:](migration-build.html#compat-の設定) + +- `FILTERS` +- `COMPILER_FILTERS` + ### グローバルフィルタ もし、グローバルにフィルタを登録していて、そしてアプリケーション全体でそのフィルタを使用している場合、そのフィルタを個々のコンポーネントで算出プロパティやメソッドに置き換えるのは不便でしょう。 diff --git a/src/guide/migration/functional-components.md b/src/guide/migration/functional-components.md index 41f31d67..9fe0d040 100644 --- a/src/guide/migration/functional-components.md +++ b/src/guide/migration/functional-components.md @@ -117,3 +117,4 @@ export default { - [移行: Render 関数](/guide/migration/render-function-api.html) - [ガイド: Render 関数](/guide/render-function.html) +- [移行ビルドのフラグ: `COMPONENT_FUNCTIONAL`](migration-build.html#compat-の設定) diff --git a/src/guide/migration/global-api.md b/src/guide/migration/global-api.md index 7f0fa9b1..2dab356e 100644 --- a/src/guide/migration/global-api.md +++ b/src/guide/migration/global-api.md @@ -85,6 +85,7 @@ const app = createApp({}) | Vue.mixin | app.mixin | | Vue.use | app.use ([以下を参照](#a-note-for-plugin-authors)) | | Vue.prototype | app.config.globalProperties ([以下を参照](#vue-prototype-replaced-by-config-globalproperties)) | +| Vue.extend | _削除_ ([以下を参照](#vue-extend-replaced-by-definecomponent)) | グローバルに振る舞いを変更しないその他のグローバル API は [グローバル API の Treeshaking](./global-api-treeshaking.html) にあるように、名前付きエクスポートになりました。 @@ -94,6 +95,8 @@ Vue 3.x では "use production build" のヒントは、"dev + full build" (ラ ES Modules ビルドでは、モジュールバンドラーと一緒に使用されていることと、ほとんどの場合 CLI やボイラープレートで本番環境が適切に設定されているため、このヒントは表示されなくなりました。 +[移行ビルドのフラグ: `CONFIG_PRODUCTION_TIP`](migration-build.html#compat-の設定) + ### `config.ignoredElements` は `config.isCustomElement` に変更 この設定オプションはネイティブのカスタム要素をサポートする意図で導入されたため、それがわかるように名前に変更しました。新しいオプションでは、以前の 文字列 / RegExp の方法より、柔軟な方法を提供する関数を期待します。 @@ -115,6 +118,8 @@ Vue 3 では、要素がコンポーネントであるかどうかのチェッ - これは、Vue CLI 設定の新しいトップレベルのオプションになります。 ::: +[移行ビルドのフラグ: `CONFIG_IGNORED_ELEMENTS`](migration-build.html#compat-の設定) + ### `Vue.prototype` は `config.globalProperties` と置換 Vue 2 では、すべてのコンポーネントでアクセス可能なプロパティを追加するために、 `Vue.prototype` がよく使われていました。 @@ -134,6 +139,58 @@ app.config.globalProperties.$http = () => {} また `globalProperties` の代わりに `provide` ([後述](#provide-inject)) を使うことも考えられます。 +[移行ビルドのフラグ: `GLOBAL_PROTOTYPE`](migration-build.html#compat-の設定) + +### `Vue.extend` の削除 + +Vue 2.x では、`Vue.extend`を使って、コンポーネントのオプションを含むオブジェクトを引数に、Vue のベースコンストラクタの「サブクラス」を作成していました。Vue 3.x では、コンポーネントコンストラクタの概念はもうありません。コンポーネントのマウントには、常に `createApp` グローバル API を使用する必要があります。 + +```js +// 以前 - Vue 2 + +// コンストラクタの作成 +const Profile = Vue.extend({ + template: '

{{firstName}} {{lastName}} aka {{alias}}

', + data() { + return { + firstName: 'Walter', + lastName: 'White', + alias: 'Heisenberg' + } + } +}) +// Profile のインスタンスを作成し、それを要素にマウントする +new Profile().$mount('#mount-point') +``` + +```js +// 今後 - Vue 3 +const Profile = { + template: '

{{firstName}} {{lastName}} aka {{alias}}

', + data() { + return { + firstName: 'Walter', + lastName: 'White', + alias: 'Heisenberg' + } + } +} + +Vue.createApp(Profile).mount('#mount-point') +``` + +#### 型推論 + +Vue 2 では、`Vue.extend`は、コンポーネントのオプションに TypeScript の型推論を提供するためにも使われていました。Vue 3 では、同じ目的のために、`defineComponent`グローバル API を`Vue.extend`の代わりに使用することができます。 + +なお、`defineComponent`の戻り値の型はコンストラクタのような型ですが、これは TSX の推論にのみ使用されます。実行時には、`defineComponent`はほとんど何もせず、オプションオブジェクトをそのまま返します。 + +#### コンポーネントの継承 + +Vue 3 では継承やミックスインよりも、 [Composition API](/api/composition-api.html) によるコンポジションを強く推奨しています。 何らかの理由でコンポーネントの継承が必要な場合は、`Vue.extend` の代わりに [`extends` オプション](/api/options-composition.html#extends) を使用することができます。 + +[移行ビルドのフラグ: `GLOBAL_EXTEND`](migration-build.html#compat-の設定) + ### プラグイン作者へのノート プラグイン作者の一般的なプラクティスとして、`Vue.use` を使ってプラグインを自動的に UMD ビルドにインストールさせるものがありました。例えば、公式の `vue-router` プラグインのブラウザ環境へのインストールは以下のようになっていました: @@ -187,6 +244,8 @@ app.directive('focus', { app.mount('#app') ``` +[移行ビルドのフラグ: `GLOBAL_MOUNT`](migration-build.html#compat-の設定) + ## Provide / Inject Vue 2.x のルートインスタンスで `provide` オプションを使用するのとどうように、Vue 3 のアプリケーションインスタンスでも、アプリケーション内の任意のコンポーネントに注入できる依存関係を提供できます: diff --git a/src/guide/migration/inline-template-attribute.md b/src/guide/migration/inline-template-attribute.md index b3019ee7..409ce867 100644 --- a/src/guide/migration/inline-template-attribute.md +++ b/src/guide/migration/inline-template-attribute.md @@ -30,6 +30,8 @@ Vue 2.x では子コンポーネントの内部のコンテンツを分散コン `inline-template` のユースケースの多くでは、すべてのテンプレートが HTML ページ内に直接書かれるようなビルドツールを使わないセットアップを想定しています。 +[移行ビルドのフラグ: `COMPILER_INLINE_TEMPLATE`](migration-build.html#compat-の設定) + ### オプション #1: `` - [Codepen](https://codepen.io/yyx990803/pen/OJNoaZL) 上のブラウザ内プレイグラウンド - [CodeSandbox](https://v3.vue.new) 上のブラウザ内サンドボックス @@ -37,6 +40,10 @@ Vue.js を使うのは初めてですか？ [エッセンシャルガイド](/gu # select vue 3 preset ``` +## 移行ビルド + +既存の Vue 2 プロジェクトやライブラリを Vue 3 にアップグレードする場合は、Vue 2 と互換性のある API を提供する Vue 3 のビルドを提供しています。詳しくは[移行ビルド](./migration-build.html)のページをご覧ください。 + ## 注目すべき新機能 Vue 3 で注目すべきいくつかの新機能の次のとおりです。 @@ -53,10 +60,6 @@ Vue 3 で注目すべきいくつかの新機能の次のとおりです。 ## 破壊的変更 -::: info INFO -Vue 2 と互換性のある動作と、互換性のない使用法に対する実行時警告を備えた Vue 3 の移行専用ビルドの開発に取り組んでいます。 重要な Vue 2 アプリの移行を計画している場合は、よりスムーズな体験のために移行ビルドを待つことを強くお勧めします。 -::: - 以下は、2.x からの破壊的変更の一覧です。: ### グローバル API diff --git a/src/guide/migration/keycode-modifiers.md b/src/guide/migration/keycode-modifiers.md index 71c3205e..2cf895c9 100644 --- a/src/guide/migration/keycode-modifiers.md +++ b/src/guide/migration/keycode-modifiers.md @@ -54,3 +54,8 @@ Vue.config.keyCodes = { ## 移行の戦略 キーコードを利用している場合は、ケバブケースでの命名に変更することを推奨します。 + +[移行ビルドのフラグ:](migration-build.html#compat-の設定) + +- `CONFIG_KEY_CODES` +- `V_ON_KEYCODE_MODIFIER` diff --git a/src/guide/migration/listeners-removed.md b/src/guide/migration/listeners-removed.md index 2d8ab1db..524f0e27 100644 --- a/src/guide/migration/listeners-removed.md +++ b/src/guide/migration/listeners-removed.md @@ -65,6 +65,8 @@ export default { `$listeners` の使用をすべて削除します。 +[移行ビルドのフラグ: `INSTANCE_LISTENERS`](migration-build.html#compat-の設定) + ## 参照 - [関連する RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0031-attr-fallthrough.md) diff --git a/src/guide/migration/migration-build.md b/src/guide/migration/migration-build.md new file mode 100644 index 00000000..86ec22ba --- /dev/null +++ b/src/guide/migration/migration-build.md @@ -0,0 +1,330 @@ +# 移行ビルド + +## 概要 + +`@vue/compat` (別名「移行ビルド」)は、Vue 2 と互換性のある動作を設定できる Vue 3 のビルドです。 + +移行ビルドは、デフォルトで Vue 2 モードで動作します。ほとんどのパブリック API は、ほんの少しの例外を除いて Vue 2 とまったく同じように動作します。Vue 3 で変更されたり、非推奨となった機能を使用すると実行時に警告が表示されます。機能の互換性は、コンポーネントごとに有効/無効を設定することもできます。 + +### 想定される使用例 + +- ([制限事項](#既知の制限事項)ありでの) Vue 2 アプリケーションの Vue 3 へのアップグレード +- ライブラリを Vue 3 に対応させるための移行作業 +- また、Vue 3 をまだ試していない Vue 2 の経験豊富な開発者は、移行ビルドを Vue 3 の代わりに使用してバージョン間の違いを学ぶことができます。 + +### 既知の制限事項 + +移行ビルドは Vue 2 の動作を可能な限り模倣するようにしていますが、次のようないくつかの制限事項があるため、アプリがアップグレードの対象にならない場合があります。 + +- Vue 2 の内部 API またはドキュメント化されていない動作に頼った依存関係。最も一般的なケースは、 `VNodes` プライベートプロパティの使用です。[Vuetify](https://vuetifyjs.com/en/)、[Quasar](https://quasar.dev/)、[ElementUI](https://element.eleme.io/#/en-US)などのコンポーネントライブラリに依存している場合は、Vue 3 と互換性のあるバージョンを待つことをお勧めします。 + +- Internet Explorer 11 のサポート: [Vue 3 は公式に IE11 サポートの計画を中止しました](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0038-vue3-ie11-support.md)。まだ IE11 以下をサポートする必要がある場合は、Vue 2 のままにしておく必要があります。 + +- サーバーサイドレンダリング: 移行ビルドは SSR にも使用できますが、カスタム SSR セットアップの移行はもっと複雑です。一般的な対処法は、`vue-server-renderer` を[`@vue/server-renderer`](https://github.com/vuejs/vue-next/tree/master/packages/server-renderer)に置き換えることです。Vue 3 ではバンドルレンダラが提供されなくなったため、Vue 3 の SSR を[Vite](https://vitejs.dev/guide/ssr.html)で使用することが推奨されています。また、[Nuxt.js](https://nuxtjs.org/)を使用している場合は、Nuxt 3 を待ったほうがよいでしょう。 + +### 期待すること + +今回の移行ビルドでは、公開されている Vue 2 の API と動作のみをカバーすることを目的としていることに注意してください。ドキュメント化されていない動作に依存しているために移行ビルドでアプリケーションが動作しなかったとしても、そのようなケースへの対応として移行ビルドを調整する可能性は低いでしょう。問題となっている動作への依存を排除するためのリファクタリングを検討してください。 + +注意点としては、アプリケーションの規模が大きく複雑な場合は、移行ビルドを使用しても移行が困難な場合があります。残念ながらアップグレードできない場合は、Composition API やその他の Vue 3 の機能を 2.7 のリリース(2021 年第 3 四半期後半予定)でバックポートする予定であることを覚えておいてください。 + +移行用のビルドでアプリを動作させることができた場合、移行が完了する前に本番環境にリリースすることが**可能**です。パフォーマンスや容量に若干のオーバーヘッドが発生しますが、本番環境の UX には目立った影響はありません。Vue 2 の動作に依存している依存関係があり、アップグレードや置き換えができない場合にはそうする必要があるかもしれません。 + +移行用のビルドは 3.1 から提供され、3.2 のリリースラインと並行して引き続き公開されます。移行ビルドの公開は、将来のマイナーバージョン(2021 年の年末以降)で終了する予定ですので、それまでに標準ビルドへの切り替えを目指してください。 + +## アップグレードのワークフロー + +以下のワークフローは、実際の Vue 2 アプリ(Vue HackerNews 2.0)を Vue 3 に移行する手順を示しています。完全なコミットは[こちら](https://github.com/vuejs/vue-hackernews-2.0/compare/migration)から確認できます。なお、実際に必要な手順はプロジェクトによって異なるため、これらの手順は厳密な指示ではなく一般的なガイダンスとして扱ってください。 + +### 準備 + +- まだ [非推奨の named/scoped スロット構文](https://vuejs.org/v2/guide/components-slots.html#Deprecated-Syntax) を使用している場合は、まず最新の構文にアップデートしてください(構文は 2.6 ですでにサポートされています)。 + +### インストール + +1. 必要に応じてツールをアップグレードします。 + + - カスタム webpack セットアップを使用している場合: `vue-loader` を `^16.0.0` にアップグレードします。 + - `vue-cli` を使用している場合: `vue upgrade` で最新の `@vue/cli-service` にアップグレードします。 + - (代替手段) [Vite](https://vitejs.dev/) + [vite-plugin-vue2](https://github.com/underfin/vite-plugin-vue2)に移行します。[[コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/565b948919eb58f22a32afca7e321b490cb3b074)] + +2. `package.json` で `vue` を 3.1 にアップデートし、同じバージョンの `@vue/compat` をインストールます。また `vue-template-compiler` (もしあれば) を `@vue/compiler-sfc` に置き換えます。 + + ```diff + "dependencies": { + - "vue": "^2.6.12", + + "vue": "^3.1.0", + + "@vue/compat": "^3.1.0" + ... + }, + "devDependencies": { + - "vue-template-compiler": "^2.6.12" + + "@vue/compiler-sfc": "^3.1.0" + } + ``` + + [コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/14f6f1879b43f8610add60342661bf915f5c4b20) + +3. ビルド設定で、`vue` を `@vue/compat` にエイリアスし、Vue のコンパイラオプションで compat モードを有効にします。 + + **設定のサンプル** + +
+ vue-cli + + ```js + // vue.config.js + module.exports = { + chainWebpack: config => { + config.resolve.alias.set('vue', '@vue/compat') + + config.module + .rule('vue') + .use('vue-loader') + .tap(options => { + return { + ...options, + compilerOptions: { + compatConfig: { + MODE: 2 + } + } + } + }) + } + ``` + +
+ +
+ Plain webpack + + ```js + // webpack.config.js + module.exports = { + resolve: { + alias: { + vue: '@vue/compat' + } + }, + module: { + rules: [ + { + test: /\.vue$/, + loader: 'vue-loader', + options: { + compilerOptions: { + compatConfig: { + MODE: 2 + } + } + } + } + ] + } + } + ``` + +
+ +
+ Vite + + ```js + // vite.config.js + export default { + resolve: { + alias: { + vue: '@vue/compat' + } + }, + plugins: [ + vue({ + template: { + compilerOptions: { + compatConfig: { + MODE: 2 + } + } + } + }) + ] + } + ``` + +
+ +4. この時点で、あなたのアプリケーションは、いくつかのコンパイル時のエラーや警告に遭遇するかもしれません(例：フィルターの使用)。まずはそれらを修正してください。コンパイラの警告がすべて消えた場合は、コンパイラを Vue 3 モードに設定することもできます。 + + [コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/b05d9555f6e115dea7016d7e5a1a80e8f825be52) + +5. エラーを修正した後、前述の[制限事項](#既知の制限事項)の対象になっていなければアプリを実行できるはずです。 + + コマンドラインとブラウザのコンソールの両方に、たくさんの警告が表示されると思います。ここでは一般的なヒントをご紹介します。 + + - ブラウザのコンソールでは、特定の警告をフィルタリングすることができます。フィルタを使用して、一度に 1 つの項目を修正することに集中することをお勧めします。また、`-GLOBAL_MOUNT` のような否定のフィルタを使うこともできます。 + + - [compat の設定](#compat-の設定)で特定の非推奨事項を抑制することができます。 + + - 警告の中には、使用している依存関係(例: `vue-router`)が原因となっているものがあります。警告のコンポーネントトレースやスタックトレース(クリックで展開)から確認できます。まず、自分のソースコードに起因する警告の修正に集中してください。 + + - `vue-router` を使用している場合は、`vue-router` v4 にアップグレードするまで、`` と `` は `` で動作しないことに注意してください。 + +6. [`` のクラス名](/guide/migration/transition.html) を更新します。これは、実行時の警告が出ない唯一の機能です。プロジェクト全体で `.*-enter` と `.*-leave` の CSS クラス名を検索することができます。 + + [コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/d300103ba622ae26ac26a82cd688e0f70b6c1d8f) + +7. [新しいグローバルマウント API](/guide/migration/global-api.html#a-new-global-api-createapp)を使用するようにアプリのエントリを更新します。 + + [コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/a6e0c9ac7b1f4131908a4b1e43641f608593f714) + +8. [`vuex` を v4 にアップグレード](https://next.vuex.vuejs.org/guide/migrating-to-4-0-from-3-x.html)します。 + + [コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/5bfd4c61ee50f358cd5daebaa584f2c3f91e0205) + +9. [`vuex-router` を v4 にアップグレード](https://next.router.vuejs.org/guide/migration/index.html)します。 `vuex-router-sync` も使用している場合は、ストアゲッターで置き換えることができます。 + + アップグレード後、`` で `` や `` を使用するには、新しい [scoped-slot ベースの構文](https://next.router.vuejs.org/guide/migration/index.html#router-view-keep-alive-and-transition) を使用する必要があります。 + + [コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/758961e73ac4089890079d4ce14996741cf9344b) + +10. 個々の警告を取り除きます。一部の機能は、Vue 2 と Vue 3 の間で矛盾した動作をすることに注意してください。例えば、Render 関数 API や、関数型コンポーネントと非同期コンポーネントの変更などがあります。アプリケーションの他の部分に影響を与えずに Vue 3 の API に移行するには、[`compatConfig` オプション](#コンポーネントごとの設定)を使用して、コンポーネントごとに Vue 3 の動作をオプトインすることができます。 + + [コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/d0c7d3ae789be71b8fd56ce79cb4cb1f921f893b) + +11. すべての警告が修正されたら、移行ビルドを削除して Vue 3 に正しく切り替えることができます。ただし、Vue 2 の動作に頼った依存関係が残っている場合は、切り替えできないことがあります。 + + [コミット例](https://github.com/vuejs/vue-hackernews-2.0/commit/9beb45490bc5f938c9e87b4ac1357cfb799565bd) + +## compat の設定 + +### グローバル設定 + +compat の機能は個別に無効にすることができます: + +```js +import { configureCompat } from 'vue' + +// 特定の機能のために compat を無効にする +configureCompat({ + FEATURE_ID_A: false, + FEATURE_ID_B: false +}) +``` + +また、アプリケーション全体をデフォルトで Vue 3 の動作にして、特定の compat 機能だけを有効にすることもできます: + +```js +import { configureCompat } from 'vue' + +// すべてを Vue 3 の動作にデフォルト化して、 +// 特定の機能のみ compat を有効にする +configureCompat({ + MODE: 3, + FEATURE_ID_A: true, + FEATURE_ID_B: true +}) +``` + +### コンポーネントごとの設定 + +コンポーネントは `compatConfig` オプションを使用することができます。このオプションには、グローバルの `configureCompat` メソッドと同じオプションが指定できます: + +```js +export default { + compatConfig: { + MODE: 3, // このコンポーネントのみ Vue 3 の動作をオプトインする + FEATURE_ID_A: true // 機能をコンポーネントレベルで切り替えることも可能です + } + // ... +} +``` + +### コンパイラ固有の設定 + +`COMPILER_` で始まる機能は、コンパイラ固有のものです。完全なビルド(ブラウザ内コンパイラ付き)を使用している場合は、実行時に設定することができます。しかし、ビルドセットアップを使用している場合は、代わりにビルド設定の `compilerOptions` で設定する必要があります(上記の設定例を参照)。 + +## 機能リファレンス + +### 互換性の種類 + +- ✔ 完全な互換性 +- ◐ 注意点付きの部分的な互換性 +- ⨂ 互換性なし(警告のみ) +- ⭘ compat のみ(警告なし) + +### 互換性なし + +> 前もって修正する必要がある、またはエラーになる可能性が高い + +| ID | 分類 | 説明 | ドキュメント | +| ------------------------------------- | ---- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| GLOBAL_MOUNT_CONTAINER | ⨂ | マウントされたアプリケーションは、マウント先の要素を置き換えません | [link](/guide/migration/mount-changes.html) | +| CONFIG_DEVTOOLS | ⨂ | production の devtools がビルド時のフラグになりました | [link](https://github.com/vuejs/vue-next/tree/master/packages/vue#bundler-build-feature-flags) | +| COMPILER_V_IF_V_FOR_PRECEDENCE | ⨂ | `v-if` と `v-for` が同じ要素で使われたときの優先順位が変更されました | [link](/guide/migration/v-if-v-for.html) | +| COMPILER_V_IF_SAME_KEY | ⨂ | `v-if` のブランチでは、同じキーを持つことができなくなりました | [link](/guide/migration/key-attribute.html#on-conditional-branches) | +| COMPILER_V_FOR_TEMPLATE_KEY_PLACEMENT | ⨂ | `