CKTIS / JavaScript
DOMContentLoaded e l’opzione once del listener
Usa `DOMContentLoaded` per attendere l’analisi dell’HTML e `{ once: true }` per limitare ogni registrazione del listener a una chiamata. Controlla `document.readyState` se il codice può partire in ritardo.
Versione: HTML Living Standard and DOM Standard; runtime support varies
Sintassi
document.addEventListener("DOMContentLoaded", init, { once: true });
// Instead, if init only needs the parsed DOM and may be set up late:
if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", init, { once: true });
} else {
init();
}Il browser genera DOMContentLoaded su document dopo aver analizzato l’HTML ed eseguito gli script previsti per dopo l’analisi: gli script con defer e i moduli senza async. Non attende il lavoro che riprende dopo un await al livello principale di un modulo. A differenza di load, l’evento non attende immagini, frame incorporati o script async. I fogli di stile possono ritardarlo indirettamente se bloccano script che l’evento deve attendere.
In document.addEventListener("DOMContentLoaded", init, { once: true }), once rimuove automaticamente quella registrazione prima che l’evento chiami init per la prima volta. Il valore predefinito è false. Un semplice true come terzo argomento attiva capture, non once. L’opzione non ripropone un evento passato e non limita le chiamate manuali né le registrazioni successive.
Se a init serve solo il DOM già analizzato, controlla document.readyState: con "loading" registra il listener, altrimenti chiama subito init(). Il browser non può generare l’evento tra il controllo sincrono e la registrazione. "interactive" significa che l’analisi è terminata, non che DOMContentLoaded sia già avvenuto. Se l’inizializzazione dipende da un altro script, coordinati esplicitamente con quello script.
L’evento, la proprietà di stato e l’opzione del listener fanno parte delle API della piattaforma web, non di ECMAScript. Il supporto di ECMAScript 2024 non ne garantisce la disponibilità in uno specifico ambiente di esecuzione.
Esempi
(() => {
const target = new EventTarget();
let calls = 0;
target.addEventListener("DOMContentLoaded", () => {
calls += 1;
}, { once: true });
target.dispatchEvent(new Event("DOMContentLoaded"));
console.log(`After first dispatch: ${calls}`);
target.dispatchEvent(new Event("DOMContentLoaded"));
console.log(`After second dispatch: ${calls}`);
})();Risultato
After first dispatch: 1 After second dispatch: 1
Esegui il codice nella console del browser. I due eventi sintetici con lo stesso nome sono inviati a un `EventTarget` separato, non a `document`. Mostrano l’effetto di `once`, non quando la pagina è pronta.
Lezioni correlate
- JavaScript · Lezione 39 · Intermedio · Versione: 3