Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Eventos DOMContentLoaded e pagehide

Usa `DOMContentLoaded` para inicializar o código quando o DOM estiver construído e `pagehide` para suspender tarefas ao sair do documento. Restaurar a partir da bfcache não é carregar de novo.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

document.addEventListener("DOMContentLoaded", onReady, { once: true });
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);

DOMContentLoaded é um Event disparado em document depois de o navegador concluir a análise do HTML, executar os scripts clássicos com defer e iniciar a avaliação dos scripts de módulo sem async agendados para o fim da análise. O evento não espera pelo fim da avaliação dos módulos: se a execução de uma dependência ficar suspensa num await ao nível superior, o evento pode ser disparado antes mesmo de começar a execução do corpo do módulo que a importa. Não espera por imagens, molduras nem pela conclusão de scripts async. As folhas de estilo podem atrasá-lo indiretamente se bloquearem a execução de scripts. Usa load em window quando precisares de esperar pelos recursos que atrasam o carregamento da página.

Se o código de inicialização puder arrancar tarde, verifica document.readyState: se for "loading", regista um listener de utilização única para DOMContentLoaded; caso contrário, usa o DOM já disponível. "interactive" indica que a análise terminou, mas não que o evento já tenha sido disparado ou que os outros scripts tenham terminado a inicialização. Se dependeres desses scripts, define explicitamente a ordem de inicialização.

Escuta pagehide em window para reagir à saída do documento, por exemplo ao recuar no histórico. Este PageTransitionEvent não indica uma simples mudança de separador e não permite cancelar a navegação. event.persisted === true significa que o documento pode ser mantido na cache de navegação para trás e para a frente (bfcache), não que o restauro esteja garantido. false significa que o documento não é mantido nessa navegação. Suspende as tarefas em pagehide e retoma-as em pageshow quando persisted === true: o documento restaurado mantém o seu DOM e não volta a disparar DOMContentLoaded.

Guarda os dados importantes à medida que forem sendo produzidos. pagehide pode não ser disparado, sobretudo se um navegador móvel for encerrado à força, e as tarefas assíncronas iniciadas nesse momento podem não terminar. Para reagir quando a página fica oculta, escuta visibilitychange em document e verifica o estado "hidden". Estas API pertencem à plataforma Web e não foram introduzidas pelo ECMAScript 2024.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>DOMContentLoaded and pagehide</title>
  <script>
    (() => {
      const init = () => console.log("DOM ready");

      if (document.readyState === "loading") {
        document.addEventListener("DOMContentLoaded", init, { once: true });
      } else {
        init();
      }

      window.addEventListener("pagehide", (event) => {
        console.log(`pagehide persisted=${event.persisted}`);
      });

      window.addEventListener("pageshow", (event) => {
        if (event.persisted) console.log("pageshow restored");
      });
    })();
  </script>
</head>
<body>
  <p>Open the browser console to see the event log.</p>
</body>
</html>

Resultado

DOM ready

Guarda o exemplo como ficheiro HTML e abre-o num navegador. Ativa a opção para manter o registo na consola e recarrega a página. `DOM ready` aparece quando `DOMContentLoaded` é disparado. As mensagens seguintes dependem da navegação e de o navegador manter ou não o documento.

Lições relacionadas

  • JavaScript · Lição 40 · Avançado · Versão: 4
  • JavaScript · Lição 41 · Avançado · Versão: 4

Fontes