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

CKTIS / JavaScript

Eventos wheel, pagehide, pageshow e beforeunload

Distingue os gestos da roda do rato ou do painel tátil do deslocamento, deteta o restauro a partir da cache de navegação e avisa sobre alterações por guardar.

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

Sintaxe

element.addEventListener("wheel", onWheel, { passive: true });
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);
window.addEventListener("beforeunload", onBeforeUnload);
window.removeEventListener("beforeunload", onBeforeUnload);

Estes eventos fazem parte das APIs do navegador, não do ECMAScript 2024. Escuta wheel num elemento e pagehide, pageshow e beforeunload em window. Alguns pormenores do comportamento variam consoante o navegador.

wheel (WheelEvent) indica um gesto da roda do rato ou do painel tátil, não um deslocamento efetivo: o gesto pode alterar o zoom ou não mover nada, e o teclado permite deslocar conteúdo sem esse gesto. deltaX e deltaY descrevem o gesto; deltaMode indica a unidade: 0 para píxeis, 1 para linhas e 2 para páginas. Para detetar o movimento efetivo, compara scrollLeft e scrollTop num listener de scroll. Para observar, usa { passive: true }. Se tiveres de impedir o deslocamento ou o zoom predefinidos, usa { passive: false } e chama preventDefault() apenas se event.cancelable for true. Alguns navegadores só permitem cancelar o primeiro evento de uma sequência.

pagehide e pageshow são do tipo PageTransitionEvent. Ao sair da página, pagehide com persisted: true indica que a página pode ser mantida na cache de navegação para trás e para a frente (bfcache), sem garantia de restauro posterior. pageshow com persisted: true indica que a mesma página foi retomada a partir da bfcache; no carregamento inicial, pageshow ocorre a seguir a load e tem persisted: false. Nenhum dos dois deteta uma simples mudança de separador, e pageshow não prova que a página esteja visível. preventDefault() não impede estas transições.

beforeunload (BeforeUnloadEvent) pode ser emitido antes de fechar, recarregar ou abandonar a página. Chama preventDefault() para pedir uma confirmação; por compatibilidade com navegadores antigos, atribui também uma cadeia não vazia a event.returnValue. Devolver uma cadeia não vazia no manipulador é um mecanismo antigo de onbeforeunload, não de addEventListener(). A caixa de diálogo exige uma interação anterior do utilizador (ativação persistente), não é garantida e mostra texto definido pelo navegador.

Regista beforeunload apenas enquanto houver alterações por guardar e remove o listener depois de as guardar ou descartar. Nem pagehide nem beforeunload são fiáveis, sobretudo em dispositivos móveis. Guarda o trabalho à medida que avança e usa visibilitychange em document quando document.visibilityState === "hidden" como sinal adicional para guardar, não como prova de que a sessão terminou.

Exemplos

(() => {
  const element = typeof document === "undefined"
    ? new EventTarget()
    : document.createElement("div");
  const page = new EventTarget();

  element.addEventListener("wheel", (event) => {
    const unit = event.deltaMode;
    if (event.cancelable) event.preventDefault();
    console.log(`wheel: deltaY=${event.deltaY}, deltaMode=${unit}, canceled=${event.defaultPrevented}`);
  }, { passive: false });

  const logTransition = (event) => {
    console.log(`${event.type}: persisted=${event.persisted}`);
  };
  page.addEventListener("pagehide", logTransition);
  page.addEventListener("pageshow", logTransition);
  page.addEventListener("beforeunload", (event) => event.preventDefault());

  const wheel = typeof WheelEvent === "function"
    ? new WheelEvent("wheel", {
        deltaY: 3, deltaMode: WheelEvent.DOM_DELTA_LINE, cancelable: true
      })
    : Object.assign(new Event("wheel", { cancelable: true }), {
        deltaY: 3, deltaMode: 1 // Lines, as with WheelEvent.DOM_DELTA_LINE.
      });
  const transition = (type) => typeof PageTransitionEvent === "function"
    ? new PageTransitionEvent(type, { persisted: true })
    : Object.assign(new Event(type), { persisted: true });

  element.dispatchEvent(wheel);
  page.dispatchEvent(transition("pagehide"));
  page.dispatchEvent(transition("pageshow"));
  const result = page.dispatchEvent(new Event("beforeunload", { cancelable: true }));
  console.log(`beforeunload: dispatchEvent returned ${result}`);
})();

Resultado

wheel: deltaY=3, deltaMode=1, canceled=true
pagehide: persisted=true
pageshow: persisted=true
beforeunload: dispatchEvent returned false

Executa o código na consola do navegador ou em Node.js 24. No navegador, o evento sintético `wheel` é enviado a um elemento desligado do documento. Em Node.js, um `EventTarget` substitui o elemento e as propriedades de `wheel`, `pagehide` e `pageshow` são adicionadas a objetos `Event` genéricos. Em ambos os ambientes, um `EventTarget` separado substitui `window`. `false` significa que o evento de teste foi cancelado, não que a navegação foi bloqueada. O código não desloca a página, não a restaura a partir da bfcache nem abre uma caixa de diálogo.

Lições relacionadas

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

Fontes