CustomEvent.initCustomEvent() — Methode · JavaScript-Referenz

Signatur

CustomEvent.prototype.initCustomEvent(type, canBubble, cancelable, detail)

Beschreibung

initCustomEvent() stammt aus dem alten DOM-Level-3-Eventmodell. Dort wurden Ereignisse in zwei Schritten erzeugt: Zuerst legte man mit document.createEvent("CustomEvent") ein leeres Ereignisobjekt an, danach initialisierte man es mit initCustomEvent(). Erst dann konnte es mit dispatchEvent() ausgelöst werden.

Die Methode legt den Ereignistyp fest, bestimmt, ob das Ereignis im DOM nach oben weitergereicht wird (Bubbling) und ob es mit preventDefault() abgebrochen werden kann. Außerdem übergibt sie beliebige Nutzdaten, die Listener später über event.detail auslesen.

Die Methode gilt als veraltet. Für neuen Code nimmst du den Konstruktor new CustomEvent(type, { bubbles, cancelable, detail }). Er erledigt alles in einem Schritt und ist besser lesbar. initCustomEvent() brauchst du nur noch, wenn du Altcode pflegst oder sehr alte Browser unterstützen musst. Dazu zählt vor allem der Internet Explorer 9–11, der den CustomEvent-Konstruktor nicht kennt.

Wichtig: Der Aufruf wirkt nur auf ein Ereignis, das noch nicht ausgelöst wurde. Rufst du die Methode auf, während das Ereignis gerade verarbeitet wird, passiert nichts.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignistyps, z. B. `"warenkorb:aktualisiert"`. Groß- und Kleinschreibung zählt.
$canBubble	boolean	false	Legt fest, ob das Ereignis im DOM-Baum nach oben weitergereicht wird (entspricht `bubbles`).
$cancelable	boolean	false	Legt fest, ob das Ereignis mit `preventDefault()` abgebrochen werden kann.
$detail	any	null	Beliebige Nutzdaten, die Listener über `event.detail` lesen können.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Methode verändert das übergebene Ereignisobjekt direkt.

Beispiele

Klassischer Ablauf: createEvent + initCustomEvent + dispatchEvent

const button = document.createElement('button');
document.body.append(button);

document.body.addEventListener('warenkorb:hinzugefuegt', (event) => {
  console.log(`Artikel: ${event.detail.name}, Menge: ${event.detail.menge}`);
});

// Altes Zwei-Schritt-Verfahren
const event = document.createEvent('CustomEvent');
event.initCustomEvent('warenkorb:hinzugefuegt', true, false, { name: 'Kaffee', menge: 2 });

button.dispatchEvent(event); // steigt dank canBubble=true bis zu body auf

Artikel: Kaffee, Menge: 2

Moderne Entsprechung mit dem CustomEvent-Konstruktor

const target = new EventTarget();

target.addEventListener('status', (e) => console.log('Status:', e.detail));

// Gleichwertig zu createEvent + initCustomEvent('status', false, false, 'bereit')
target.dispatchEvent(new CustomEvent('status', { detail: 'bereit' }));

Status: bereit

Hilfsfunktion mit Rückfall für alte Browser (IE 9–11)

const createCustomEvent = (type, { bubbles = false, cancelable = false, detail = null } = {}) => {
  if (typeof window.CustomEvent === 'function') {
    return new CustomEvent(type, { bubbles, cancelable, detail });
  }
  // Rückfall für den Internet Explorer
  const evt = document.createEvent('CustomEvent');
  evt.initCustomEvent(type, bubbles, cancelable, detail);
  return evt;
};

const form = document.createElement('form');
form.addEventListener('speichern', (e) => {
  if (!e.detail.gueltig) e.preventDefault();
});

const evt = createCustomEvent('speichern', { cancelable: true, detail: { gueltig: false } });
const nichtAbgebrochen = form.dispatchEvent(evt);
console.log('Fortfahren?', nichtAbgebrochen);

Fortfahren? false

// Wichtig · Fallstricke

Veraltet: Die Methode ist aus dem DOM-Standard als deprecated markiert. Alle aktuellen Browser unterstützen sie aus Kompatibilitätsgründen noch, sie kann aber künftig wegfallen. Nimm stattdessen new CustomEvent().
Ereignis bereits ausgelöst: Nach dispatchEvent() oder während der Verarbeitung hat ein erneuter Aufruf keine Wirkung. Brauchst du das Ereignis nochmal, erzeuge ein neues Objekt.
Ohne Initialisierung: Löst du ein Ereignis aus createEvent() ohne vorherigen init…-Aufruf aus, wirft dispatchEvent() einen InvalidStateError.
Standardwerte: canBubble und cancelable sind false, wenn du sie weglässt. Ohne canBubble=true erreicht das Ereignis keine Listener auf übergeordneten Elementen.
Node.js: Node.js hat kein document.createEvent(). Dort gibt es CustomEvent ab Version 19 nur über den Konstruktor. initCustomEvent() ist in Node.js nicht verfügbar.
detail-Referenz: detail wird nicht kopiert, sondern als Referenz übergeben. Listener können das Objekt also verändern.

Siehe auch

KeyboardEvent.initKeyboardEvent() MouseEvent.initMouseEvent() MutationEvent.initMutationEvent() TextEvent.initTextEvent() TimeEvent.initTimeEvent()