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

CKTIS / JavaScript

Eventos DOMContentLoaded, pagehide e resize

Escolhe o evento certo: `DOMContentLoaded` quando o DOM está pronto, `pagehide` ao sair da página e `resize` quando muda o tamanho da área de visualização.

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("resize", onResize);

DOMContentLoaded, pagehide e resize pertencem à plataforma Web, não a ECMAScript 2024. Regista os ouvintes com addEventListener(): em document para o primeiro e em window para os outros dois. A disponibilidade depende do ambiente de execução; não partas do princípio de que um worker ou Node.js disponibiliza estes alvos de eventos do navegador.

DOMContentLoaded é um Event não cancelável que se propaga a partir de document na fase de bubbling. O navegador dispara-o após analisar o HTML, executar os scripts clássicos com defer e iniciar a avaliação dos scripts de módulo programados para depois da análise (sem async). Não espera que a avaliação assíncrona dos módulos termine: um módulo pode continuar suspenso num await de nível superior, ou a execução do seu corpo pode ainda estar à espera de uma dependência assíncrona. Ao contrário de load, não espera diretamente por imagens, molduras ou scripts async. Se só precisas do DOM já analisado, regista um ouvinte com { once: true } quando document.readyState === "loading"; caso contrário, inicializa logo. "interactive" não prova que o evento já ocorreu nem que os scripts diferidos prepararam o estado de que o teu código depende.

pagehide é um PageTransitionEvent que se escuta em window ao sair da página, não ao mudar apenas de separador. event.persisted === true indica que a página pode ficar na cache de navegação para trás e para a frente (bfcache); false significa que esse documento não será restaurado dessa forma. true não garante o regresso: deteta o restauro efetivo com pageshow e persisted === true, sem um novo DOMContentLoaded. preventDefault() não impede a navegação. pagehide pode não ocorrer, sobretudo em dispositivos móveis, pelo que deves guardar os dados importantes mais cedo. Para detetar a passagem para segundo plano, usa visibilitychange e verifica document.visibilityState === "hidden".

O resize de window é um Event não cancelável que não se propaga na fase de bubbling. Indica mudanças no tamanho da área de visualização, não de um elemento qualquer. Lê as dimensões atuais em window.innerWidth e window.innerHeight; para acompanhar o tamanho de um elemento, usa ResizeObserver. As mudanças podem suceder-se rapidamente, pelo que convém limitar a frequência dos cálculos de disposição mais pesados.

Exemplos

(() => {
  const documentTarget = globalThis.document ?? new EventTarget();
  const windowTarget = globalThis.window ?? new EventTarget();
  const controller = new AbortController();
  const options = { signal: controller.signal };

  documentTarget.addEventListener("DOMContentLoaded", (event) => {
    console.log(event.type);
  }, options);
  windowTarget.addEventListener("pagehide", (event) => {
    console.log(`${event.type}: persisted=${event.persisted}`);
  }, options);
  windowTarget.addEventListener("resize", (event) => {
    console.log(event.type);
  }, options);

  try {
    documentTarget.dispatchEvent(new Event("DOMContentLoaded", { bubbles: true }));
    const pagehide = typeof PageTransitionEvent === "function"
      ? new PageTransitionEvent("pagehide", { persisted: true })
      : Object.assign(new Event("pagehide"), { persisted: true });
    windowTarget.dispatchEvent(pagehide);
    windowTarget.dispatchEvent(new Event("resize"));
  } finally {
    controller.abort();
  }
})();

Resultado

DOMContentLoaded
pagehide: persisted=true
resize

Executa o código na consola do navegador, num novo separador `about:blank`, ou guarda-o como `main.js` e executa `node main.js` com Node.js 24. Em Node.js, o exemplo usa instâncias autónomas de `EventTarget` em vez de `document` e `window`. Os eventos sintéticos verificam a ligação dos ouvintes; não alteram o estado de preparação do documento nem as dimensões da área de visualização, não iniciam navegação e não testam a bfcache. `abort()` remove os três ouvintes.

Lições relacionadas

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

Fontes