Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

CustomEvent: dados com detail e fase ascendente com bubbles

Utiliza `detail` para transportar dados num evento personalizado e `bubbles` para que os ouvintes dos antepassados sem captura o possam receber após a fase do alvo.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

new CustomEvent(type)
new CustomEvent(type, { detail: payload, bubbles: true })
event.detail
event.bubbles
target.dispatchEvent(event)

new CustomEvent(type, options) cria um evento do DOM. type é o nome do evento e distingue maiúsculas de minúsculas; options é opcional. Criar o evento não o despacha: chama target.dispatchEvent(event) para invocar os ouvintes aplicáveis de forma síncrona, antes de a chamada terminar.

detail e bubbles têm funções independentes. detail contém os dados e tem null como valor predefinido. Os ouvintes leem-nos através da propriedade só de leitura event.detail. Podes passar um valor primitivo ou um objeto. O objeto não é copiado nem congelado: os ouvintes recebem o mesmo objeto e podem alterar as suas propriedades modificáveis.

A opção bubbles tem false como valor predefinido. bubbles: true ativa a fase ascendente: após a fase do alvo, o evento pode chegar aos ouvintes nos antepassados, exceto se a propagação tiver sido interrompida. A propriedade só de leitura event.bubbles é herdada de Event. O valor false não desativa os ouvintes no alvo nem os ouvintes de captura (capture: true) nos antepassados.

stopPropagation() impede que o evento continue a propagar-se; separadamente, cancelable determina se preventDefault() pode cancelar o evento. Para que um evento despachado dentro de uma árvore shadow DOM possa subir para fora dela, define também composed: true (valor predefinido: false). Um evento despachado por um script tem isTrusted igual a false; não o tomes como prova de uma ação do utilizador. CustomEvent é uma API do DOM e não faz parte do ECMAScript 2024. A disponibilidade depende do ambiente de execução.

Exemplos

{
  const hasDOM = typeof document !== "undefined";
  const parent = hasDOM ? document.createElement("div") : new EventTarget();
  const child = hasDOM ? document.createElement("div") : new EventTarget();
  if (hasDOM) parent.appendChild(child);

  const type = "score-change";
  const lines = [];
  child.addEventListener(type, (event) => {
    lines.push(`child: ${event.detail.score}, bubbles=${event.bubbles}`);
  });
  parent.addEventListener(type, (event) => {
    lines.push(`parent: ${event.detail.score}, bubbles=${event.bubbles}`);
  });

  function dispatchFromChild(event) {
    child.dispatchEvent(event);
    // Without a DOM tree, model just the bubbling step to one parent.
    if (!hasDOM && event.bubbles && !event.cancelBubble) {
      parent.dispatchEvent(event);
    }
  }

  dispatchFromChild(new CustomEvent(type, { detail: { score: 1 } }));
  dispatchFromChild(new CustomEvent(type, {
    detail: { score: 2 },
    bubbles: true,
  }));

  console.log(lines.join("\n"));
}

Resultado

child: 1, bubbles=false
child: 2, bubbles=true
parent: 2, bubbles=true

Executa o bloco em Node.js 24 ou na consola do navegador. No navegador, os elementos não estão ligados ao documento, mas `child` tem um elemento pai e aplica-se a propagação ascendente nativa do DOM. Em Node.js, o código reencaminha explicitamente o evento para `parent` para simular apenas esse passo da fase ascendente. Em ambos os ambientes, `child` recebe ambos os eventos; o ouvinte sem captura em `parent` recebe apenas o segundo, com `score: 2`.

Lições relacionadas

  • JavaScript · Lição 43 · Avançado · Versão: 4

Fontes