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