Document.createEvent() — Methode · JavaScript-Referenz

Signatur

Document.prototype.createEvent(type)

Beschreibung

document.createEvent() ist die alte Art, synthetische Events zu erzeugen. Die Methode gibt ein nicht initialisiertes Event-Objekt zurück. Welche Schnittstelle es hat, legt der übergebene Name fest, z. B. "Event", "MouseEvent" oder "CustomEvent". Bevor du das Objekt mit dispatchEvent() auslöst, musst du es mit der passenden Init-Methode vorbereiten, etwa initEvent(), initMouseEvent() oder initCustomEvent(). Ohne diesen Schritt wirft dispatchEvent() einen InvalidStateError.

In modernem Code solltest du stattdessen die Event-Konstruktoren nutzen, etwa new Event(), new CustomEvent(), new MouseEvent() oder new KeyboardEvent(). Damit erzeugst und initialisierst du ein Event in einem Schritt und übergibst die Optionen lesbar als Objekt. Die init*Event()-Methoden gelten als veraltet.

createEvent() brauchst du heute praktisch nur noch in altem Code, für sehr alte Umgebungen wie den Internet Explorer 9–11 (dort fehlen die Event-Konstruktoren) oder in Polyfills.

Groß- und Kleinschreibung spielen beim Namen keine Rolle. Einige ältere Aliasnamen werden ebenfalls akzeptiert, zum Beispiel "Events", "HTMLEvents", "MouseEvents" und "UIEvents".

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name der Event-Schnittstelle, z. B. `"Event"`, `"CustomEvent"`, `"MouseEvent"`, `"KeyboardEvent"`, `"UIEvent"`, `"FocusEvent"`, `"MessageEvent"` oder `"TouchEvent"`. Groß- und Kleinschreibung werden ignoriert. Nicht gemeint ist der Event-Typ wie `"click"`: Den legst du erst in der Init-Methode fest.

Rückgabewert

Typ

Event

Beschreibung

Ein nicht initialisiertes Event-Objekt der angeforderten Schnittstelle, z. B. ein MouseEvent. Wird der Name nicht unterstützt, wirft die Methode einen DOMException vom Typ NotSupportedError.

Beispiele

Einfaches Event erzeugen, initialisieren und auslösen

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

button.addEventListener('ping', (e) => {
  console.log('Empfangen:', e.type, 'bubbles:', e.bubbles);
});

// Alter Weg: erzeugen, dann initialisieren
const event = document.createEvent('Event');
event.initEvent('ping', true, true); // type, bubbles, cancelable
button.dispatchEvent(event);

Empfangen: ping bubbles: true

CustomEvent mit Daten (Legacy) im Vergleich zum Konstruktor

const cart = document.createElement('div');

cart.addEventListener('cart:add', (e) => {
  console.log(`Artikel ${e.detail.sku} x${e.detail.qty}`);
});

// Legacy-Variante
const legacy = document.createEvent('CustomEvent');
legacy.initCustomEvent('cart:add', true, false, { sku: 'A-100', qty: 2 });
cart.dispatchEvent(legacy);

// Moderne Variante (empfohlen)
const modern = new CustomEvent('cart:add', {
  bubbles: true,
  detail: { sku: 'B-200', qty: 1 }
});
cart.dispatchEvent(modern);

Artikel A-100 x2 Artikel B-200 x1

Fallback-Hilfsfunktion für alte Browser

// Erzeugt ein CustomEvent – nutzt createEvent nur, wenn der Konstruktor fehlt
const makeCustomEvent = (type, detail = null, bubbles = true) => {
  if (typeof window.CustomEvent === 'function') {
    return new CustomEvent(type, { detail, bubbles, cancelable: true });
  }
  const evt = document.createEvent('CustomEvent');
  evt.initCustomEvent(type, bubbles, true, detail);
  return evt;
};

document.addEventListener('app:ready', (e) => console.log('Bereit:', e.detail));
document.dispatchEvent(makeCustomEvent('app:ready', { version: '1.4.0' }));

Bereit: { version: '1.4.0' }

Nicht unterstützten Namen abfangen

try {
  document.createEvent('click'); // falsch: Event-Typ statt Schnittstelle
} catch (err) {
  console.log(err.name);
}

NotSupportedError

// Wichtig · Fallstricke

Veraltet: createEvent() und die init*Event()-Methoden sind nur noch aus Kompatibilitätsgründen spezifiziert. Nutze in neuem Code Konstruktoren wie new Event(), new CustomEvent() oder new MouseEvent(). Die funktionieren in allen modernen Browsern, nicht aber im Internet Explorer.
Ohne Initialisierung kein Auslösen: Wenn du ein Event ohne vorheriges initEvent() an dispatchEvent() übergibst, wird ein InvalidStateError geworfen.
Häufiger Fehler: Das Argument ist der Name der Schnittstelle ("MouseEvent"), nicht der Event-Typ ("click"). Unbekannte Namen führen zu einem NotSupportedError.
Keine vertrauenswürdigen Events: Selbst erzeugte Events haben immer isTrusted === false. Aktionen, die der Browser nur bei echten Nutzeraktionen erlaubt, lassen sich damit nicht auslösen, z. B. Pop-ups, Vollbild, Zwischenablage oder das Abspielen von Audio.
initMouseEvent() und initKeyboardEvent() haben sehr lange, fehleranfällige Parameterlisten. Außerdem wird initKeyboardEvent() nicht in allen Browsern einheitlich umgesetzt.

Siehe auch

Event Document.createTouch() Document.createElement() Document.createComment() Document.createElementNS()