Dokument: visibilitychange-Ereignis

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2021.

Das visibilitychange-Ereignis wird am Dokument ausgelöst, wenn der Inhalt seines Tabs sichtbar wird oder verborgen wird.

Das Ereignis ist nicht abbrechbar.

Syntax

Verwenden Sie den Ereignisnamen in Methoden wie addEventListener(), oder setzen Sie eine Ereignishandler-Eigenschaft.

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

onvisibilitychange = (event) => { }

Ereignistyp

Ein generisches Event.

Verwendungshinweise

Das Ereignis enthält nicht den aktualisierten Sichtbarkeitsstatus des Dokuments, aber Sie können diese Information aus der visibilityState-Eigenschaft des Dokuments abrufen.

Dieses Ereignis wird mit einem visibilityState von hidden ausgelöst, wenn ein Benutzer zu einer neuen Seite navigiert, Tabs wechselt, den Tab schließt, den Browser minimiert oder schließt oder auf mobilen Geräten vom Browser zu einer anderen App wechselt. Der Übergang zu hidden ist das letzte Ereignis, das zuverlässig von der Seite beobachtbar ist, daher sollten Entwickler es als das wahrscheinliche Ende der Benutzersitzung behandeln (zum Beispiel zum Senden von Analysedaten).

Der Übergang zu hidden ist auch ein guter Zeitpunkt, an dem Seiten aufhören können, UI-Aktualisierungen vorzunehmen und alle Aufgaben zu stoppen, die der Benutzer nicht im Hintergrund laufen lassen möchte.

Beispiele

Musik pausieren beim Übergang zu versteckt

Dieses Beispiel pausiert die Wiedergabe von Audio, wenn die Seite versteckt wird und setzt die Wiedergabe fort, wenn die Seite wieder sichtbar wird. Ein vollständiges Beispiel finden Sie in der Dokumentation Page Visibility API: Pausing audio on page hide.

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

Senden von Analysedaten am Ende der Sitzung beim Übergang zu versteckt

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

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

Spezifikationen

Specification
HTML
# event-visibilitychange
HTML
# handler-onvisibilitychange

Browser-Kompatibilität

Siehe auch