diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index b6bf6318bb..d63c785b49 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -48,7 +48,11 @@ const sidebar = { children: [ { title: 'Reactivity', - children: ['/guide/reactivity', '/guide/reactivity-fundamentals', '/guide/reactivity-computed-watchers'] + children: [ + '/guide/reactivity', + '/guide/reactivity-fundamentals', + '/guide/reactivity-computed-watchers' + ] }, { title: 'Composition API', @@ -83,9 +87,11 @@ const sidebar = { title: 'Migration to Vue 3', collapsable: true, children: [ + 'migration', 'migration/global-api', 'migration/treeshaking', - 'migration/functional-components' + 'migration/functional-components', + 'migration/async-components' ] }, { diff --git a/src/guide/migration/async-components.md b/src/guide/migration/async-components.md new file mode 100644 index 0000000000..6a6b6fa4a8 --- /dev/null +++ b/src/guide/migration/async-components.md @@ -0,0 +1,88 @@ +# Async Components + +## Overview + +Here is a high level overview of what has changed: + +- New `defineAsyncComponent` helper method that explicitly defines async components +- `component` option renamed to `loader` +- Loader function does not inherently receive `resolve` and `reject` arguments and must return a Promise + +For a more in-depth explanation, read on! + +## Introduction + +Previously, async components were created by simply defining a component as a function that returned a promise, such as: + +```js +const asyncPage = () => import('./NextPage.vue') +``` + +Or, for the more advanced component syntax with options: + +```js +const asyncPage = { + component: () => import('./NextPage.vue'), + delay: 200, + timeout: 3000, + error: ErrorComponent, + loading: LoadingComponent +} +``` + +## Current Syntax + +Now, in Vue 3, since functional components are defined as pure functions, async components definitions need to be explicitly defined by wrapping it in a new `defineAsyncComponent` helper: + +```js +import { defineAsyncComponent } from 'vue' +import ErrorComponent from './components/ErrorComponent.vue' +import LoadingComponent from './components/LoadingComponent.vue' + +// Async component without options +const asyncPage = defineAsyncComponent(() => import('./NextPage.vue')) + +// Async component with options +const asyncPageWithOptions = defineAsyncComponent({ + loader: () => import('./NextPage.vue'), + delay: 200, + timeout: 3000, + errorComponent: ErrorComponent, + loadingComponent: LoadingComponent +}) +``` + +Another change that has been made from v2 is that the `component` option is now renamed to `loader` in order to accurately communicate that a component definition cannot be provided directly. + +```js{4} +import { defineAsyncComponent } from 'vue' + +const asyncPageWithOptions = defineAsyncComponent({ + loader: () => import('./NextPAge.vue'), + delay: 200, + timeout: 3000, + error: ErrorComponent, + loading: LoadingComponent +}) +``` + +In addition, unlike 2.x, the loader function no longer receives the `resolve` and `reject` arguments and must always return a Promise. + +```js +// 2.x version +const oldAsyncComponent = (resolve, reject) => { + /* ... */ +} + +// 3.x version +const asyncComponent = defineAsyncComponent( + () => + new Promise((resolve, reject) => { + /* ... */ + }) +) +``` + +For more information on the usage of async components, see: + +- [Guide: Dynamic & Async Components](/guide/component-dynamic-async.html#dynamic-components-with-keep-alive)