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
- Element: wheel event
- WheelEvent: deltaMode property
- WheelEvent: WheelEvent() constructor
- Window: pagehide event
- Window: pageshow event
- HTML Standard: The PageTransitionEvent interface
- Window: beforeunload event
- HTML Standard: Preventing navigation
- Document: visibilitychange event
- EventTarget: dispatchEvent() method