Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Les événements wheel, pagehide, pageshow et beforeunload

Distinguez un geste de molette ou de pavé tactile du défilement, détectez une restauration depuis le cache de navigation et signalez les modifications non enregistrées.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

element.addEventListener("wheel", onWheel, { passive: true });
window.addEventListener("pagehide", onPageHide);
window.addEventListener("pageshow", onPageShow);
window.addEventListener("beforeunload", onBeforeUnload);
window.removeEventListener("beforeunload", onBeforeUnload);

Ces événements relèvent des API du navigateur, pas d’ECMAScript 2024. Écoutez wheel sur un élément, et pagehide, pageshow et beforeunload sur window. Certains détails de comportement varient selon le navigateur.

wheel (WheelEvent) signale un geste de molette ou de pavé tactile, pas un défilement réel : le geste peut zoomer ou ne rien déplacer, et le clavier peut faire défiler sans ce geste. deltaX et deltaY décrivent le geste ; deltaMode donne l’unité : 0 pour les pixels, 1 pour les lignes et 2 pour les pages. Pour détecter le mouvement réel, comparez scrollLeft et scrollTop dans un écouteur de scroll. Pour observer, utilisez { passive: true }. Si vous devez empêcher le défilement ou le zoom par défaut, utilisez { passive: false } et appelez preventDefault() seulement si event.cancelable vaut true. Certains navigateurs ne permettent d’annuler que le premier événement d’une série.

pagehide et pageshow sont de type PageTransitionEvent. En quittant une page, pagehide avec persisted: true indique qu’elle peut être conservée dans le cache de navigation arrière/avant (bfcache), sans garantie de restauration ultérieure. pageshow avec persisted: true indique que la même page a repris depuis le bfcache ; au chargement initial, pageshow suit load et a persisted: false. Aucun des deux ne suit les simples changements d’onglet, et pageshow ne prouve pas que la page est visible. preventDefault() n’arrête pas ces transitions.

beforeunload (BeforeUnloadEvent) peut se déclencher avant la fermeture, le rechargement ou le départ de la page. Appelez preventDefault() pour demander une confirmation ; pour les anciens navigateurs, assignez aussi une chaîne non vide à event.returnValue. Renvoyer une chaîne non vide depuis le gestionnaire est un ancien mécanisme propre à onbeforeunload, pas à addEventListener(). La boîte de dialogue exige une interaction préalable de l’utilisateur (activation persistante), n’est pas garantie et affiche un texte choisi par le navigateur.

N’installez l’écouteur beforeunload qu’en présence de modifications non enregistrées et retirez-le après leur enregistrement ou leur abandon. Ni pagehide ni beforeunload ne sont fiables, surtout sur mobile. Enregistrez au fil du travail et utilisez visibilitychange sur document lorsque document.visibilityState === "hidden" comme signal supplémentaire pour enregistrer, pas comme preuve de fin de session.

Exemples

(() => {
  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}`);
})();

Résultat

wheel: deltaY=3, deltaMode=1, canceled=true
pagehide: persisted=true
pageshow: persisted=true
beforeunload: dispatchEvent returned false

Exécutez le code dans la console du navigateur ou dans Node.js 24. Dans le navigateur, l’événement synthétique `wheel` est envoyé à un élément détaché. Dans Node.js, un `EventTarget` remplace l’élément et de simples objets `Event` portent les propriétés de `wheel`, `pagehide` et `pageshow`. Dans les deux environnements, un `EventTarget` distinct tient lieu de `window`. `false` signifie que l’événement de test a été annulé, pas que la navigation a été bloquée. Le code ne fait pas défiler la page, ne la restaure pas depuis le bfcache et n’ouvre pas de boîte de dialogue.

Leçons associées

  • JavaScript · Leçon 36 · Avancé · Version : 4

Sources