CKTIS / JavaScript
DOMContentLoaded, pagehide y pageshow: disponibilidad del DOM y navegación
Distingue cuándo está listo el DOM, cuándo se abandona un documento y cuándo se restaura. Aprende a interpretar `readyState` y `persisted` sin confundirlos con la visibilidad.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
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 es un evento del navegador de tipo Event que se escucha en document. Se dispara tras finalizar el análisis del HTML y ejecutar los scripts clásicos con defer. Antes de dispararlo, el navegador también inicia la evaluación de los scripts de módulo sin async insertados por el analizador HTML. No espera a que se resuelvan las operaciones que suspenden la ejecución mediante await en el nivel superior de esos módulos o de sus dependencias, por lo que la inicialización de los módulos puede seguir pendiente después del evento. No espera a las imágenes, los marcos ni los scripts async; las hojas de estilo pueden retrasarlo indirectamente si bloquean los scripts diferidos. No es el evento load.
Si el código puede ejecutarse tarde y solo necesita que el DOM ya se haya construido a partir del HTML, comprueba document.readyState. Si es "loading", añade un listener de un solo uso para DOMContentLoaded; si no, inicializa de inmediato. "interactive" indica que el análisis terminó, no que DOMContentLoaded ya se haya disparado ni que otros scripts hayan terminado de inicializarse.
En window, escucha pagehide al salir de un documento y pageshow al cargarlo o restaurarlo. Ambos son eventos PageTransitionEvent con un persisted booleano. En pagehide, true indica que el documento podría reutilizarse, pero no lo garantiza; false indica que no se reutilizará. En una nueva carga, pageshow se dispara después de load con false. Si se restaura desde la caché de navegación atrás/adelante (bfcache), el valor es true: vuelven el mismo DOM y el mismo estado de JavaScript, sin otro DOMContentLoaded.
Usa pagehide para pausar las tareas de la página y pageshow con persisted === true para reanudarlas o actualizar datos obsoletos. pagehide puede no dispararse, por ejemplo si se cierra a la fuerza un navegador móvil en segundo plano. Guarda los cambios importantes a medida que ocurran; usa visibilitychange y document.visibilityState para detectar cambios de visibilidad. Estos eventos no señalan un simple cambio de pestaña y son parte de la plataforma web, no de ECMAScript.
Ejemplos
(() => {
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"));
}
})();Resultado
DOM ready
Pega el código una vez en la consola del navegador tras la carga completa de la página. `DOM ready` procede de la comprobación de `readyState`, no de un evento repetido. Conserva el registro de la consola, navega a otro documento en la misma pestaña y vuelve atrás. Las líneas adicionales dependen de la navegación y de si el navegador usa la bfcache.
Lecciones relacionadas
- JavaScript · Lección 37 · Avanzado · Versión: 4