Componentes assíncronos com defineAsyncComponent
defineAsyncComponent(), loadingComponent, errorComponent e opções de delay e timeout.
Componentes assíncronos com defineAsyncComponent é uma aula grátis de Vue Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Vue Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Vue Academy inclui 4 aulas no total.
Por que usar componentes assíncronos
defineAsyncComponent permite carregar um componente sob demanda — seu código só é buscado quando o componente é renderizado pela primeira vez.
Isso possibilita a divisão do código por rota e por componente, reduzindo seu pacote inicial e acelerando a primeira renderização.
A forma com função de carregamento
O uso mais simples recebe uma função de carregamento que retorna um import() dinâmico. Vite/webpack divide automaticamente esse import em seu próprio fragmento.
<script setup>
import { defineAsyncComponent } from 'vue'
const SettingsModal = defineAsyncComponent(() =>
import('./SettingsModal.vue')
)
</script>
<template>
<SettingsModal v-if="showSettings" />
</template>A forma com objeto de opções
Para ter um controle mais preciso, passe um objeto de opções. Os principais campos são:
- função de carregamento — a função de importação dinâmica
- componente de carregamento — exibido durante o carregamento
- componente de erro — exibido se o carregamento falhar
- atraso / timeout — controles de tempo
import { defineAsyncComponent } from 'vue'
import Loading from './Loading.vue'
import ErrorView from './ErrorView.vue'
const AsyncChart = defineAsyncComponent({
loader: () => import('./Chart.vue'),
loadingComponent: Loading,
errorComponent: ErrorView,
delay: 200,
timeout: 5000
})atraso: evitando que o indicador de carregamento pisque
A opção delay (200 ms por padrão) define por quanto tempo o Vue aguarda antes de exibir o loadingComponent. Se o fragmento for carregado antes desse tempo, nenhum indicador de carregamento será exibido.
Defina delay: 0 para mostrar o estado de carregamento imediatamente.
const AsyncPanel = defineAsyncComponent({
loader: () => import('./Panel.vue'),
loadingComponent: Spinner,
// wait 300ms before showing Spinner
delay: 300
})timeout: falhas em carregamentos lentos
A opção timeout define o tempo máximo de espera. Se o carregador não for resolvido dentro de timeout ms, o errorComponent será exibido e um erro será registrado.
Por padrão, não há tempo limite — o carregamento aguarda indefinidamente.
const AsyncReport = defineAsyncComponent({
loader: () => import('./Report.vue'),
errorComponent: ErrorView,
// fail if not loaded within 10s
timeout: 10000
})O retorno de chamada onError
O manipulador onError é executado quando o carregador é rejeitado. Ele recebe o erro, uma função de nova tentativa, uma função de falha e a contagem atual de tentativas.
É aqui que você implementa a lógica de novas tentativas com limite para redes instáveis.
const AsyncWidget = defineAsyncComponent({
loader: () => import('./Widget.vue'),
onError(error, retry, fail, attempts) {
if (attempts <= 3) {
retry() // try loading again
} else {
fail() // give up, show errorComponent
}
}
})Decisão entre tentar novamente e falhar
Dentro de onError, você deve chamar exatamente uma de retry() ou fail() (ou nenhuma delas, o que também causa uma falha). Uma estratégia comum é tentar novamente algumas vezes em caso de erros de rede, mas falhar imediatamente diante de um erro de sintaxe ou de fragmento que não possa ser corrigido com novas tentativas.
onError(error, retry, fail, attempts) {
const isNetwork = /Loading chunk/.test(error.message)
if (isNetwork && attempts <= 2) {
retry()
} else {
fail()
}
}Combinação com Suspense
Quando um componente assíncrono está dentro de um limite de Suspense, o limite controla o estado de carregamento. Nesse caso, o próprio loadingComponent do componente é ignorado — o conteúdo alternativo de Suspense prevalece.
<template>
<Suspense>
<AsyncChart /> <!-- loadingComponent ignored here -->
<template #fallback>Loading chart...</template>
</Suspense>
</template>Fragmentos nomeados para depuração
Você pode nomear o fragmento gerado com um comentário especial. Isso facilita a leitura das solicitações de rede e dos relatórios do pacote.
const AsyncEditor = defineAsyncComponent(() =>
import(
/* webpackChunkName: "editor" */
'./RichTextEditor.vue'
)
)Componentes assíncronos e propriedades
Componentes assíncronos aceitam propriedades e emitem eventos exatamente como componentes normais. O Vue encaminha tudo de forma transparente assim que o componente real é resolvido — você não precisa alterar o ponto de chamada.
<template>
<AsyncProfile
:user-id="id"
@save="handleSave"
/>
</template>
<!-- AsyncProfile resolves to the real component, props/events pass through -->Boa prática: carregue sob demanda o conteúdo acima da dobra com cuidado
Carregue sob demanda os componentes que estão fora da tela, atrás de interações (modais, abas) ou que são raramente usados. Evite carregar sob demanda a interface essencial acima da dobra — a solicitação adicional pode prejudicar o desempenho percebido.
// Good candidate: modal only opened on click
const Modal = defineAsyncComponent(() => import('./Modal.vue'))
// Poor candidate: hero shown immediately on load
// import Hero directly insteadVerificação rápida
Teste sua compreensão de defineAsyncComponent.
Recapitulação
Você aprendeu sobre o carregamento de componentes assíncronos com defineAsyncComponent:
- a forma com função de carregamento retorna um
import()dinâmico para dividir o código - a forma com opções adiciona
loadingComponent,errorComponent,delay,timeout delayevita que o indicador de carregamento pisque;timeoutfaz carregamentos lentos falharemonError(error, retry, fail, attempts)implementa a lógica de tentar novamente ou falhar- dentro de Suspense, o conteúdo alternativo do limite assume o controle da interface de carregamento
Aprenda HTML com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 42
- Aulas
- 156
Perguntas Frequentes
A aula “Componentes assíncronos com defineAsyncComponent” é grátis?
Sim — o texto completo de “Componentes assíncronos com defineAsyncComponent” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Vue Academy, atualize para CoddyKit PRO. O curso de Vue Academy inclui 4 aulas no total.
O que vou aprender em “Componentes assíncronos com defineAsyncComponent”?
defineAsyncComponent(), loadingComponent, errorComponent e opções de delay e timeout. Você pratica Vue Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Vue Academy?
Nenhuma experiência prévia é necessária. Vue Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.
Quanto tempo leva a aula “Componentes assíncronos com defineAsyncComponent”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Vue Academy?
Sim. Cada aula de Vue Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Componente Vue Suspense
- Componentes assíncronos com defineAsyncComponent
- SSR em fluxo com renderToWebStream
- Estratégias de hidratação adiada