Window: beforeunload-Ereignis

Syntax

Verwenden Sie den Ereignisnamen in Methoden wie addEventListener() oder setzen Sie eine Ereignisbehandlungseigenschaft.

addEventListener("beforeunload", (event) => { })

onbeforeunload = (event) => { }

Ereignistyp

Ein BeforeUnloadEvent. Es erbt von Event.

Hinweise zur Verwendung

Damit der Dialog angezeigt wird, wenn Benutzer den Tab schließen oder zu einer anderen Seite navigieren, sollte eine beforeunload-Ereignisbehandlungsfunktion preventDefault() auf dem Ereignisobjekt aufrufen. Beachten Sie, dass aktuelle Implementierungen:

• eine sticky activation voraussetzen, damit der Dialog angezeigt wird. Das bedeutet, dass der Browser den Dialog nur anzeigt, wenn im Frame oder in einem eingebetteten Frame eine Benutzergeste oder -interaktion stattgefunden hat. Wenn Benutzer nie mit der Seite interagiert haben, gibt es keine Benutzerdaten zu speichern und damit keinen berechtigten Anwendungsfall für den Dialog.
• im angezeigten Dialog nur einen generischen, vom Browser festgelegten Text ausgeben. Der Code der Webseite kann diesen Text nicht beeinflussen.

Das beforeunload-Ereignis bringt einige Probleme mit sich:

• Es wird nicht zuverlässig ausgelöst, insbesondere auf Mobilgeräten. Im folgenden Szenario wird das beforeunload-Ereignis beispielsweise überhaupt nicht ausgelöst:

  1. Ein Benutzer ruft Ihre Seite auf einem Mobilgerät auf.
  2. Anschließend wechselt der Benutzer zu einer anderen App.
  3. Später schließt der Benutzer den Browser über die App-Verwaltung.

  Hinweis: Es wird empfohlen, das visibilitychange-Ereignis als zuverlässigeres Signal zum automatischen Speichern des App-Zustands zu verwenden. Damit lassen sich Probleme wie das oben beschriebene umgehen. Weitere Informationen finden Sie unter Benutzer- und App-Zustand nicht verlieren: Page Visibility verwenden.

• In Firefox ist beforeunload nicht mit dem back/forward cache (bfcache) kompatibel: Firefox nimmt Seiten mit beforeunload-Listenern nicht in den bfcache auf, was sich negativ auf die Leistung auswirkt.

Daher wird Entwicklern empfohlen, nur dann auf beforeunload zu reagieren, wenn Benutzer nicht gespeicherte Änderungen haben. In diesem Fall kann der oben beschriebene Dialog sie vor einem drohenden Datenverlust warnen. Entfernen Sie den Listener wieder, sobald er nicht mehr benötigt wird. Ein sparsamer Einsatz von beforeunload-Listenern kann die Auswirkungen auf die Leistung minimieren.

Aliasse für die Ereignisbehandlung

Neben der Window-Schnittstelle steht die Ereignisbehandlungseigenschaft onbeforeunload auch für folgende Ziele zur Verfügung:

• HTMLBodyElement
• HTMLFrameSetElement
• SVGSVGElement

Beispiele

Im folgenden Beispiel verwenden wir ein HTML-Textfeld <input> für Daten, die geändert werden können und anschließend gespeichert werden müssen:

<input type="text" name="name" id="name" />

Unser JavaScript fügt dem <input>-Element einen input-Event-Listener hinzu, der auf Änderungen des eingegebenen Werts reagiert. Sobald der Wert nicht mehr leer ist, wird dem Window-Objekt ein beforeunload-Event-Listener hinzugefügt.

Wird der Wert wieder zu einer leeren Zeichenfolge, etwa weil er gelöscht wird, entfernen wir den beforeunload-Event-Listener wieder. Wie oben in den Hinweisen zur Verwendung beschrieben, sollte der Listener entfernt werden, wenn keine nicht gespeicherten Daten vorliegen, vor deren Verlust gewarnt werden muss.

Die beforeunload-Ereignisbehandlungsfunktion ruft event.preventDefault() auf, um den Warndialog auszulösen, wenn Benutzer den Tab schließen oder zu einer anderen Seite navigieren. Wir haben außerdem event.returnValue = true in die Funktion aufgenommen, damit die Demo auch in Browsern funktioniert, die den event.preventDefault()-Mechanismus nicht unterstützen.

const beforeUnloadHandler = (event) => {
  // Recommended
  event.preventDefault();

  // Included for legacy support, e.g. Chrome/Edge < 119
  event.returnValue = true;
};

const nameInput = document.querySelector("#name");

nameInput.addEventListener("input", (event) => {
  if (event.target.value !== "") {
    window.addEventListener("beforeunload", beforeUnloadHandler);
  } else {
    window.removeEventListener("beforeunload", beforeUnloadHandler);
  }
});

Wenn der Wert von <input> nicht leer ist, zeigt der Browser einen Warndialog an, sobald Sie versuchen, die Seite zu schließen, zu einer anderen Seite zu navigieren oder die Seite neu zu laden. Probieren Sie es aus:

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Die Schnittstelle BeforeUnloadEvent
• Verwandte Ereignisse:
  • DOMContentLoaded
  • readystatechange
  • load
  • unload
• Die Page Lifecycle API bietet weitere hilfreiche Hinweise zum Umgang mit dem Lebenszyklus von Seiten in Ihren Web-Apps.