异步组件​

2026-02-22 09:47:25 今晚世界杯

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

jsimport { 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 单文件组件：

jsimport { defineAsyncComponent } from 'vue'

const AsyncComp = defineAsyncComponent(() =>

import('./components/MyComponent.vue')

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

与普通组件一样，异步组件可以使用 app.component() 全局注册：

jsapp.component('MyComponent', defineAsyncComponent(() =>

import('./components/MyComponent.vue')

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

vue

也可以直接在父组件中直接定义它们：

vue

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

jsconst AsyncComp = defineAsyncComponent({

// 加载函数

loader: () => import('./Foo.vue'),

// 加载异步组件时使用的组件

loadingComponent: LoadingComponent,

// 展示加载组件前的延迟时间，默认为 200ms

delay: 200,

// 加载失败后展示的组件

errorComponent: ErrorComponent,

// 如果提供了一个 timeout 时间限制，并超时了

// 也会显示这里配置的报错组件，默认值是：Infinity

timeout: 3000

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

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

惰性激活 ​如果你正在使用服务器端渲染，这一部分才会适用。

在 Vue 3.5+ 中，异步组件可以通过提供激活策略来控制何时进行激活。

Vue 提供了一些内置的激活策略。这些内置策略需要分别导入，以便在未使用时进行 tree-shake。

该设计有意保持在底层，以确保灵活性。将来可以在此基础上构建编译器语法糖，无论是在核心还是更上层的解决方案 (如 Nuxt) 中实现。

在空闲时进行激活 ​通过 requestIdleCallback 进行激活：

jsimport { defineAsyncComponent, hydrateOnIdle } from 'vue'

const AsyncComp = defineAsyncComponent({

loader: () => import('./Comp.vue'),

hydrate: hydrateOnIdle(/* 传递可选的最大超时 */)

})在可见时激活 ​通过 IntersectionObserver 在元素变为可见时进行激活。

jsimport { defineAsyncComponent, hydrateOnVisible } from 'vue'

const AsyncComp = defineAsyncComponent({

loader: () => import('./Comp.vue'),

hydrate: hydrateOnVisible()

})可以选择传递一个侦听器的选项对象值：

jshydrateOnVisible({ rootMargin: '100px' })在媒体查询匹配时进行激活 ​当指定的媒体查询匹配时进行激活。

jsimport { defineAsyncComponent, hydrateOnMediaQuery } from 'vue'

const AsyncComp = defineAsyncComponent({

loader: () => import('./Comp.vue'),

hydrate: hydrateOnMediaQuery('(max-width:500px)')

})交互时激活 ​当组件元素上触发指定事件时进行激活。完成激活后，触发激活的事件也将被重放。

jsimport { defineAsyncComponent, hydrateOnInteraction } from 'vue'

const AsyncComp = defineAsyncComponent({

loader: () => import('./Comp.vue'),

hydrate: hydrateOnInteraction('click')

})也可以是多个事件类型的列表：

jshydrateOnInteraction(['wheel', 'mouseover'])自定义策略 ​tsimport { defineAsyncComponent, type HydrationStrategy } from 'vue'

const myStrategy: HydrationStrategy = (hydrate, forEachElement) => {

// forEachElement 是一个遍历组件未激活的 DOM 中所有根元素的辅助函数，

// 因为根元素可能是一个片段而非单个元素

forEachElement(el => {

// ...

})

// 准备好时调用 `hydrate`

hydrate()

return () => {

// 如必要，返回一个销毁函数

}

}

const AsyncComp = defineAsyncComponent({

loader: () => import('./Comp.vue'),

hydrate: myStrategy

})搭配 Suspense 使用 ​异步组件可以搭配内置的 组件一起使用，若想了解 和异步组件之间交互，请参阅 章节。