EventTarget.dispatchEvent() — Methode · JavaScript-Referenz

Signatur

EventTarget.prototype.dispatchEvent(event)

Beschreibung

dispatchEvent() löst ein zuvor erzeugtes Event-Objekt manuell auf einem EventTarget aus – etwa einem DOM-Element, window, document oder einer eigenen Klasse, die von EventTarget erbt. Dabei gelten dieselben Regeln wie bei nativen Events: Capturing-Phase, Target-Phase und – falls bubbles: true gesetzt ist – die Bubbling-Phase.

Der Aufruf ist der letzte Schritt beim Auslösen eines Events. Das Event wird vorher mit einem Konstruktor wie new Event(), new CustomEvent(), new MouseEvent() oder new KeyboardEvent() erzeugt und konfiguriert. Beim Versand setzt der Browser event.target auf das aufrufende Objekt.

Im Gegensatz zu nativen Events, die der Browser über die Event-Loop als Task einreiht, arbeitet dispatchEvent() synchron: Alle Listener laufen durch, bevor die Methode zurückkehrt. Manuell ausgelöste Events haben event.isTrusted === false.

Typische Einsatzgebiete sind eigene Komponenten-Events (z. B. in Web Components), lose gekoppelte Kommunikation zwischen Modulen, das Simulieren von Benutzereingaben in Tests sowie das Auslösen von input/change-Events nach programmatischen Wertänderungen, damit Frameworks die Änderung erkennen.

Parameter

Name	Typ	Default	Beschreibung
$event Pflicht	Event		Das auszulösende Event-Objekt (z. B. `Event`, `CustomEvent`, `MouseEvent`). Es darf nicht gerade in Verarbeitung sein und muss initialisiert sein.

Rückgabewert

Typ

boolean

Beschreibung

false, wenn das Event abbrechbar ist (cancelable: true) und mindestens ein Listener event.preventDefault() aufgerufen hat; sonst true.

Beispiele

Eigenes Event mit CustomEvent und Bubbling

const list = document.createElement('ul');
const item = document.createElement('li');
list.append(item);

// Listener auf dem Elternelement – funktioniert dank bubbles: true
list.addEventListener('item-selected', (e) => {
  console.log('Ausgewählt:', e.detail.id, '| isTrusted:', e.isTrusted);
});

const event = new CustomEvent('item-selected', {
  bubbles: true,
  detail: { id: 42 }
});

item.dispatchEvent(event);

Ausgewählt: 42 | isTrusted: false

Abbrechbares Event und Rückgabewert auswerten

const form = document.createElement('form');

form.addEventListener('before-save', (e) => {
  if (!e.detail.title) {
    e.preventDefault(); // Speichern verhindern
  }
});

const save = (data) => {
  const ok = form.dispatchEvent(new CustomEvent('before-save', {
    cancelable: true,
    detail: data
  }));
  console.log(ok ? 'Gespeichert' : 'Abgebrochen');
};

save({ title: '' });
save({ title: 'Bericht' });

Abgebrochen Gespeichert

Synchrone Ausführung nachweisen

const target = new EventTarget();
target.addEventListener('ping', () => console.log('2: Listener'));

console.log('1: vor dispatchEvent');
target.dispatchEvent(new Event('ping'));
console.log('3: nach dispatchEvent');

1: vor dispatchEvent 2: Listener 3: nach dispatchEvent

input-Event nach programmatischer Wertänderung auslösen

const input = document.createElement('input');
input.addEventListener('input', (e) => console.log('Neuer Wert:', e.target.value));

// Das Setzen von value löst KEIN input-Event aus – daher manuell:
input.value = 'Hallo';
input.dispatchEvent(new Event('input', { bubbles: true }));

Neuer Wert: Hallo

// Wichtig · Fallstricke

Standardmäßig kein Bubbling: new Event('x') hat bubbles: false und cancelable: false. Ohne bubbles: true erreichen Listener auf Elternelementen das Event nicht; ohne cancelable: true bleibt preventDefault() wirkungslos.
Synchron: Ausnahmen in Listenern werden nicht an den Aufrufer weitergegeben, sondern gemeldet (window.onerror/Konsole); die übrigen Listener laufen trotzdem. Lange Listener blockieren den Aufrufer.
Keine Standardaktion: Synthetische Events (isTrusted === false) lösen meist keine Browser-Aktionen aus – z. B. öffnet ein simuliertes keydown keine Texteingabe und ein erzeugtes click startet keine nutzeraktivierungspflichtigen APIs (Popups, Vollbild, Zwischenablage). Ausnahme: click auf Elementen führt die Aktivierung aus (z. B. Link-Navigation, Checkbox-Umschalten); hierfür ist element.click() oft einfacher.
Fehler: InvalidStateError, wenn das Event gerade versendet wird oder nicht initialisiert ist. Ein Event-Objekt kann nach Abschluss erneut versendet werden, sauberer ist aber ein neues Objekt.
Sicherheit: Listener, die sicherheitskritische Aktionen ausführen, sollten event.isTrusted prüfen, da beliebiger Skriptcode Events fälschen kann.
Kompatibilität: In allen modernen Browsern verfügbar. Der EventTarget-Konstruktor (für eigene Ziele) ab Chrome 64, Firefox 59, Safari 14; in Node.js global ab Version 15. Das alte document.createEvent()/initEvent() ist veraltet – Konstruktoren verwenden.

Siehe auch

Event EventTarget.addEventListener() EventTarget.removeEventListener() Event.initEvent() CropTarget.fromElement()