CKTIS / JavaScript
Gli eventi wheel, pagehide, pageshow e beforeunload
Distingui i gesti con rotellina o touchpad dallo scorrimento, riconosci il ripristino dalla cache di navigazione e avvisa in caso di modifiche non salvate.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
element.addEventListener("wheel", onWheel, { passive: true });
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);
window.addEventListener("beforeunload", onBeforeUnload);
window.removeEventListener("beforeunload", onBeforeUnload);Questi eventi fanno parte delle API del browser, non di ECMAScript 2024. Ascolta wheel su un elemento e pagehide, pageshow e beforeunload su window. Alcuni dettagli del comportamento variano a seconda del browser.
wheel (WheelEvent) segnala un gesto di rotellina o touchpad, non uno scorrimento effettivo: il gesto può cambiare lo zoom o non spostare nulla, e la tastiera può far scorrere senza quel gesto. deltaX e deltaY descrivono il gesto; deltaMode ne indica l’unità: 0 per i pixel, 1 per le righe, 2 per le pagine. Per rilevare lo spostamento effettivo, confronta scrollLeft e scrollTop in un listener di scroll. Per osservare, usa { passive: true }. Se devi impedire lo scorrimento o lo zoom predefiniti, usa { passive: false } e chiama preventDefault() solo se event.cancelable è true. Alcuni browser consentono di annullare solo il primo evento di una sequenza.
pagehide e pageshow sono di tipo PageTransitionEvent. Quando lasci la pagina, pagehide con persisted: true indica che la pagina può essere conservata nella cache di navigazione indietro/avanti (bfcache), non che sarà sicuramente ripristinata. pageshow con persisted: true indica che la stessa pagina è stata ripresa dalla bfcache; al primo caricamento, pageshow segue load e ha persisted: false. Nessuno dei due rileva il semplice cambio di scheda e pageshow non dimostra che la pagina sia visibile. preventDefault() non interrompe queste transizioni.
beforeunload (BeforeUnloadEvent) può attivarsi prima di chiudere, ricaricare o lasciare la pagina. Chiama preventDefault() per richiedere una conferma; per compatibilità con i browser meno recenti, assegna anche una stringa non vuota a event.returnValue. Restituire una stringa non vuota dal gestore è un meccanismo legacy di onbeforeunload, non di addEventListener(). La finestra di dialogo richiede un’interazione precedente dell’utente (attivazione persistente), non è garantita e mostra un testo stabilito dal browser.
Registra beforeunload solo quando ci sono modifiche non salvate e rimuovi il listener dopo averle salvate o scartate. Né pagehide né beforeunload sono affidabili, soprattutto sui dispositivi mobili. Salva man mano che il lavoro procede e usa visibilitychange su document quando document.visibilityState === "hidden" come ulteriore segnale per salvare, non come prova della fine della sessione.
Esempi
(() => {
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}`);
})();Risultato
wheel: deltaY=3, deltaMode=1, canceled=true pagehide: persisted=true pageshow: persisted=true beforeunload: dispatchEvent returned false
Esegui il codice nella console del browser o in Node.js 24. Nel browser l’evento sintetico `wheel` viene inviato a un elemento scollegato dal documento. In Node.js un `EventTarget` sostituisce l’elemento e le proprietà di `wheel`, `pagehide` e `pageshow` vengono aggiunte a semplici oggetti `Event`. In entrambi gli ambienti un `EventTarget` separato sostituisce `window`. `false` significa che l’evento di prova è stato annullato, non che la navigazione è stata bloccata. Il codice non fa scorrere la pagina, non la ripristina dalla bfcache e non apre finestre di dialogo.
Lezioni correlate
- JavaScript · Lezione 36 · Avanzato · Versione: 4
Fonti
- 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