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

CKTIS / JavaScript

Eventos DOMContentLoaded, pagehide e scroll

Distingue a disponibilidade do DOM, a saída da página e o deslocamento. Regista cada escuta no objeto certo e tem em conta o restauro a partir da bfcache.

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

Sintaxe

document.addEventListener("DOMContentLoaded", onReady, { once: true });
window.addEventListener("pagehide", onPageHide);
document.addEventListener("scroll", onDocumentScroll);
scrollBox.addEventListener("scroll", onElementScroll);

Estes eventos do navegador respondem a três perguntas diferentes: o DOM está pronto para a inicialização? O navegador está a sair deste documento? A posição de deslocamento mudou? Fazem parte da plataforma Web, não do ECMAScript. Fora do navegador, não pressuponhas a existência de document e window.

DOMContentLoaded é disparado em document depois de terminar a análise do HTML, de serem executados os scripts clássicos com defer e de o navegador iniciar a avaliação dos módulos sem async programados para o fim da análise. O evento não espera pelo fim da avaliação assíncrona dos módulos: um await ao nível superior numa dependência pode atrasar a execução do corpo do módulo que a importa até depois do evento. Ao contrário de load, não espera por imagens, frames incorporadas nem scripts async. Uma folha de estilos pode atrasá-lo indiretamente se bloquear um script.

Se o código de inicialização puder ser executado tarde, verifica document.readyState. Se o valor for "loading", regista uma escuta única de DOMContentLoaded; caso contrário, inicializa imediatamente. "interactive" significa que a análise terminou, não que o evento já foi disparado ou que os outros scripts diferidos já terminaram.

Escuta pagehide em window para reagir quando o navegador sai do documento, não quando apenas se muda de separador. Nesse PageTransitionEvent, event.persisted === true indica que o documento poderá ser restaurado a partir da cache de navegação para trás e para a frente (bfcache), mas não o garante; false significa que não é guardado para reutilização. Para retomar o trabalho após o restauro, usa pageshow com persisted === true, não DOMContentLoaded. pagehide pode não ocorrer, por exemplo se o sistema terminar um navegador móvel. Guarda os dados importantes à medida que são alterados; para detetar que o separador ficou oculto, usa visibilitychange e verifica se o estado é "hidden".

Para o deslocamento da página, escuta scroll em document e lê window.scrollY; num contentor com deslocamento, escuta o evento no próprio elemento e lê o seu scrollTop. O deslocamento provocado por código também pode disparar o evento, que não indica o fim do deslocamento. Mantém o processamento do evento leve, pois os eventos podem suceder-se rapidamente; se necessário, limita a frequência das atualizações dispendiosas.

Exemplos

(() => {
  const viewportHeight = 80;
  const contentHeight = 240;

  function run(page, doc, createScrollBox) {
    page.addEventListener("pagehide", (event) => {
      console.log(`pagehide: persisted=${event.persisted}`);
    });

    function init() {
      console.log("DOM ready");

      const box = createScrollBox();
      box.addEventListener("scroll", () => {
        console.log(`scroll: ${box.scrollTop}`);
      }, { once: true });

      box.scrollTop = 40;
    }

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

  if (typeof window !== "undefined" && typeof document !== "undefined") {
    run(window, document, () => {
      const box = document.createElement("div");
      box.style.cssText = `width: 200px; height: ${viewportHeight}px; overflow: auto`;

      const content = document.createElement("div");
      content.style.height = `${contentHeight}px`;
      content.textContent = "Scroll demo";
      box.append(content);
      document.body.append(box);
      return box;
    });
    return;
  }

  // Node.js stand-ins exercise the same listeners without a browser DOM.
  class ScrollBox extends EventTarget {
    #offset = 0;

    get scrollTop() {
      return this.#offset;
    }

    set scrollTop(value) {
      const offset = Math.min(Math.max(0, value), contentHeight - viewportHeight);
      if (offset === this.#offset) return;
      this.#offset = offset;
      setTimeout(() => this.dispatchEvent(new Event("scroll")), 0);
    }
  }

  const page = new EventTarget();
  const doc = new EventTarget();
  doc.readyState = "loading";
  run(page, doc, () => new ScrollBox());
  doc.readyState = "interactive";
  doc.dispatchEvent(new Event("DOMContentLoaded"));
})();

Resultado

DOM ready
scroll: 40

Executa o código uma vez na consola de uma página HTML vazia e já carregada. A inicialização é imediata e o código desloca o contentor. Ativa a preservação do registo e navega para outro documento no mesmo separador para procurar uma linha adicional `pagehide: persisted=true` ou `pagehide: persisted=false`. Essa linha não é garantida. Em Node.js, objetos de substituição baseados em `EventTarget` executam os mesmos processadores de eventos de disponibilidade do DOM e de deslocamento, sem verificar o comportamento real do navegador.

Lições relacionadas

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

Fontes