JavaScript Academy · Aula

As fases de captura e propagação

Entenda como os eventos percorrem o DOM.

As fases de captura e propagação é uma aula grátis de JavaScript Academy no CoddyKit. Esta é a aula 1 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 JavaScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de JavaScript Academy inclui 4 aulas no total.

Duas passagens pelo DOM

Quando você clica em um elemento, o evento não é disparado somente nesse elemento. Ele percorre a árvore do DOM em duas fases: a fase de captura (de cima para baixo, de document até o alvo) e a fase de propagação (de baixo para cima, do alvo de volta até document).

<div id="outer">
  <button id="inner">Click</button>
</div>

O padrão: propagação

Por padrão, addEventListener escuta durante a fase de propagação. Um clique no botão interno dispara primeiro o manipulador dele, depois o manipulador do elemento pai, em seguida o do avô e assim por diante até document.

inner.addEventListener("click", () => console.log("inner"));
outer.addEventListener("click", () => console.log("outer"));
// Click inner -> logs: "inner" then "outer"

Ativando a captura

Passe um terceiro argumento true (ou { capture: true }) para escutar durante a fase de captura. Os manipuladores de captura são executados de cima para baixo, antes de qualquer manipulador de propagação.

outer.addEventListener("click", () => console.log("outer capture"), true);
inner.addEventListener("click", () => console.log("inner bubble"));
// Click inner -> "outer capture" then "inner bubble"

A ordem completa

Para um clique em #inner com manipuladores nas duas fases, a ordem é: fase de captura de cima para baixo, depois o alvo e, por fim, fase de propagação de baixo para cima.

documento na captura
elemento externo na captura
elemento interno (alvo)
elemento externo na propagação
documento na propagação

event.target versus event.currentTarget

event.target é o elemento que realmente disparou o evento, ou seja, onde o clique ocorreu. event.currentTarget é o elemento cujo ouvinte está sendo executado naquele momento. Em um manipulador de um elemento pai durante a propagação, eles são diferentes.

outer.addEventListener("click", (e) => {
  console.log(e.target.id);        // "inner" - where click occurred
  console.log(e.currentTarget.id); // "outer" - listener owner
});

Interrompendo a propagação

event.stopPropagation() interrompe o percurso: o evento não continuará até o próximo elemento na fase atual. Os manipuladores dos elementos pais acima na árvore nunca serão executados.

inner.addEventListener("click", (e) => {
  e.stopPropagation();
  console.log("handled here only");
});
outer.addEventListener("click", () => console.log("never runs"));

stopImmediatePropagation

stopPropagation() ainda permite que outros ouvintes no mesmo elemento sejam executados. Para também bloquear os ouvintes irmãos no mesmo elemento, use event.stopImmediatePropagation().

inner.addEventListener("click", (e) => {
  e.stopImmediatePropagation();
  console.log("first only");
});
inner.addEventListener("click", () => console.log("blocked"));

preventDefault É Diferente

Não confunda preventDefault() com stopPropagation(). preventDefault() cancela a ação padrão do navegador (seguir um link ou enviar um formulário), mas NÃO impede que o evento continue se propagando.

link.addEventListener("click", (e) => {
  e.preventDefault();  // do not navigate
  // event still bubbles to parents
});

Por Que a Captura É Rara

A maior parte do código usa o borbulhamento porque isso corresponde à nossa intuição: o elemento específico reage primeiro e, em seguida, os contêineres ficam sabendo do ocorrido. A captura é útil quando um elemento pai precisa interceptar ou impedir um evento antes que os elementos filhos o vejam.

Verificando a Fase

event.eventPhase informa qual fase está ativa: 1 captura, 2 no alvo, 3 borbulhamento. Isso raramente é necessário, mas ajuda durante a depuração de cadeias complexas de ouvintes.

el.addEventListener("click", (e) => {
  console.log(e.eventPhase); // 1, 2, or 3
}, true);

Nem Todos os Eventos Fazem Borbulhamento

A maioria dos eventos da interface (click, input, keydown) faz borbulhamento. Alguns não fazem isso por padrão, como focus, blur e mouseenter. Para esses eventos, use as variantes com borbulhamento (focusin, focusout) ou a fase de captura.

Verificação Rápida

Teste sua compreensão das fases dos eventos.

Recapitulação

Os eventos percorrem a captura (para baixo) e depois o borbulhamento (para cima). Os ouvintes usam o borbulhamento por padrão; passe true para usar a captura. e.target é a origem, enquanto e.currentTarget é o elemento proprietário do ouvinte. Use stopPropagation() para interromper o percurso e preventDefault() para cancelar as ações padrão. Essas duas fases são a base da delegação de eventos.

Perguntas Frequentes

A aula “As fases de captura e propagação” é grátis?

Sim — o texto completo de “As fases de captura e propagação” é 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 JavaScript Academy, atualize para CoddyKit PRO. O curso de JavaScript Academy inclui 4 aulas no total.

O que vou aprender em “As fases de captura e propagação”?

Entenda como os eventos percorrem o DOM. Você pratica JavaScript 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 JavaScript Academy?

Nenhuma experiência prévia é necessária. JavaScript 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 1 de 4.

Quanto tempo leva a aula “As fases de captura e propagação”?

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 JavaScript Academy?

Sim. Cada aula de JavaScript 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

← Voltar para JavaScript Academy