Event — Schnittstelle · JavaScript-Referenz

Signatur

interface Event

Beschreibung

Event ist die Basisschnittstelle für alle Ereignisse im DOM. Klicks, Tastendrücke, Formularübermittlungen, Ladevorgänge und Netzwerkereignisse werden als Objekte vom Typ Event oder einer abgeleiteten Schnittstelle wie MouseEvent, KeyboardEvent, InputEvent oder CustomEvent dargestellt. Jeder Listener, den du mit addEventListener() registrierst, bekommt so ein Objekt als erstes Argument.

Die wichtigsten Eigenschaften sind type (Name des Ereignisses), target (das ursprüngliche Ziel), currentTarget (das Element, dessen Listener gerade läuft), eventPhase, bubbles, cancelable, defaultPrevented, isTrusted und timeStamp. Mit den Methoden preventDefault(), stopPropagation(), stopImmediatePropagation() und composedPath() steuerst du die Standardaktion und die Weitergabe durch den DOM-Baum.

Ein Ereignis durchläuft drei Phasen: die Capture-Phase (vom window hinunter zum Ziel), die Target-Phase und die Bubbling-Phase (vom Ziel wieder nach oben), wobei Letztere nur stattfindet, wenn bubbles auf true steht. Darauf beruht die Ereignisdelegation: ein einzelner Listener auf einem Elternelement wertet über event.target die Ereignisse vieler Kindelemente aus.

Mit new Event(type, options) erzeugst du eigene Ereignisse und löst sie mit EventTarget.dispatchEvent() aus. Wenn du Daten mitschicken willst, nimm stattdessen CustomEvent mit der Eigenschaft detail.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"click"` oder ein eigener Name wie `"cart:updated"`. Groß- und Kleinschreibung wird unterschieden.
$options	object	{}	Optionales Konfigurationsobjekt (`EventInit`) für den Konstruktor.
$options.bubbles	boolean	false	Legt fest, ob das Ereignis durch den DOM-Baum nach oben weitergegeben wird.
$options.cancelable	boolean	false	Legt fest, ob sich das Ereignis mit `preventDefault()` abbrechen lässt.
$options.composed	boolean	false	Legt fest, ob das Ereignis die Grenze eines Shadow DOM in das umgebende (Light) DOM überschreitet.

Rückgabewert

Typ

Event

Beschreibung

Ein neues Event-Objekt, das du mit dispatchEvent() auslösen kannst. Es hat isTrusted === false.

Beispiele

Eigenschaften eines Ereignisses im Listener auslesen

const button = document.querySelector('#speichern');

button.addEventListener('click', (event) => {
  console.log(event.type);                    // Ereignisname
  console.log(event.target === button);       // ursprüngliches Ziel
  console.log(event.currentTarget === button);
  console.log(event.bubbles, event.cancelable);
  console.log(event.isTrusted);               // true bei echter Benutzeraktion
});

click true true true true true

Standardaktion verhindern: Formular per fetch absenden

const form = document.querySelector('#kontakt');

form.addEventListener('submit', async (event) => {
  event.preventDefault(); // kein Neuladen der Seite
  console.log(event.defaultPrevented);

  const response = await fetch('/api/kontakt', {
    method: 'POST',
    body: new FormData(form),
  });
  console.log(response.ok ? 'Gesendet' : 'Fehler');
});

true Gesendet

Ereignisdelegation mit target und closest()

const liste = document.querySelector('#todo-liste');

liste.addEventListener('click', (event) => {
  const loeschen = event.target.closest('button.loeschen');
  if (!loeschen || !liste.contains(loeschen)) return;

  event.stopPropagation(); // nicht an Eltern weitergeben
  loeschen.closest('li').remove();
  console.log('Eintrag entfernt');
});

Eintrag entfernt

Eigenes Ereignis erzeugen und auslösen

const panel = document.querySelector('#panel');

document.body.addEventListener('panel:close', (event) => {
  console.log(`Empfangen von #${event.target.id}, Phase ${event.eventPhase}`);
});

const closeEvent = new Event('panel:close', { bubbles: true, cancelable: true });
const nichtAbgebrochen = panel.dispatchEvent(closeEvent);

console.log(nichtAbgebrochen, closeEvent.isTrusted);

Empfangen von #panel, Phase 3 true false

// Wichtig · Fallstricke

target und currentTarget: target ist das Element, auf dem das Ereignis ursprünglich ausgelöst wurde, oft ein Kindelement. currentTarget ist das Element, an dem der Listener hängt. Nach Ende der Weitergabe steht currentTarget auf null. Wenn du den Wert asynchron brauchst, speichere ihn vorher in einer Variablen.
preventDefault() wirkt nur, wenn cancelable auf true steht. In Listenern, die mit { passive: true } registriert sind (bei touchstart/wheel auf window/document in Chrome standardmäßig), wird der Aufruf ignoriert und erzeugt eine Warnung in der Konsole.
stopPropagation() hält die Weitergabe an andere Elemente an. stopImmediatePropagation() verhindert zusätzlich, dass weitere Listener auf demselben Element aufgerufen werden. Setze beides sparsam ein, denn es kann Analyse-Skripte oder Delegation an anderen Stellen stören.
Selbst erzeugte Ereignisse haben isTrusted === false. Browser lösen dafür keine geschützten Standardaktionen aus, zum Beispiel öffnet sich bei einem künstlichen click kein Popup ohne Benutzergeste. Für sicherheitsrelevante Prüfungen kannst du isTrusted auswerten.
Ein Ereignisobjekt, das gerade ausgelöst wird, lässt sich nicht noch einmal per dispatchEvent() auslösen (InvalidStateError). Erzeuge für jede Auslösung ein neues Objekt.
Bei new Event() stehen bubbles und cancelable standardmäßig auf false. Ohne bubbles: true funktioniert Delegation mit eigenen Ereignissen nicht.
Veraltet: document.createEvent() + initEvent(), event.returnValue, event.srcElement und cancelBubble. Nimm stattdessen den Konstruktor, preventDefault(), target und stopPropagation(). Der Event-Konstruktor fehlt nur im Internet Explorer. In Node.js gibt es Event und EventTarget global ab Version 15.

Siehe auch

UIEvent Client Element Point Text