CKTIS / JavaScript
Eventos wheel, pagehide, pageshow y beforeunload
Distingue los gestos de rueda o panel táctil del desplazamiento, detecta una restauración desde la caché de historial y avisa si hay cambios sin guardar.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
element.addEventListener("wheel", onWheel, { passive: true });
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);
window.addEventListener("beforeunload", onBeforeUnload);
window.removeEventListener("beforeunload", onBeforeUnload);Estos eventos pertenecen a las API del navegador, no a ECMAScript 2024. Escucha wheel en un elemento y pagehide, pageshow y beforeunload en window. Los detalles de su comportamiento varían según el navegador.
wheel (WheelEvent) indica un gesto con la rueda del ratón o el panel táctil, no un desplazamiento real: el gesto puede cambiar el zoom o no mover nada, y el teclado permite desplazarse sin ese gesto. deltaX y deltaY describen el gesto; deltaMode indica la unidad: 0 para píxeles, 1 para líneas y 2 para páginas. Para detectar el movimiento real, compara scrollLeft y scrollTop en un listener de scroll. Para observar, usa { passive: true }. Si necesitas impedir el desplazamiento o el zoom predeterminados, usa { passive: false } y llama a preventDefault() solo si event.cancelable es true. Algunos navegadores solo permiten cancelar el primer evento de una secuencia.
pagehide y pageshow son de tipo PageTransitionEvent. Al salir de la página, pagehide con persisted: true indica que puede conservarse en la caché de navegación atrás/adelante (bfcache), sin garantía de restauración posterior. pageshow con persisted: true indica que se ha reanudado la misma página desde la bfcache; en la carga inicial, pageshow ocurre después de load y tiene persisted: false. Ninguno detecta un cambio de pestaña normal, y pageshow no demuestra que la página sea visible. preventDefault() no detiene estas transiciones.
beforeunload (BeforeUnloadEvent) puede dispararse antes de cerrar, recargar o abandonar la página. Llama a preventDefault() para solicitar un diálogo de confirmación; por compatibilidad con navegadores antiguos, asigna además una cadena no vacía a event.returnValue. Devolver una cadena no vacía desde el manejador es un mecanismo antiguo de onbeforeunload, no de addEventListener(). El diálogo requiere interacción previa del usuario (activación persistente), no está garantizado y usa texto elegido por el navegador.
Registra beforeunload solo mientras haya cambios sin guardar y elimina el listener después de guardarlos o descartarlos. Ni pagehide ni beforeunload son fiables, especialmente en móviles. Guarda a medida que se trabaja y usa visibilitychange en document cuando document.visibilityState === "hidden" como señal adicional para guardar, no como prueba de que la sesión terminó.
Ejemplos
(() => {
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
Ejecuta el código en la consola del navegador o en Node.js 24. En el navegador, el evento sintético `wheel` se envía a un elemento desconectado del documento. En Node.js, un `EventTarget` sustituye al elemento y se añaden las propiedades de `wheel`, `pagehide` y `pageshow` a objetos `Event` genéricos. En ambos entornos, un `EventTarget` separado sustituye a `window`. `false` significa que se canceló el evento de prueba, no que se bloqueó la navegación. El código no desplaza la página, no la restaura desde la bfcache ni abre un diálogo.
Lecciones relacionadas
- JavaScript · Lección 36 · Avanzado · Versión: 4
Fuentes
- 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