当前位置：首页 > news >正文

Vue3 defineAsyncComponent() 函数

news 2025/8/7 13:36:52

异步组件的问题与解决方法

基本用法

加载与错误状态

实际应用场景

代码示例

注意事项

进阶技巧

总结

defineAsyncComponent是Vue3提供的一个API，用于定义异步组件。它允许我们定义一个返回Promise的函数，该Promise在组件需要渲染时解析为组件定义。这样，我们可以将组件分割成多个代码块，按需加载，而不是一次性加载所有组件。

与传统的同步组件相比，异步组件在首次加载时不会阻塞页面的渲染，而是异步加载，从而提高了应用的响应速度。

使用场景

defineAsyncComponent的使用场景非常广泛，以下是一些典型的应用场景：

懒加载组件：只在需要时加载组件，减少初始加载时间。
代码分割：将大型组件拆分成多个小组件，按需加载，减少构建体积。
动态加载：根据用户的操作或应用状态动态加载组件。

异步组件的问题与解决方法

从核心角度看，用户完全可以自主实现异步组件，而无需依赖框架。例如，App 组件的同步渲染如下：

import App from 'App.vue'
createApp(App).mount('#app')

上述代码可以轻松地改为异步渲染：

const loader = () => import('App.vue')
loader().then(App => {createApp(App).mount('#app')
})

此处，我们使用 import() 动态加载组件，返回一个 Promise 实例。组件加载成功后，使用 createApp 函数挂载，实现页面的异步渲染。
如果我们想要部分页面异步渲染，我们只需能够异步加载某个组件。假设下面的代码是 App.vue 组件：

<template><CompA /><component :is="asyncComp" />
</template><script>import { shallowRef } from 'vue'import CompA from 'CompA.vue'export default {components: { CompA },setup() {const asyncComp = shallowRef(null)// 异步加载 CompB 组件import('CompB.vue').then(CompB => asyncComp.value = CompB)return {asyncComp}}}
</script>

此代码模板中，页面由同步渲染的和动态组件构成，动态组件绑定了 asyncComp 变量。
脚本块异步加载 CompB 组件，加载成功后，设定 asyncComp 变量的值为 CompB，实现了 CompB 组件的异步加载和渲染。
虽然用户可以自定义异步组件，但其实现有复杂性，因为完整的异步组件设计包括以下考虑：

如果组件加载失败或超时，是否展示 Error 组件？
是否需要占位内容，例如 Loading 组件，于何时加载时展示？
是否设定延迟展示 Loading 组件的时间，避免由于组件加载过快导致的闪烁？
如果组件加载失败，是否需要重试？

为了更优雅地解决这些问题，我们需在框架层面为异步组件提供封装支持：

允许用户指定加载错误时的渲染组件。
允许用户指定 Loading 组件及其展示延迟。
允许用户设置组件加载超时时长。
提供组件加载失败后的重试功能。

总的来说，这些都是异步组件需要解决的核心问题。

基本用法

在大型项目中，我们可能需要拆分应用为更小的块，并仅在需要时再从服务器加载相关组件。Vue 提供了 defineAsyncComponent 方法来实现此功能：

import { defineAsyncComponent } from 'vue'const AsyncComp = defineAsyncComponent(() => {return new Promise((resolve, reject) => {// ...从服务器获取组件resolve(/* 获取到的组件 */)})
})
// ... 像使用其他一般组件一样使用 `AsyncComp`

如你所见，defineAsyncComponent 方法接收一个返回 Promise 的加载函数。这个 Promise 的 resolve 回调方法应该在从服务器获得组件定义时调用。你也可以调用 reject(reason) 表明加载失败。

ES 模块动态导入也会返回一个 Promise，所以多数情况下我们会将它和 defineAsyncComponent 搭配使用。类似 Vite 和 Webpack 这样的构建工具也支持此语法 (并且会将它们作为打包时的代码分割点)，因此我们也可以用它来导入 Vue 单文件组件：

import { defineAsyncComponent } from 'vue'const AsyncComp = defineAsyncComponent(() =>import('./components/MyComponent.vue')
)

最后得到的 AsyncComp 是一个外层包装过的组件，仅在页面需要它渲染时才会调用加载内部实际组件的函数。它会将接收到的 props 和插槽传给内部组件，所以你可以使用这个异步的包装组件无缝地替换原始组件，同时实现延迟加载。

你也可以在局部注册组件时使用 defineAsyncComponent：

<script>
import { defineAsyncComponent } from 'vue'export default {components: {AdminPage: defineAsyncComponent(() =>import('./components/AdminPageComponent.vue'))}
}
</script><template><AdminPage />
</template>

加载与错误状态

异步操作不可避免地会涉及到加载和错误状态，因此 defineAsyncComponent() 也支持在高级选项中处理这些状态：

const AsyncComp = defineAsyncComponent({// 加载函数loader: () => import('./Foo.vue'),// 加载异步组件时使用的组件loadingComponent: LoadingComponent,// 展示加载组件前的延迟时间，默认为 200msdelay: 200,// 加载失败后展示的组件errorComponent: ErrorComponent,// 如果提供了一个 timeout 时间限制，并超时了// 也会显示这里配置的报错组件，默认值是：Infinitytimeout: 3000
})

如果提供了一个加载组件，它将在内部组件加载时先行显示。在加载组件显示之前有一个默认的 200ms 延迟——这是因为在网络状况较好时，加载完成得很快，加载组件和最终组件之间的替换太快可能产生闪烁，反而影响用户感受。

如果提供了一个报错组件，则它会在加载器函数返回的 Promise 抛错时被渲染。你还可以指定一个超时时间，在请求耗时超过指定时间时也会渲染报错组件。

实际应用场景

代码示例

以下是一个完整的代码示例，展示了如何定义和使用异步组件：

<template><div><component :is="AsyncComponent" /></div>
</template><script>
import { defineAsyncComponent } from 'vue';const AsyncComponent = defineAsyncComponent(() => import('./AsyncComponent.vue'));export default {components: {AsyncComponent,},
};
</script>

在这个示例中，我们定义了一个异步组件AsyncComponent，并在模板中使用它。当组件被渲染时，AsyncComponent会异步加载。