Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

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

Fuentes