DOM-Ereignisse

Ereignisse werden ausgelöst, um den Code über "interessante Veränderungen" zu informieren, die die Codeausführung beeinflussen könnten. Diese können durch Benutzerinteraktionen wie Mausbenutzung oder Größenänderung eines Fensters, Änderungen im Zustand der zugrunde liegenden Umgebung (z.B. niedriger Akkustand oder Medienereignisse des Betriebssystems) und andere Ursachen entstehen.

Jedes Ereignis wird durch ein Objekt repräsentiert, das auf der Event-Schnittstelle basiert und zusätzliche benutzerdefinierte Felder und/oder Funktionen enthalten kann, um Informationen darüber bereitzustellen, was passiert ist. Die Dokumentation für jedes Ereignis enthält eine Tabelle (nahe am Anfang), die einen Link zur zugehörigen Ereignisschnittstelle und andere relevante Informationen enthält. Eine vollständige Liste der verschiedenen Ereignistypen finden Sie unter Event > Interfaces based on Event.

Dieses Thema bietet einen Index zu den Hauptarten von Ereignissen, die Sie interessieren könnten (Animation, Zwischenablage, Worker etc.) sowie die Hauptklassen, die diese Arten von Ereignissen implementieren.

Ereignisindex

Ereignistyp	Beschreibung	Dokumentation
Animation	Ereignisse im Zusammenhang mit der Web Animation API. Wird verwendet, um auf Änderungen im Animationsstatus zu reagieren (z.B. wenn eine Animation startet oder endet).	Animation-Ereignisse werden auf `Document`, `Window`, `HTMLElement` ausgelöst.
Asynchrones Laden von Daten	Ereignisse im Zusammenhang mit dem Laden von Daten.	Ereignisse werden auf `AbortSignal`, `XMLHttpRequest`, `FileReader` ausgelöst.
Zwischenablage	Ereignisse im Zusammenhang mit der Clipboard API. Wird verwendet, um zu benachrichtigen, wenn Inhalt ausgeschnitten, kopiert oder eingefügt wird.	Ereignisse werden auf `Document`, `Element`, `Window` ausgelöst.
Komposition	Ereignisse im Zusammenhang mit Komposition; Eingabe von Text "indirekt" (anstatt durch normale Tastatureingaben). Zum Beispiel Text, der über eine Sprache-zu-Text-Engine eingegeben wird, oder mit speziellen Tastenkombinationen, die die Tastatureingaben verändern, um neue Zeichen in einer anderen Sprache darzustellen.	Ereignisse werden auf `Element` ausgelöst.
CSS-Übergang	Ereignisse im Zusammenhang mit CSS-Übergängen. Bietet Benachrichtigungsereignisse, wenn CSS-Übergänge starten, stoppen, abgebrochen werden etc.	Ereignisse werden auf `Document`, `HTMLElement`, `Window` ausgelöst.
Datenbank	Ereignisse im Zusammenhang mit Datenbankoperationen: Öffnen, Schließen, Transaktionen, Fehler etc.	Ereignisse werden auf `IDBDatabase`, `IDBOpenDBRequest`, `IDBRequest`, `IDBTransaction` ausgelöst.
DOM-Veränderung	Ereignisse im Zusammenhang mit Änderungen an der Document Object Model (DOM)-Hierarchie und den Knoten.	Warnung: Veränderungsereignisse sind veraltet. Mutations-Beobachter sollten stattdessen verwendet werden.
Drag'n'Drop, Maus-Rad	Ereignisse im Zusammenhang mit der Verwendung der HTML Drag and Drop API und Rad-Ereignisse. Drag- und Rad-Ereignisse stammen von Mausereignissen ab. Während sie bei der Verwendung des Mausrads oder beim Ziehen/Ablegen ausgelöst werden, können sie auch mit anderer geeigneter Hardware verwendet werden.	Drag-Ereignisse werden auf `Document` ausgelöst. Rad-Ereignisse werden auf `Element` ausgelöst.
Fokus	Ereignisse im Zusammenhang mit dem Erlangen und dem Verlust des Fokus von Elementen.	Ereignisse werden auf `Element`, `Window` ausgelöst.
Formular	Ereignisse im Zusammenhang mit Formularen, die erstellt, zurückgesetzt und gesendet werden.	Ereignisse werden auf `HTMLFormElement` ausgelöst.
Vollbild	Ereignisse im Zusammenhang mit der Fullscreen API. Wird verwendet, um den Übergang zwischen Vollbild- und Fenstermodus sowie Fehler bei diesem Übergang zu benachrichtigen.	Ereignisse werden auf `Document`, `Element` ausgelöst.
Gamepad	Ereignisse im Zusammenhang mit der Gamepad API.	Ereignisse werden auf `Window` ausgelöst.
Gesten	Touch-Ereignisse werden empfohlen, um Gesten zu implementieren.	Ereignisse werden auf `Document`, `Element` ausgelöst. Zusätzlich gibt es eine Reihe nicht-standardisierter Gestenereignisse: Nicht-standardmäßige WebKit-spezifische Ereignisse auf `Element`: `gesturestart`-Ereignis, `gesturechange`-Ereignis, `gestureend`-Ereignis.
Verlauf	Ereignisse im Zusammenhang mit der History API.	Ereignisse werden auf `Window` ausgelöst.
Verwaltung der Darstellung von HTML-Elementinhalten	Ereignisse im Zusammenhang mit der Änderung des Zustands eines Anzeige- oder Textelements.	Ereignisse werden auf `HTMLDetailsElement`, `HTMLDialogElement`, `HTMLSlotElement` ausgelöst.
Eingaben	Ereignisse im Zusammenhang mit HTML-Eingabenelementen wie `<input>`, `<select>`, oder `<textarea>`.	Ereignisse werden auf `HTMLElement`, `HTMLInputElement` ausgelöst.
Tastatur	Ereignisse im Zusammenhang mit der Verwendung einer Tastatur. Wird verwendet, um zu benachrichtigen, wenn Tasten heruntergedrückt, losgelassen oder einfach gedrückt werden.	Ereignisse werden auf `Document`, `Element` ausgelöst.
Laden/Entladen von Dokumenten	Ereignisse im Zusammenhang mit dem Laden und Entladen von Dokumenten.	Ereignisse werden auf `Document` und `Window` ausgelöst.
Manifeste	Ereignisse im Zusammenhang mit der Installation von Progressive-Web-App-Manifesten.	Ereignisse werden auf `Window` ausgelöst.
Medien	Ereignisse im Zusammenhang mit der Mediennutzung (einschließlich der Media Capture and Streams API, Web Audio API, Picture-in-Picture API, etc.).	Ereignisse werden auf `ScriptProcessorNode`, `HTMLMediaElement`, `AudioTrackList`, `AudioScheduledSourceNode`, `MediaRecorder`, `MediaStream`, `MediaStreamTrack`, `VideoTrackList`, `HTMLTrackElement`, `OfflineAudioContext`, `TextTrack`, `TextTrackList`, Element/audio, Element/video ausgelöst.
Nachrichtenübermittlung	Ereignisse im Zusammenhang mit einem Fenster, das eine Nachricht von einem anderen Browsing-Kontext empfängt.	Ereignisse werden auf `Window` ausgelöst.
Maus	Ereignisse im Zusammenhang mit der Verwendung einer Computermaus. Wird verwendet, um zu benachrichtigen, wenn die Maus geklickt, doppelt geklickt, hoch und herunter bewegt wird, Rechtsklick, Bewegung in und aus einem Element, Textauswahl etc. Pointer-Ereignisse bieten eine hardwareunabhängige Alternative zu Mausereignissen. Drag- und Rad-Ereignisse leiten sich von Mausereignissen ab.	Mausereignisse werden auf `Element` ausgelöst.
Netzwerk/Verbindung	Ereignisse im Zusammenhang mit Gewinnen und Verlieren der Netzwerkverbindung.	Ereignisse werden auf `Window` ausgelöst. Ereignisse werden auf `NetworkInformation` (Netzwerk-Informations-API) ausgelöst.
Zahlungen	Ereignisse im Zusammenhang mit der Payment Request API.	Ereignisse werden auf `PaymentRequest`, `PaymentResponse` ausgelöst.
Leistung	Ereignisse im Zusammenhang mit jeder leistungsbezogenen Spezifikation, die in Performance-APIs gruppiert ist.	Ereignisse werden auf `Performance` ausgelöst.
Zeiger	Ereignisse im Zusammenhang mit der Pointer Events API. Bietet hardwareunabhängige Benachrichtigungen von Zeigegeräten, einschließlich Maus, Touch, Stift/Zeichengerät.	Ereignisse werden auf `Document`, `HTMLElement` ausgelöst.
Drucken	Ereignisse im Zusammenhang mit dem Drucken.	Ereignisse werden auf `Window` ausgelöst.
Promise-Ablehnung	Ereignisse, die an das globale Skriptkontext gesendet werden, wenn ein JavaScript-Promise abgelehnt wird.	Ereignisse werden auf `Window` ausgelöst.
Sockets	Ereignisse im Zusammenhang mit der WebSockets API.	Ereignisse werden auf `WebSocket` ausgelöst.
SVG	Ereignisse im Zusammenhang mit SVG-Bildern.	Ereignisse werden auf `SVGElement`, `SVGAnimationElement`, `SVGGraphicsElement` ausgelöst.
Textauswahl	Auswahl-API-Ereignisse im Zusammenhang mit der Textauswahl.	Ereignis (`selectionchange`) ausgelöst auf [`HTMLTextAreaElement`](/de/docs/Web/API/HTMLTextAreaElement/selectionchange_event), [`HTMLInputElement`](/de/docs/Web/API/HTMLInputElement/selectionchange_event).
Touch	Ereignisse im Zusammenhang mit der Touch Events API. Bietet Benachrichtigungsereignisse beim Interagieren mit einem berührungsempfindlichen Bildschirm (d.h. mit einem Finger oder Stift). Nicht im Zusammenhang mit der Force Touch API.	Ereignisse werden auf `Document`, `Element` ausgelöst.
Virtuelle Realität	Ereignisse im Zusammenhang mit der WebXR Device API. Warnung: Die WebVR API (und zugehörige `Window`-Ereignisse) sind veraltet.	Ereignisse werden auf `XRSystem`, `XRSession`, `XRReferenceSpace` ausgelöst.
RTC (Echtzeitkommunikation)	Ereignisse im Zusammenhang mit der WebRTC API.	Ereignisse werden auf `RTCDataChannel`, `RTCDTMFSender`, `RTCIceTransport`, `RTCPeerConnection` ausgelöst.
Server-gesendete Ereignisse	Ereignisse im Zusammenhang mit der Server-gesendete Ereignisse API.	Ereignisse werden auf `EventSource` ausgelöst.
Sprache	Ereignisse im Zusammenhang mit der Web Speech API.	Ereignisse werden auf `SpeechSynthesisUtterance` ausgelöst.
Worker	Ereignisse im Zusammenhang mit der Web Workers API, Service Worker API, Broadcast Channel API und Channel Messaging API. Wird verwendet, um auf neue Nachrichten und Fehler beim Senden von Nachrichten zu reagieren. Service Worker können auch über andere Ereignisse benachrichtigt werden, einschließlich Push-Benachrichtigungen, Benutzern, die auf angezeigte Benachrichtigungen klicken, dass die Push-Abonnements ungültig geworden sind, das Löschen von Elementen aus dem Inhaltsverzeichnis usw.	Ereignisse werden auf `ServiceWorkerGlobalScope`, `DedicatedWorkerGlobalScope`, `SharedWorkerGlobalScope`, `WorkerGlobalScope`, `Worker`, `BroadcastChannel`, `MessagePort` ausgelöst.

