Document: 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 July 2015.

Das visibilitychange-Ereignis wird bei dem Dokument ausgelöst, wenn die Inhalte seines Tabs sichtbar geworden sind oder versteckt wurden.

Das Ereignis kann nicht abgebrochen werden.

Syntax

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

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

onvisibilitychange = (event) => {};

Ereignistyp

Ein generisches Event.

Hinweise zur Verwendung

Das Ereignis beinhaltet nicht den aktualisierten Sichtbarkeitsstatus des Dokuments, aber Sie können diese Information von der visibilityState-Eigenschaft des Dokuments erhalten.

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 einem mobilen Gerät vom Browser zu einer anderen App wechselt. Der Übergang zu hidden ist das letzte Ereignis, das von der Seite zuverlässig beobachtet werden kann, daher sollten Entwickler es als wahrscheinliches Ende der Benutzersitzung behandeln (zum Beispiel zum Senden von Analysedaten).

Der Übergang zu hidden ist auch ein guter Zeitpunkt, zu dem Seiten UI-Aktualisierungen stoppen und alle Aufgaben anhalten können, die der Benutzer nicht im Hintergrund ausgeführt haben möchte.

Beispiele

Musik beim Wechseln zu verborgen pausieren

Dieses Beispiel pausiert die Wiedergabe von Audio, wenn die Seite verborgen wird und setzt die Wiedergabe fort, wenn die Seite wieder sichtbar wird. Für ein vollständiges Beispiel siehe die Page Visibility API: Pausing audio on page hide Dokumentation.

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 Sitzungsend-Analysen beim Wechseln zu verborgen

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

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

Spezifikationen

Specification
HTML Standard
# event-visibilitychange
HTML Standard
# handler-onvisibilitychange

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch