CKTIS / JavaScript
DOMContentLoaded, pagehide e pageshow: disponibilidade do DOM e navegação
Distingue o momento em que o DOM fica pronto, a saída de um documento e o seu restauro. Aprende a interpretar `readyState` e `persisted` sem os confundir com a visibilidade.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
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 é um evento do navegador do tipo Event a escutar em document. É emitido depois de terminar a análise do HTML e de serem executados os scripts clássicos com defer. Antes de emitir o evento, o navegador inicia também a avaliação dos scripts de módulo sem async inseridos pelo analisador de HTML. Não espera pela conclusão das operações aguardadas por um await ao nível superior desses módulos ou das suas dependências, pelo que a inicialização dos módulos pode continuar pendente depois do evento. Não espera por imagens, frames nem scripts com async; as folhas de estilo podem atrasá-lo indiretamente se bloquearem scripts adiados. Não é o evento load.
Se o código puder correr tarde e só precisar do DOM resultante da análise do HTML, verifica document.readyState. Se for "loading", regista um listener de utilização única para DOMContentLoaded; caso contrário, inicializa logo. "interactive" indica que a análise terminou, não que DOMContentLoaded já ocorreu ou que os outros scripts acabaram de inicializar.
Em window, escuta pagehide ao sair de um documento e pageshow ao carregá-lo ou restaurá-lo. Ambos são eventos PageTransitionEvent com a propriedade booleana persisted. Em pagehide, true indica que o documento poderá ser reutilizado, sem garantia; false indica que não será reutilizado. Num novo carregamento, pageshow ocorre depois de load com false. Ao restaurar a partir da cache de navegação para trás e para a frente (bfcache), o valor é true: regressam o mesmo DOM e o mesmo estado de JavaScript, sem outro DOMContentLoaded.
Usa pagehide para suspender tarefas da página e pageshow com persisted === true para as retomar ou atualizar dados desatualizados. pagehide pode não ocorrer, por exemplo se um navegador móvel for encerrado em segundo plano. Guarda as alterações importantes à medida que acontecem; usa visibilitychange e document.visibilityState para detetar mudanças de visibilidade. Estes eventos não assinalam uma simples mudança de separador e fazem parte da plataforma Web, não do ECMAScript.
Exemplos
(() => {
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
Cola o código uma vez na consola do navegador após o carregamento completo da página. `DOM ready` resulta da verificação de `readyState`, não da repetição de um evento. Mantém o registo da consola, navega para outro documento no mesmo separador e volta atrás. As linhas adicionais dependem da navegação e da utilização da bfcache pelo navegador.
Lições relacionadas
- JavaScript · Lição 37 · Avançado · Versão: 4