WheelEvent.deltaMode — Eigenschaft · JavaScript-Referenz

Signatur

WheelEvent.deltaMode

Beschreibung

WheelEvent.deltaMode gibt einen unsigned long zurück, der festlegt, wie die Delta-Werte eines Mausrad- oder Touchpad-Ereignisses zu deuten sind. Mögliche Werte sind:

0 – WheelEvent.DOM_DELTA_PIXEL: Die Deltas sind in Pixeln angegeben.
1 – WheelEvent.DOM_DELTA_LINE: Die Deltas sind in Zeilen angegeben.
2 – WheelEvent.DOM_DELTA_PAGE: Die Deltas sind in Seiten angegeben.

Die Eigenschaft ist immer dann wichtig, wenn du eigenes Scroll-Verhalten umsetzt – etwa Zoom in Karten, horizontales Scrollen in Galerien oder das Steuern von Canvas- und WebGL-Szenen. Ohne Auswertung von deltaMode kann ein deltaY von 3 je nach Browser und Gerät drei Pixel oder drei Zeilen (also etwa 50 Pixel) bedeuten.

In der Praxis liefern die meisten modernen Browser DOM_DELTA_PIXEL. Firefox meldet bei klassischen Mausrädern jedoch teilweise DOM_DELTA_LINE, und bei Einstellungen wie „Seitenweise scrollen“ kann unter Windows DOM_DELTA_PAGE auftreten. Robuster Code normalisiert die Werte daher immer auf Pixel.

Rückgabewert

Typ

number (0 | 1 | 2)

Beschreibung

0 (DOM_DELTA_PIXEL), 1 (DOM_DELTA_LINE) oder 2 (DOM_DELTA_PAGE). Der Wert ist schreibgeschützt.

Beispiele

Einheit des Scroll-Ereignisses ausgeben

const modes = {
  [WheelEvent.DOM_DELTA_PIXEL]: 'Pixel',
  [WheelEvent.DOM_DELTA_LINE]: 'Zeilen',
  [WheelEvent.DOM_DELTA_PAGE]: 'Seiten'
};

window.addEventListener('wheel', (event) => {
  console.log(`deltaY = ${event.deltaY} ${modes[event.deltaMode]}`);
}, { passive: true });

deltaY = 100 Pixel (z. B. Chrome) deltaY = 3 Zeilen (z. B. Firefox mit Mausrad)

Delta-Werte auf Pixel normalisieren

const LINE_HEIGHT = 16; // angenommene Zeilenhöhe in px

const toPixels = (event, delta) => {
  switch (event.deltaMode) {
    case WheelEvent.DOM_DELTA_LINE:
      return delta * LINE_HEIGHT;
    case WheelEvent.DOM_DELTA_PAGE:
      return delta * window.innerHeight;
    default:
      return delta; // bereits Pixel
  }
};

const gallery = document.querySelector('.gallery');

gallery.addEventListener('wheel', (event) => {
  event.preventDefault();
  // Vertikales Mausrad in horizontales Scrollen umwandeln
  gallery.scrollLeft += toPixels(event, event.deltaY);
}, { passive: false });

Gleichmäßiger Zoom für eine Canvas-Karte

const canvas = document.querySelector('canvas');
let zoom = 1;

canvas.addEventListener('wheel', (event) => {
  event.preventDefault();
  const factor = event.deltaMode === WheelEvent.DOM_DELTA_PIXEL ? 1 : 40;
  const pixels = event.deltaY * factor;
  zoom = Math.min(8, Math.max(0.25, zoom * Math.exp(-pixels * 0.001)));
  console.log(`Zoom: ${zoom.toFixed(2)}`);
}, { passive: false });

Zoom: 0.90 Zoom: 0.82

// Wichtig · Fallstricke

Nicht annehmen, dass immer Pixel geliefert werden: Firefox meldet bei Mausrädern häufig DOM_DELTA_LINE. Werte immer normalisieren, sonst scrollt oder zoomt die Anwendung in Firefox kaum merklich.
Firefox-Besonderheit: Firefox liefert DOM_DELTA_PIXEL, wenn deltaMode gelesen wird, bevor auf deltaX/deltaY zugegriffen wird (Schutz vor Fingerprinting und aus Kompatibilitätsgründen). Das Verhalten ist also teilweise von der Zugriffsreihenfolge abhängig.
Die tatsächliche Zeilenhöhe ist nicht standardisiert – Werte zwischen 16 und 40 px sind üblich. Wer es genau braucht, liest die berechnete line-height des Scroll-Containers per getComputedStyle() aus.
Zum Verhindern des Standard-Scrollens muss der Listener mit { passive: false } registriert werden; auf window/document sind wheel-Listener in Chrome standardmäßig passiv.
Die veralteten Ereignisse mousewheel und DOMMouseScroll besitzen kein deltaMode – stattdessen das Ereignis wheel verwenden.

Siehe auch

WheelEvent WheelEvent.deltaY WheelEvent.deltaX WheelEvent.deltaZ Element.scrollBy() StorageEvent.newValue