Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Cycle de vie d’une page : visibilité, départ et retour

Distinguez un onglet masqué, une tentative de quitter la page et une restauration depuis le cache de navigation pour enregistrer l’état, avertir ou reprendre une tâche au bon moment.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

document.addEventListener('visibilitychange', onVisibilityChange); // Read document.visibilityState or document.hidden.
window.addEventListener('beforeunload', onBeforeUnload); // Register only while unsaved changes exist.
window.removeEventListener('beforeunload', onBeforeUnload); // Remove the same listener once changes are saved or discarded.
window.addEventListener('pagehide', onPageHide); // Read event.persisted.
window.addEventListener('pageshow', onPageShow); // Read event.persisted.

Ces quatre événements relèvent de la plateforme web, pas d’ECMAScript 2024. Leur prise en charge et leur comportement varient selon le navigateur et la situation. Ne supposez pas qu’ils se déclencheront tous dans un ordre fixe.

Écoutez visibilitychange sur document. Cet événement n’est pas annulable. Lisez document.visibilityState (visible ou hidden) ou le booléen document.hidden. Changer d’onglet peut masquer la page sans la quitter. Enregistrez l’état au fil du travail et considérez le passage à hidden comme le meilleur signal pour un dernier enregistrement ou une mise en pause, pas comme la preuve que la session est terminée.

Sur window, beforeunload est un événement BeforeUnloadEvent annulable, lié à une tentative de quitter, de recharger ou de fermer la page. Pour demander une confirmation, appelez event.preventDefault() et définissez event.returnValue sur une chaîne non vide pour la compatibilité avec d’anciens navigateurs. Renvoyer une valeur ne fonctionne qu’avec onbeforeunload, pas avec addEventListener(). La boîte de dialogue exige une interaction utilisateur préalable admissible (sticky activation) ; le navigateur peut l’omettre et choisit son texte. N’ajoutez l’écouteur que tant qu’il existe des modifications non enregistrées et retirez-le après leur enregistrement ou leur abandon : il peut empêcher l’utilisation du bfcache, notamment dans Firefox.

pagehide et pageshow sont des événements PageTransitionEvent non annulables sur window. Au départ, pagehide avec event.persisted === true signifie que le navigateur compte conserver le document en mémoire pour la navigation arrière/avant (bfcache), sans garantir sa restauration. false signifie qu’il ne compte pas le conserver. Utilisez pagehide pour mettre des ressources en pause, non pour enregistrer des données critiques : cet événement et beforeunload peuvent manquer, par exemple si un système mobile arrête le navigateur en arrière-plan.

Au chargement initial, pageshow suit load avec persisted === false. La valeur true indique que le même document a effectivement été restauré depuis le bfcache : reprenez les tâches suspendues et actualisez les données susceptibles d’être périmées. pageshow ne prouve pas que l’utilisateur voit la page ; il peut se déclencher dans un onglet en arrière-plan.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Page lifecycle events</title>
</head>
<body>
  <label><input id="dirty" type="checkbox" autocomplete="off"> Simulate unsaved changes</label>
  <script>
    const dirty = document.getElementById('dirty');

    function warn(event) {
      console.log('beforeunload');
      event.preventDefault();
      event.returnValue = 'unsaved'; // Legacy compatibility, not dialog text.
    }

    dirty.addEventListener('change', () => {
      if (dirty.checked) {
        window.addEventListener('beforeunload', warn);
      } else {
        window.removeEventListener('beforeunload', warn);
      }
    });

    document.addEventListener('visibilitychange', () => {
      console.log(`visibilitychange: ${document.visibilityState}`);
    });
    for (const type of ['pagehide', 'pageshow']) {
      window.addEventListener(type, (event) => {
        console.log(`${type}: persisted=${event.persisted}`);
      });
    }
    console.log('ready');
  </script>
</body>
</html>

Résultat

ready

Then, for example, after switching away from the tab and back:
visibilitychange: hidden
visibilitychange: visible

Other lines (not guaranteed and not in a fixed cross-event order):
beforeunload
pagehide: persisted=true
pageshow: persisted=true

A dispatched page transition event can also report persisted=false.

Ouvrez l’exemple comme page HTML dans le navigateur et consultez la console. `ready` s’affiche immédiatement ; les messages suivants dépendent de vos actions et du navigateur. La case simule des modifications non enregistrées sans rien enregistrer.

Leçons associées

  • JavaScript · Leçon 35 · Avancé · Version : 4

Sources