Erstellen und Auslösen von Ereignissen

Zusätzlich zu den von integrierten Schnittstellen ausgelösten Ereignissen, können Sie DOM-Ereignisse selbst erstellen und auslösen. Solche Ereignisse werden häufig als synthetische Ereignisse bezeichnet, im Gegensatz zu den vom Browser ausgelösten Ereignissen.

Erstellen benutzerdefinierter Ereignisse

Ereignisse können mit dem Event-Konstruktor wie folgt erstellt werden:

const event = new Event("build");

// Listen for the event.
elem.addEventListener(
  "build",
  (e) => {
    /* … */
  },
  false,
);

// Dispatch the event.
elem.dispatchEvent(event);

Dieses Codebeispiel verwendet die Methode EventTarget.dispatchEvent().

Hinzufügen benutzerdefinierter Daten – CustomEvent()

Um dem Ereignisobjekt mehr Daten hinzuzufügen, existiert die CustomEvent-Schnittstelle und die detail-Eigenschaft kann verwendet werden, um benutzerdefinierte Daten zu übergeben. Zum Beispiel könnte das Ereignis wie folgt erstellt werden:

const event = new CustomEvent("build", { detail: elem.dataset.time });

Dies ermöglicht es Ihnen dann, auf die zusätzlichen Daten im Ereignislistener zuzugreifen:

