WheelEvent.deltaY — Eigenschaft · JavaScript-Referenz

Signatur

WheelEvent.deltaY

Beschreibung

WheelEvent.deltaY gibt an, wie weit der Benutzer mit dem Mausrad, Touchpad oder einem ähnlichen Eingabegerät vertikal gescrollt hat. Ein positiver Wert bedeutet Scrollen nach unten (zum Benutzer hin), ein negativer Wert Scrollen nach oben.

Die Einheit des Werts hängt von WheelEvent.deltaMode ab: 0 (DOM_DELTA_PIXEL) steht für Pixel, 1 (DOM_DELTA_LINE) für Zeilen und 2 (DOM_DELTA_PAGE) für Seiten. Die meisten Browser melden Pixel, Firefox liefert bei klassischen Mausrädern unter Umständen Zeilen.

Typische Einsatzzwecke sind eigene Scroll- und Zoom-Steuerungen (etwa Zoomen in Karten oder Bildbetrachtern), horizontale Karussells, die per vertikalem Rad bedient werden, oder Parallax-Effekte. Wenn man das Standardverhalten unterdrücken will, muss der Listener mit { passive: false } registriert werden, damit preventDefault() wirkt.

Wichtig: Das wheel-Event ist nicht dasselbe wie das scroll-Event. deltaY beschreibt die Eingabe des Geräts, nicht die tatsächliche Scrollposition des Dokuments. Es wird auch dann ausgelöst, wenn gar nichts gescrollt werden kann.

Rückgabewert

Typ

number

Beschreibung

Ein double: positiv beim Scrollen nach unten, negativ nach oben, 0 wenn keine vertikale Bewegung. Einheit gemäß deltaMode.

Beispiele

Scrollrichtung erkennen

window.addEventListener('wheel', (event) => {
  const richtung = event.deltaY > 0 ? 'nach unten' : event.deltaY < 0 ? 'nach oben' : 'keine';
  console.log(`deltaY: ${event.deltaY}, Richtung: ${richtung}`);
});

deltaY: 100, Richtung: nach unten

Zoom per Mausrad in einem Bildbetrachter

const bild = document.querySelector('#vorschau');
let zoom = 1;

bild.addEventListener('wheel', (event) => {
  event.preventDefault(); // Seitenscrollen verhindern
  // Faktor abhängig von der Stärke der Bewegung
  zoom *= Math.exp(-event.deltaY * 0.001);
  zoom = Math.min(Math.max(zoom, 0.5), 5);
  bild.style.transform = `scale(${zoom})`;
}, { passive: false });

deltaMode normalisieren und horizontal scrollen

const ZEILENHOEHE = 16;
const leiste = document.querySelector('.karussell');

const inPixel = (event) => {
  switch (event.deltaMode) {
    case WheelEvent.DOM_DELTA_LINE: return event.deltaY * ZEILENHOEHE;
    case WheelEvent.DOM_DELTA_PAGE: return event.deltaY * leiste.clientWidth;
    default: return event.deltaY;
  }
};

leiste.addEventListener('wheel', (event) => {
  if (event.deltaY === 0) return;
  event.preventDefault();
  leiste.scrollLeft += inPixel(event);
}, { passive: false });

// Wichtig · Fallstricke

Einheit prüfen: Man sollte deltaY nie ohne Blick auf deltaMode verwenden. Firefox meldet bei Mausrädern teils Zeilen (deltaMode === 1) mit Werten wie 3 statt 100.
Werte je nach Gerät unterschiedlich: Touchpads liefern viele kleine Werte mit Nachlauf (Trägheit), Mausräder wenige große Sprünge. Zuverlässig ist nur das Vorzeichen, nicht der Betrag. Für Aktionen „ein Schritt pro Raste“ eignet sich ein Throttling oder ein Schwellwert.
Pinch-Zoom: In Chrome, Edge und Firefox erzeugt eine Pinch-Geste auf dem Touchpad wheel-Events mit ctrlKey === true, bei denen deltaY den Zoom beschreibt.
Passive Listener: Auf window, document und body sind wheel-Listener standardmäßig passiv. preventDefault() wirkt nur mit { passive: false }. Das kann aber die Scroll-Leistung verschlechtern.
Umgekehrte Richtung: Die Einstellung „natürliches Scrollen“ unter macOS dreht das Vorzeichen um, und zwar schon auf Betriebssystemebene.
Das veraltete mousewheel-Event mit wheelDelta (umgekehrtes Vorzeichen, Vielfache von 120) sollte man nicht mehr verwenden.

Siehe auch

WheelEvent WheelEvent.deltaX WheelEvent.deltaZ WheelEvent.deltaMode Event.preventDefault()