Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

CustomEvent : données avec detail et remontée avec bubbles

Utilisez `detail` pour transmettre des données dans un évènement personnalisé et `bubbles` pour que les écouteurs des ancêtres hors capture puissent le recevoir après la phase cible.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

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

new CustomEvent(type, options) crée un évènement DOM. type est un nom d’évènement sensible à la casse, et options est facultatif. La création ne déclenche pas l’évènement : appelez target.dispatchEvent(event) pour exécuter les écouteurs concernés de façon synchrone avant que l’appel ne se termine.

detail et bubbles ont des rôles indépendants. detail contient les données et vaut null par défaut. Les écouteurs y accèdent via la propriété en lecture seule event.detail. Vous pouvez transmettre une valeur primitive ou un objet. Un objet n’est ni copié ni gelé : les écouteurs reçoivent le même objet et peuvent modifier ses propriétés modifiables.

L’option bubbles vaut false par défaut. bubbles: true active la phase de remontée : après la phase cible, l’évènement peut atteindre les écouteurs des ancêtres, sauf si la propagation a été arrêtée. La propriété en lecture seule event.bubbles est héritée de Event. La valeur false ne désactive ni les écouteurs sur la cible ni les écouteurs de capture (capture: true) sur les ancêtres.

stopPropagation() arrête la propagation ultérieure ; indépendamment, cancelable détermine si preventDefault() peut annuler l’évènement. Pour qu’un évènement déclenché dans un arbre shadow DOM puisse remonter au-delà de cet arbre, définissez aussi composed: true (par défaut false). Un évènement déclenché par un script a isTrusted à false ; ne le considérez pas comme une preuve d’action de l’utilisateur. CustomEvent est une API du DOM, pas une fonctionnalité d’ECMAScript 2024. Sa disponibilité dépend de l’environnement d’exécution.

Exemples

{
  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"));
}

Résultat

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

Exécutez le bloc dans Node.js 24 ou dans la console d’un navigateur. Dans le navigateur, les éléments ne sont pas rattachés au document, mais `child` a bien un parent et la remontée native du DOM s’applique. Dans Node.js, le code transmet explicitement l’évènement à `parent` pour simuler cette seule étape de la remontée. Dans les deux environnements, `child` reçoit les deux évènements ; l’écouteur hors capture sur `parent` ne reçoit que le second, avec `score: 2`.

Leçons associées

  • JavaScript · Leçon 43 · Avancé · Version : 4

Sources