function eventHandler(e) {
  console.log(`The time is: ${e.detail}`);
}

Hinzufügen benutzerdefinierter Daten – Vererben von Event

Die Event-Schnittstelle kann auch vererbt werden. Dies ist besonders nützlich zur Wiederverwendung, für komplexere benutzerdefinierte Daten oder sogar zum Hinzufügen von Methoden zum Ereignis.

class BuildEvent extends Event {
  #buildTime;

  constructor(buildTime) {
    super("build");
    this.#buildTime = buildTime;
  }

  get buildTime() {
    return this.#buildTime;
  }
}

Dieses Codebeispiel definiert eine BuildEvent-Klasse mit einer schreibgeschützten Eigenschaft und einem festen Ereignistyp.

Das Ereignis könnte dann wie folgt erstellt werden:

const event = new BuildEvent(elem.dataset.time);

Die zusätzlichen Daten können dann in den Ereignis-Listenern über die benutzerdefinierten Eigenschaften angesprochen werden:

function eventHandler(e) {
  console.log(`The time is: ${e.buildTime}`);
}

Ereignis-Bubbling

Es ist oft wünschenswert, ein Ereignis von einem Kindelement auszulösen und einen Vorfahren es auffangen zu lassen; optional können Sie Daten mit dem Ereignis einschließen:

