Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

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