Dokument: visibilitychange-Ereignis

Syntax

Verwenden Sie den Ereignisnamen in addEventListener():

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

Alternativ können Sie ihn der Event-Handler-Eigenschaft des Interfaces zuweisen:

onvisibilitychange = (event) => { }

Ereignistyp

Ein generisches Event.

Hinweise zur Verwendung

Das Ereignis enthält nicht den aktualisierten Sichtbarkeitsstatus des Dokuments. Sie können diese Information jedoch über die Eigenschaft visibilityState des Dokuments abrufen.

Dieses Ereignis wird mit einem visibilityState von hidden ausgelöst, wenn ein Benutzer eine neue Seite aufruft, den Tab wechselt oder schließt, den Browser minimiert oder schließt oder auf einem Mobilgerät vom Browser zu einer anderen App wechselt. Der Übergang zu hidden ist das letzte Ereignis, das die Seite zuverlässig beobachten kann. Entwickler sollten ihn daher als wahrscheinliches Ende der Benutzersitzung behandeln, beispielsweise um Analysedaten zu senden.

Der Übergang zu hidden ist auch ein guter Zeitpunkt, um Aktualisierungen der Benutzeroberfläche und Aufgaben anzuhalten, die der Benutzer nicht im Hintergrund weiterlaufen lassen möchte.

Beispiele

Musikwiedergabe beim Übergang zu hidden pausieren

Dieses Beispiel pausiert die Audiowiedergabe, wenn die Seite ausgeblendet wird, und setzt sie fort, sobald die Seite wieder sichtbar ist. Ein vollständiges Beispiel finden Sie in der Dokumentation zur Page Visibility API: Audiowiedergabe beim Ausblenden der Seite pausieren.

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    playingOnHide = !audio.paused;
    audio.pause();
  } else if (playingOnHide) {
    // Resume playing if audio was "playing on hide"
    audio.play();
  }
});

Analysedaten zum Sitzungsende beim Übergang zu hidden senden

Dieses Beispiel behandelt den Übergang zu hidden als Ende der Benutzersitzung und sendet die entsprechenden Analysedaten über die API Navigator.sendBeacon():

document.onvisibilitychange = () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
};

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Page Visibility API
• Document.visibilityState
• Document.hidden
• Benutzer- und Anwendungsstatus nicht verlieren: Page Visibility verwenden erklärt ausführlich, warum Sie visibilitychange statt beforeunload/unload verwenden sollten.
• Page Lifecycle API bietet Empfehlungen für den Umgang mit dem Seitenlebenszyklus in Ihren Webanwendungen.