html

<form>
  <textarea></textarea>
</form>

const form = document.querySelector("form");
const textarea = document.querySelector("textarea");

// Create a new event, allow bubbling, and provide any data you want to pass to the "detail" property
const eventAwesome = new CustomEvent("awesome", {
  bubbles: true,
  detail: { text: () => textarea.value },
});

// The form element listens for the custom "awesome" event and then consoles the output of the passed text() method
form.addEventListener("awesome", (e) => console.log(e.detail.text()));

// As the user types, the textarea inside the form dispatches/triggers the event to fire, using itself as the starting point
textarea.addEventListener("input", (e) => e.target.dispatchEvent(eventAwesome));

Ereignisse dynamisch erstellen und auslösen

Elemente können auf Ereignisse hören, die noch nicht erstellt wurden:

html

<form>
  <textarea></textarea>
</form>

const form = document.querySelector("form");
const textarea = document.querySelector("textarea");

form.addEventListener("awesome", (e) => console.log(e.detail.text()));

textarea.addEventListener("input", function () {
  // Create and dispatch/trigger an event on the fly
  // Note: Optionally, we've also leveraged the "function expression" (instead of the "arrow function expression") so "this" will represent the element
  this.dispatchEvent(
    new CustomEvent("awesome", {
      bubbles: true,
      detail: { text: () => textarea.value },
    }),
  );
});

Auslösen eingebauter Ereignisse

Dieses Beispiel zeigt, wie man einen Klick simuliert (d.h. ein Klickereignis programmatisch erzeugt) auf ein Kontrollkästchen mit DOM-Methoden. Sehen Sie sich das Beispiel in Aktion an.

function simulateClick() {
  const event = new MouseEvent("click", {
    view: window,
    bubbles: true,
    cancelable: true,
  });
  const cb = document.getElementById("checkbox");
  const cancelled = !cb.dispatchEvent(event);

  if (cancelled) {
    // A handler called preventDefault.
    alert("cancelled");
  } else {
    // None of the handlers called preventDefault.
    alert("not cancelled");
  }
}

Registrieren von Ereignishandlern

Es gibt zwei empfohlene Ansätze zum Registrieren von Handlern. Der Code des Ereignishandlers kann entweder ausgeführt werden, indem er der entsprechenden onevent-Eigenschaft des Zielelements zugewiesen wird, oder indem der Handler als Listener für das Element mit der Methode addEventListener() registriert wird. In jedem Fall erhält der Handler ein Objekt, das der Event-Schnittstelle (oder einer abgeleiteten Schnittstelle) entspricht. Der Hauptunterschied besteht darin, dass mit den Ereignislistener-Methoden mehrere Ereignishandler hinzugefügt (oder entfernt) werden können.

