Document : évènement visibilitychange

Syntaxe

Utilisez le nom de l'évènement dans des méthodes comme addEventListener(), ou définissez une propriété de gestionnaire d'évènement.

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

onvisibilitychange = (event) => { }

Type d'évènement

Un objet Event générique.

Notes d'utilisation

L'évènement n'inclut pas l'état de visibilité mis à jour du document, mais vous pouvez obtenir cette information à partir de la propriété visibilityState du document.

Cet évènement se déclenche avec un visibilityState qui vaut hidden lorsque l'utilisateur·ice navigue vers une nouvelle page, change d'onglet, ferme l'onglet, minimise ou ferme le navigateur, ou, sur mobile, passe du navigateur à une autre application. La transition vers hidden est le dernier évènement qui peut être observé de manière fiable par la page, donc les développeur·euse·s devraient le considérer comme la fin probable de la session de l'utilisateur·ice (par exemple, pour envoyer des données analytiques).

La transition vers hidden est également un bon moment pour que les pages arrêtent de mettre à jour l'interface utilisateur et interrompent toute tâche que l'utilisateur·ice ne souhaite pas voir s'exécuter en arrière-plan.

Exemples

Mettre la musique en pause lors du passage à l'état caché

Cet exemple met en pause la lecture audio lorsque la page est cachée et reprend la lecture lorsque la page redevient visible. Pour un exemple complet, consultez la documentation L'API Page Visibility : Mettre en pause l'audio lorsque la page est cachée.

document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    playingOnHide = !audio.paused;
    audio.pause();
  } else if (playingOnHide) {
    // Reprendre la lecture si l'audio était « en lecture cachée »
    audio.play();
  }
});

Envoyer des analytiques de fin de session lors de la transition vers l'état caché

Cet exemple considère la transition vers hidden comme la fin de la session de l'utilisateur·ice et envoie les analytiques appropriées en utilisant l'API Navigator.sendBeacon() :

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

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'API Page Visibility
• La propriété Document.visibilityState
• La propriété Document.hidden
• Ne perdez pas l'état de l'utilisateur·ice et de l'application, utilisez Page Visibility ^(angl.) explique en détail pourquoi vous devriez utiliser visibilitychange, et non beforeunload/unload.
• L'API Page Lifecycle ^(angl.) fournit des conseils sur les meilleures pratiques pour gérer le comportement du cycle de vie des pages dans vos applications web.