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

CKTIS / JavaScript

Visibilité du document : `Document.hidden` et `visibilitychange`

Lisez la visibilité actuelle du document avec `document.hidden` et réagissez à ses changements avec `visibilitychange`, sans interrogation périodique.

Version : Current web platform; runtime support varies

Syntaxe

document.hidden
 document.visibilityState
 document.addEventListener("visibilitychange", listener)
 document.removeEventListener("visibilitychange", listener)

document.hidden est une propriété booléenne en lecture seule. Elle vaut true si document.visibilityState vaut "hidden", et false si cet état vaut "visible". Un onglet en arrière-plan ou une fenêtre réduite sont des cas courants où le document est considéré comme masqué. Cet état ne vous dit pas si la page a le focus, si un élément particulier est visible ou si quelqu’un regarde la page.

Après un changement d’état dans un sens ou dans l’autre, le navigateur déclenche visibilitychange sur document. C’est un simple Event qui remonte et n’est pas annulable. Il ne contient pas le nouvel état : lisez la propriété dans la fonction d’écoute. L’enregistrement de cette fonction ne l’appelle pas immédiatement ; lisez donc l’état initial séparément. Pour arrêter l’écoute, passez la même fonction à removeEventListener.

Vous pouvez par exemple suspendre les mises à jour non essentielles de l’interface quand le document est masqué, puis les reprendre quand il redevient visible. Le passage à "hidden" ne signifie pas que la page a été fermée, et rien ne garantit que le navigateur laissera au code le temps de terminer son travail. Cette API appartient à la plateforme web, pas à ECMAScript. Sa disponibilité dépend de l’environnement d’exécution.

Exemples

const stopVisibilityLog = (() => {
  const hasDocument = typeof document !== "undefined";
  const page = hasDocument ? document : new EventTarget();
  let simulatedHidden = false;

  if (!hasDocument) {
    // Node.js fixture: simulate visibility without a browser document.
    Object.defineProperty(page, "hidden", { get: () => simulatedHidden });
  }

  const logVisibility = () => {
    console.log(page.hidden ? "hidden" : "visible");
  };

  page.addEventListener("visibilitychange", logVisibility);
  logVisibility();

  const stop = () => {
    page.removeEventListener("visibilitychange", logVisibility);
  };

  if (!hasDocument) {
    const changeVisibility = (hidden) => {
      simulatedHidden = hidden;
      page.dispatchEvent(new Event("visibilitychange", { bubbles: true }));
    };

    changeVisibility(true);
    changeVisibility(false);
    stop();
    changeVisibility(true); // No log after removing the listener.
  }

  return stop;
})();

Résultat

visible
hidden
visible

Exécutez le code une fois dans la console du navigateur, sur une page visible. Passez à un autre onglet, puis revenez au premier. La sortie indiquée suppose exactement ces deux changements après la lecture initiale. Appelez `stopVisibilityLog()` pour arrêter la journalisation. Dans Node.js, l’exemple simule les changements de visibilité sans utiliser de document de navigateur.

Leçons associées

  • JavaScript · Leçon 27 · Intermédiaire · Version : 3
  • JavaScript · Leçon 29 · Intermédiaire · Version : 3
  • JavaScript · Leçon 31 · Intermédiaire · Version : 3

Sources