WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

CustomEvent: Daten mit detail und Bubbling mit bubbles

Mit `detail` übergibst du Daten in einem benutzerdefinierten Ereignis. Mit `bubbles` ermöglichst du, dass Listener an Vorfahren das Ereignis nach der Zielphase ohne Capture empfangen.

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

Syntax

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

new CustomEvent(type, options) erzeugt ein DOM-Ereignis. Bei type, dem Ereignisnamen, wird zwischen Groß- und Kleinschreibung unterschieden. options ist optional. Der Konstruktor löst das Ereignis nicht aus: Erst target.dispatchEvent(event) ruft die zuständigen Listener synchron auf, bevor der Aufruf zurückkehrt.

detail und bubbles haben voneinander unabhängige Aufgaben. detail enthält die Nutzdaten und ist standardmäßig null. Listener lesen den Wert über die schreibgeschützte Eigenschaft event.detail. Du kannst einen primitiven Wert oder ein Objekt übergeben. Ein Objekt wird weder kopiert noch eingefroren: Listener erhalten dasselbe Objekt und können dessen veränderbare Eigenschaften ändern.

Die Option bubbles ist standardmäßig false. bubbles: true aktiviert die Bubbling-Phase: Nach der Zielphase kann das Ereignis Listener an Vorfahren erreichen, sofern die Weiterleitung nicht gestoppt wurde. Die schreibgeschützte Eigenschaft event.bubbles stammt von Event. false deaktiviert weder Listener am Ziel noch Capture-Listener (capture: true) an Vorfahren.

stopPropagation() stoppt die weitere Ausbreitung. Unabhängig davon bestimmt cancelable, ob preventDefault() das Ereignis abbrechen kann. Damit ein innerhalb eines Shadow Trees ausgelöstes Ereignis auch außerhalb dieses Baums bubbeln kann, setze zusätzlich composed: true (Standard: false). Ein per Skript ausgelöstes Ereignis hat isTrusted gleich false; betrachte es nicht als Nachweis einer Benutzeraktion. CustomEvent ist eine DOM-API und kein Teil von ECMAScript 2024. Die Verfügbarkeit hängt von der Laufzeitumgebung ab.

Beispiele

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

Ergebnis

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

Führe den Block in Node.js 24 oder in einer Browserkonsole aus. Im Browser sind die Elemente nicht ins Dokument eingebunden, aber `child` hat ein Elternelement und das native DOM-Bubbling greift. In Node.js leitet der Code das Ereignis ausdrücklich an `parent` weiter, um diesen einen Bubbling-Schritt nachzubilden. In beiden Umgebungen empfängt `child` beide Ereignisse; der Listener ohne Capture an `parent` empfängt nur das zweite mit `score: 2`.

Zugehörige Lektionen

  • JavaScript · Lektion 43 · Fortgeschritten · Version: 4

Quellen