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