CKTIS / JavaScript
CustomEvent: datos con detail y fase de burbujeo con bubbles
Usa `detail` para transmitir datos en un evento personalizado y `bubbles` para que los escuchadores de los ancestros que no usan captura puedan recibirlo después de la fase de destino.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
new CustomEvent(type)
new CustomEvent(type, { detail: payload, bubbles: true })
event.detail
event.bubbles
target.dispatchEvent(event)new CustomEvent(type, options) crea un evento del DOM. type es el nombre del evento y distingue entre mayúsculas y minúsculas; options es opcional. Crear el evento no lo despacha: llama a target.dispatchEvent(event) para invocar de forma síncrona los escuchadores correspondientes antes de que termine la llamada.
detail y bubbles cumplen funciones independientes. detail contiene los datos y su valor predeterminado es null. Los escuchadores lo leen mediante la propiedad de solo lectura event.detail. Puedes pasar un valor primitivo o un objeto. El objeto no se copia ni se congela: los escuchadores reciben el mismo objeto y pueden cambiar sus propiedades modificables.
La opción bubbles vale false por defecto. bubbles: true activa la fase de burbujeo: después de la fase de destino, el evento puede llegar a los escuchadores de los ancestros, salvo que se haya detenido la propagación. La propiedad de solo lectura event.bubbles se hereda de Event. El valor false no desactiva los escuchadores del destino ni los de captura (capture: true) de los ancestros.
stopPropagation() detiene la propagación posterior; por separado, cancelable determina si preventDefault() puede cancelar el evento. Para que un evento despachado dentro de un árbol shadow DOM pueda burbujear fuera de él, establece también composed: true (por defecto, false). Un evento despachado por un script tiene isTrusted en false; no lo trates como prueba de una acción del usuario. CustomEvent es una API del DOM, no parte de ECMAScript 2024. Su disponibilidad depende del entorno de ejecución.
Ejemplos
{
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
Ejecuta el bloque en Node.js 24 o en la consola del navegador. En el navegador, los elementos no están conectados al documento, pero `child` sí tiene un padre y se aplica el burbujeo nativo del DOM. En Node.js, el código reenvía explícitamente el evento a `parent` para simular ese único paso del burbujeo. En ambos entornos, `child` recibe ambos eventos; el escuchador sin captura de `parent` solo recibe el segundo, con `score: 2`.
Lecciones relacionadas
- JavaScript · Lección 43 · Avanzado · Versión: 4