Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

DOMContentLoaded, pagehide e pageshow: disponibilità del DOM e navigazione

Distingui quando il DOM è pronto, quando la navigazione lascia un documento e quando il browser lo ripristina. Scopri come interpretare `readyState` e `persisted`.

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

Sintassi

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 è un evento del browser di tipo Event da ascoltare su document. Scatta al termine dell’analisi del codice HTML e dopo l’esecuzione degli script classici con defer. Prima di generarlo, il browser avvia anche la valutazione degli script di modulo senza async inseriti dal parser HTML. Non attende il completamento delle operazioni sospese da un await al livello superiore di questi moduli o delle loro dipendenze: l’inizializzazione dei moduli può quindi essere ancora in corso dopo l’evento. Non aspetta immagini, frame o script async; i fogli di stile possono ritardarlo indirettamente bloccando gli script differiti. Non è l’evento load.

Se il codice può partire tardi e gli basta che il DOM sia stato costruito a partire dall’HTML, controlla document.readyState. Se vale "loading", registra un listener per DOMContentLoaded che si attivi una sola volta; altrimenti inizializza subito. "interactive" significa che l’analisi è terminata, non che DOMContentLoaded sia già scattato o che gli altri script abbiano finito di inizializzarsi.

Su window, ascolta pagehide quando si lascia un documento e pageshow quando viene caricato o ripristinato. Entrambi sono eventi PageTransitionEvent con un valore booleano persisted. Per pagehide, true indica un possibile riutilizzo del documento, non garantito; false indica che non verrà riutilizzato. In un nuovo caricamento, pageshow segue load con false. Se il documento viene ripristinato dalla cache di navigazione indietro/avanti (bfcache), il valore è true: tornano lo stesso DOM e lo stesso stato JavaScript senza un nuovo DOMContentLoaded.

Usa pagehide per sospendere le attività della pagina e pageshow con persisted === true per riprenderle o aggiornare i dati obsoleti. pagehide potrebbe non scattare, per esempio se il browser mobile viene terminato in background. Salva le modifiche importanti man mano; per i cambiamenti di visibilità usa visibilitychange e document.visibilityState. Questi eventi non segnalano un semplice cambio di scheda e fanno parte della piattaforma web, non di ECMAScript.

Esempi

(() => {
  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"));
  }
})();

Risultato

DOM ready

Incolla il codice una sola volta nella console del browser dopo il caricamento completo della pagina. `DOM ready` deriva dal controllo di `readyState`, non dalla ripetizione di un evento. Mantieni il log della console, visita un altro documento nella stessa scheda e torna indietro. Le righe aggiuntive dipendono dalla navigazione e dall’uso della bfcache.

Lezioni correlate

  • JavaScript · Lezione 37 · Avanzato · Versione: 4

Fonti