CKTIS / JavaScript
Zdarzenia wheel, pagehide, pageshow i beforeunload
Odróżnij gest kółkiem lub gładzikiem od przewijania, rozpoznaj przywrócenie strony z pamięci historii i ostrzegaj przed utratą niezapisanych zmian.
Wersja: ECMAScript 2024 and the current web platform; runtime support varies
Składnia
element.addEventListener("wheel", onWheel, { passive: true });
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);
window.addEventListener("beforeunload", onBeforeUnload);
window.removeEventListener("beforeunload", onBeforeUnload);Te zdarzenia należą do API przeglądarki, a nie do ECMAScript 2024. Nasłuchuj wheel na elemencie, a pagehide, pageshow i beforeunload na window. Szczegóły działania zależą od przeglądarki.
wheel (WheelEvent) zgłasza gest kółkiem lub gładzikiem, nie faktyczne przewinięcie: gest może powiększać widok albo nie przesunąć treści, a przewijać można też klawiaturą. deltaX i deltaY opisują gest; deltaMode określa jednostkę: 0 to piksele, 1 to linie, 2 to strony. Aby wykryć rzeczywisty ruch treści, w obsłudze scroll porównuj scrollLeft i scrollTop. Do obserwacji użyj { passive: true }. Jeśli musisz zablokować domyślne przewijanie lub powiększanie, użyj { passive: false } i wywołaj preventDefault() tylko wtedy, gdy event.cancelable jest prawdziwe. W części przeglądarek można anulować tylko pierwsze zdarzenie serii.
pagehide i pageshow to zdarzenia typu PageTransitionEvent. Przy opuszczaniu strony pagehide z persisted: true oznacza, że strona może pozostać w pamięci nawigacji wstecz i dalej (bfcache), ale jej późniejsze przywrócenie nie jest gwarantowane. pageshow z persisted: true oznacza, że wznowiono tę samą stronę z bfcache; przy pierwszym wczytaniu pageshow następuje po load i ma persisted: false. Żadne z tych zdarzeń nie służy do wykrywania zwykłego przełączania kart, a pageshow nie dowodzi, że użytkownik widzi stronę. preventDefault() nie zatrzymuje tych przejść.
beforeunload (BeforeUnloadEvent) może wystąpić przed zamknięciem, przeładowaniem lub opuszczeniem strony. Wywołaj preventDefault(), aby poprosić o potwierdzenie; dla starszych przeglądarek ustaw też event.returnValue na niepusty ciąg. Zwrócenie niepustego ciągu z funkcji to starszy mechanizm działający z onbeforeunload, nie z addEventListener(). Dialog wymaga wcześniejszej interakcji użytkownika (sticky activation), nie jest gwarantowany i ma tekst ustalany przez przeglądarkę.
Podpinaj beforeunload tylko przy niezapisanych zmianach i odpinaj po ich zapisaniu lub odrzuceniu. Ani pagehide, ani beforeunload nie są pewne, zwłaszcza na urządzeniach mobilnych. Zapisuj dane w trakcie pracy i traktuj visibilitychange na document przy document.visibilityState === "hidden" jako dodatkowy sygnał do zapisu, nie jako dowód zakończenia sesji.
Przykłady
(() => {
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}`);
})();Wynik
wheel: deltaY=3, deltaMode=1, canceled=true pagehide: persisted=true pageshow: persisted=true beforeunload: dispatchEvent returned false
Uruchom kod w konsoli przeglądarki lub w Node.js 24. W przeglądarce `wheel` trafia do odłączonego elementu; w Node.js zastępuje go obiekt `EventTarget`, a właściwości zdarzeń `wheel`, `pagehide` i `pageshow` są ustawiane na zwykłych obiektach `Event`. W obu środowiskach osobny `EventTarget` zastępuje `window`. `false` oznacza anulowanie zdarzenia testowego, nie zatrzymanie nawigacji. Kod nie przewija strony, nie przywraca jej z bfcache ani nie otwiera dialogu.
Powiązane lekcje
- JavaScript · Lekcja 36 · Zaawansowany · Wersja: 4
Źródła
- 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