CKTIS / JavaScript
DOMContentLoaded, pagehide et pageshow : disponibilité du DOM et navigation
Distinguez le moment où le DOM est prêt, le départ d’un document et sa restauration. Apprenez à interpréter `readyState` et la valeur de `persisted` selon l’événement.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
document.addEventListener("DOMContentLoaded", onDomReady, { once: true });
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);
// onPageHide and onPageShow receive a PageTransitionEvent with a boolean persisted property.DOMContentLoaded est un événement du navigateur de type Event à écouter sur document. Il se déclenche lorsque l’analyse du HTML est terminée et que les scripts classiques avec defer ont été exécutés. Avant de le déclencher, le navigateur lance aussi l’évaluation des scripts de module sans async insérés par l’analyseur HTML. Il n’attend pas la fin des opérations attendues par un await au niveau supérieur dans ces modules ou leurs dépendances : l’initialisation des modules peut donc rester inachevée après le déclenchement de l’événement. Il n’attend pas les images, les cadres intégrés ni les scripts async ; les feuilles de style peuvent le retarder indirectement en bloquant les scripts différés. Il ne s’agit pas de load.
Si votre code peut s’exécuter tard et n’a besoin que du DOM issu de l’analyse, consultez document.readyState. Si la valeur est "loading", ajoutez un écouteur à usage unique pour DOMContentLoaded ; sinon, initialisez immédiatement. "interactive" indique que l’analyse est terminée, pas que DOMContentLoaded s’est déjà déclenché ni que les autres scripts ont terminé leur initialisation.
Sur window, écoutez pagehide lorsqu’on quitte un document et pageshow lorsqu’il est chargé ou restauré. Ces événements de type PageTransitionEvent ont une propriété booléenne persisted. Pour pagehide, true indique une réutilisation possible, pas garantie ; false signifie que le document ne sera pas réutilisé. Lors d’un nouveau chargement, pageshow suit load avec false. Lors d’une restauration depuis le cache de navigation arrière/avant (bfcache), la valeur est true : le même DOM et le même état JavaScript sont restaurés sans nouveau DOMContentLoaded.
Utilisez pagehide pour suspendre les tâches propres à la page et pageshow avec persisted === true pour les reprendre ou actualiser les données périmées. pagehide peut manquer, par exemple si un navigateur mobile est arrêté en arrière-plan. Enregistrez les modifications importantes au fur et à mesure ; utilisez visibilitychange et document.visibilityState pour suivre la visibilité. Ces événements ne signalent pas un simple changement d’onglet et relèvent de la plateforme web, pas d’ECMAScript.
Exemples
(() => {
function installListeners(doc, win) {
const onDomReady = () => console.log("DOM ready");
if (doc.readyState === "loading") {
doc.addEventListener("DOMContentLoaded", onDomReady, { once: true });
} else {
onDomReady();
}
const logTransition = (event) => {
console.log(`${event.type} persisted=${event.persisted}`);
};
win.addEventListener("pagehide", logTransition);
win.addEventListener("pageshow", logTransition);
}
if (typeof document !== "undefined" && typeof window !== "undefined") {
installListeners(document, window);
} else {
// Node.js test: simulate DOM readiness without simulating navigation.
const testDocument = new EventTarget();
const testWindow = new EventTarget();
testDocument.readyState = "loading";
installListeners(testDocument, testWindow);
testDocument.readyState = "interactive";
testDocument.dispatchEvent(new Event("DOMContentLoaded"));
}
})();Résultat
DOM ready
Collez le code une seule fois dans la console du navigateur après le chargement complet de la page. `DOM ready` provient alors du test de `readyState`, pas d’un événement rejoué. Conservez les journaux de la console, ouvrez un autre document dans le même onglet, puis revenez en arrière. Les lignes supplémentaires dépendent de la navigation et de l’utilisation du bfcache.
Leçons associées
- JavaScript · Leçon 37 · Avancé · Version : 4