Warnung: Ein dritter Ansatz zur Einstellung von Ereignishandlern unter Verwendung von HTML-Onevent-Attributen wird nicht empfohlen! Sie blähen das Markup auf und machen es weniger lesbar sowie schwerer zu debuggen. Weitere Informationen finden Sie unter Inline-Ereignishandler.

Verwendung von Onevent-Eigenschaften

Nach Konvention haben JavaScript-Objekte, die Ereignisse auslösen, entsprechende "onevent"-Eigenschaften (benannt durch Voranstellen von "on" an den Namen des Ereignisses). Diese Eigenschaften werden aufgerufen, um den zugehörigen Handler-Code auszuführen, wenn das Ereignis ausgelöst wird, und können auch direkt von Ihrem eigenen Code aufgerufen werden.

Um den Code des Ereignishandlers festzulegen, können Sie ihn einfach der entsprechenden Onevent-Eigenschaft zuweisen. Für jedes Ereignis in einem Element kann nur ein Ereignishandler zugewiesen werden. Bei Bedarf kann der Handler durch Zuweisung einer anderen Funktion zur gleichen Eigenschaft ersetzt werden.

Das folgende Beispiel zeigt, wie eine greet()-Funktion für das click-Ereignis unter Verwendung der onclick-Eigenschaft festgelegt wird.

const btn = document.querySelector("button");

function greet(event) {
  console.log("greet:", event);
}

btn.onclick = greet;

Beachten Sie, dass ein Objekt, das das Ereignis darstellt, als erstes Argument an den Ereignishandler übergeben wird. Dieses Ereignisobjekt implementiert entweder oder ist abgeleitet von der Event-Schnittstelle.

EventTarget.addEventListener

Die flexibelste Möglichkeit, einen Ereignishandler auf einem Element festzulegen, besteht darin, die EventTarget.addEventListener-Methode zu verwenden. Dieser Ansatz ermöglicht es, mehrere Listener an ein Element zuzuweisen und Listener bei Bedarf zu entfernen, indem EventTarget.removeEventListener verwendet wird.

Hinweis: Die Fähigkeit, Ereignishandler hinzuzufügen und zu entfernen, ermöglicht es Ihnen beispielsweise, dass derselbe Button in verschiedenen Umständen unterschiedliche Aktionen ausführt. Zusätzlich kann das Bereinigen alter/nicht verwendeter Ereignishandler in komplexeren Programmen die Effizienz verbessern.

Das folgende Beispiel zeigt, wie eine greet()-Funktion als Listener/Ereignishandler für das click-Ereignis festgelegt werden kann (Sie könnten einen anonymen Funktionsausdruck anstelle einer benannten Funktion verwenden, wenn gewünscht). Beachten Sie erneut, dass das Ereignis als erstes Argument an den Ereignishandler übergeben wird.

const btn = document.querySelector("button");

function greet(event) {
  console.log("greet:", event);
}

btn.addEventListener("click", greet);

Die Methode kann auch zusätzliche Argumente/Optionen entgegennehmen, um Aspekte der Erfassung und Entfernung der Ereignisse zu steuern. Weitere Informationen finden Sie auf der Referenzseite zu EventTarget.addEventListener.

Verwendung von AbortSignal

Eine bemerkenswerte Funktion des Ereignis-Listeners ist die Fähigkeit, ein Abbruchsignal zu verwenden, um mehrere Ereignishandler gleichzeitig zu bereinigen.

Dies wird erreicht, indem dasselbe AbortSignal an den addEventListener()-Aufruf für alle Ereignishandler übergeben wird, die Sie zusammen entfernen möchten. Sie können dann abort() auf dem Controller aufrufen, der das AbortSignal besitzt, und es wird alle Ereignishandler entfernen, die mit diesem Signal hinzugefügt wurden. Um beispielsweise einen Ereignishandler hinzuzufügen, den wir mit einem AbortSignal entfernen können:

const controller = new AbortController();

btn.addEventListener(
  "click",
  (event) => {
    console.log("greet:", event);
  },
  { signal: controller.signal },
); // pass an AbortSignal to this handler

Dieser Ereignishandler kann dann so entfernt werden:

controller.abort(); // removes any/all event handlers associated with this controller

Spezifikationen

Specification
DOM # events
HTML # events-2