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

CKTIS / JavaScript

Les événements DOMContentLoaded, pagehide et scroll

Distinguez la disponibilité du DOM, le départ de la page et le défilement. Choisissez la bonne cible et tenez compte de la restauration depuis le bfcache.

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

Syntaxe

document.addEventListener("DOMContentLoaded", onReady, { once: true });
window.addEventListener("pagehide", onPageHide);
document.addEventListener("scroll", onDocumentScroll);
scrollBox.addEventListener("scroll", onElementScroll);

Ces événements du navigateur répondent à trois questions différentes : le DOM est-il prêt pour l’initialisation ? Le navigateur quitte-t-il ce document ? La position de défilement a-t-elle changé ? Ils relèvent de la plateforme web, pas d’ECMAScript. Hors navigateur, ne supposez pas que document et window sont disponibles.

DOMContentLoaded est déclenché sur document une fois l’analyse du HTML terminée, les scripts classiques avec defer exécutés et l’évaluation des modules sans async prévus pour la fin de l’analyse lancée. L’événement n’attend pas la fin de l’évaluation asynchrone des modules : un await au niveau supérieur dans une dépendance peut retarder l’exécution du corps du module qui l’importe jusqu’après l’événement. Contrairement à load, il n’attend ni les images, ni les cadres intégrés, ni les scripts async. Une feuille de style peut le retarder indirectement si elle bloque un script.

Si le code d’initialisation risque de s’exécuter tard, vérifiez document.readyState. Si l’état vaut "loading", enregistrez un écouteur à usage unique pour DOMContentLoaded ; sinon, initialisez immédiatement. "interactive" signifie que l’analyse est terminée, mais ne prouve ni que l’événement a déjà eu lieu ni que les autres scripts différés ont terminé leur exécution.

Écoutez pagehide sur window pour réagir lorsque le navigateur quitte le document, pas lors d’un simple changement d’onglet. Sur ce PageTransitionEvent, event.persisted === true indique que le document pourrait être restauré depuis le cache de navigation arrière/avant (bfcache), sans garantie ; false signifie qu’il n’est pas conservé pour être réutilisé. Pour reprendre le travail après une restauration, utilisez pageshow avec persisted === true, et non DOMContentLoaded. pagehide peut ne pas se produire, par exemple si le système arrête un navigateur mobile. Enregistrez les données importantes au fil de l’utilisation ; pour détecter qu’un onglet devient masqué, écoutez visibilitychange et vérifiez l’état "hidden".

Pour le défilement de la page, écoutez scroll sur document et lisez window.scrollY ; pour un conteneur défilant, écoutez l’événement sur l’élément lui-même et lisez son scrollTop. Un défilement piloté par le code peut aussi déclencher l’événement, qui ne signale pas la fin du défilement. Gardez le gestionnaire léger, car les événements peuvent se succéder rapidement ; limitez au besoin la fréquence des mises à jour coûteuses.

Exemples

(() => {
  const viewportHeight = 80;
  const contentHeight = 240;

  function run(page, doc, createScrollBox) {
    page.addEventListener("pagehide", (event) => {
      console.log(`pagehide: persisted=${event.persisted}`);
    });

    function init() {
      console.log("DOM ready");

      const box = createScrollBox();
      box.addEventListener("scroll", () => {
        console.log(`scroll: ${box.scrollTop}`);
      }, { once: true });

      box.scrollTop = 40;
    }

    if (doc.readyState === "loading") {
      doc.addEventListener("DOMContentLoaded", init, { once: true });
    } else {
      init();
    }
  }

  if (typeof window !== "undefined" && typeof document !== "undefined") {
    run(window, document, () => {
      const box = document.createElement("div");
      box.style.cssText = `width: 200px; height: ${viewportHeight}px; overflow: auto`;

      const content = document.createElement("div");
      content.style.height = `${contentHeight}px`;
      content.textContent = "Scroll demo";
      box.append(content);
      document.body.append(box);
      return box;
    });
    return;
  }

  // Node.js stand-ins exercise the same listeners without a browser DOM.
  class ScrollBox extends EventTarget {
    #offset = 0;

    get scrollTop() {
      return this.#offset;
    }

    set scrollTop(value) {
      const offset = Math.min(Math.max(0, value), contentHeight - viewportHeight);
      if (offset === this.#offset) return;
      this.#offset = offset;
      setTimeout(() => this.dispatchEvent(new Event("scroll")), 0);
    }
  }

  const page = new EventTarget();
  const doc = new EventTarget();
  doc.readyState = "loading";
  run(page, doc, () => new ScrollBox());
  doc.readyState = "interactive";
  doc.dispatchEvent(new Event("DOMContentLoaded"));
})();

Résultat

DOM ready
scroll: 40

Exécutez le code une fois dans la console d’une page HTML vide et déjà chargée. L’initialisation est immédiate et le code fait défiler le conteneur. Activez la conservation du journal et ouvrez un autre document dans le même onglet pour chercher une ligne supplémentaire `pagehide: persisted=true` ou `pagehide: persisted=false`. Cette ligne n’est pas garantie. Dans Node.js, des objets de substitution basés sur `EventTarget` font fonctionner les mêmes gestionnaires de disponibilité du DOM et de défilement, sans vérifier le comportement réel du navigateur.

Leçons associées

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

Sources