CKTIS / JavaScript
DOMContentLoaded y la opción once del listener
Usa `DOMContentLoaded` para esperar a que se analice el HTML y `{ once: true }` para limitar cada registro del listener a una llamada. Consulta `document.readyState` si tu código puede ejecutarse tarde.
Versión: HTML Living Standard and DOM Standard; runtime support varies
Sintaxis
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();
}El navegador dispara DOMContentLoaded en document después de analizar el HTML y ejecutar los scripts previstos para después del análisis: los que llevan defer y los módulos sin async. No espera al trabajo que se reanuda tras un await de nivel superior. A diferencia de load, el evento no espera a las imágenes, los marcos internos ni los scripts async. Las hojas de estilo pueden retrasarlo indirectamente si bloquean scripts a los que el evento sí espera.
En document.addEventListener("DOMContentLoaded", init, { once: true }), once elimina automáticamente ese registro antes de que el evento llame a init por primera vez. Su valor predeterminado es false. Pasar solo true como tercer argumento activa capture, no once. La opción no vuelve a emitir un evento pasado ni limita las llamadas manuales o los registros posteriores.
Si init solo necesita el DOM analizado, consulta document.readyState: si es "loading", registra el listener; de lo contrario, llama a init() de inmediato. El navegador no puede disparar el evento entre esa comprobación síncrona y el registro. "interactive" significa que el análisis ha terminado, no que DOMContentLoaded ya se haya disparado. Si la inicialización depende de otro script, coordínala explícitamente con él.
El evento, la propiedad de estado y la opción del listener forman parte de las API web, no de ECMAScript. La compatibilidad con ECMAScript 2024 no garantiza que estén disponibles en un entorno de ejecución concreto.
Ejemplos
(() => {
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}`);
})();Resultado
After first dispatch: 1 After second dispatch: 1
Ejecuta el código en la consola del navegador. Los dos eventos sintéticos con el mismo nombre se envían a un `EventTarget` independiente, no a `document`. Demuestran el efecto de `once`, no cuándo está lista la página.
Lecciones relacionadas
- JavaScript · Lección 39 · Intermedio · Versión: 3