WheelEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface WheelEvent extends MouseEvent

Beschreibung

WheelEvent ist die Ereignisschnittstelle für das wheel-Event. Sie erbt von MouseEvent (und damit von UIEvent und Event) und stellt zusätzlich die Bewegungswerte auf drei Achsen bereit: deltaX (horizontal), deltaY (vertikal) und deltaZ (Tiefe). Die Eigenschaft deltaMode gibt an, in welcher Einheit diese Werte vorliegen: Pixel (WheelEvent.DOM_DELTA_PIXEL = 0), Zeilen (DOM_DELTA_LINE = 1) oder Seiten (DOM_DELTA_PAGE = 2).

Man setzt WheelEvent ein, wenn man auf Rad- oder Touchpad-Gesten reagieren möchte, ohne sich auf das tatsächliche Scrollen des Dokuments zu verlassen – etwa für Zoom in Karten und Bildbetrachtern, horizontale Karussells, eigene Scroll-Container, 3D-Szenen oder Zahleneingaben per Rad. Mit gedrückter Strg-Taste (ctrlKey) melden viele Browser auch Pinch-Zoom-Gesten des Touchpads als wheel-Event.

Wichtig: Das wheel-Event ist nicht dasselbe wie das scroll-Event. Es feuert auch dann, wenn nichts gescrollt werden kann, und die Delta-Werte sagen nichts Verlässliches über die tatsächliche Scrollstrecke aus. Wer auf Positionsänderungen reagieren will, nutzt scroll; wer auf die Geste selbst reagieren will, nutzt wheel.

Der Konstruktor new WheelEvent(type, options) erzeugt synthetische Ereignisse, z. B. für Tests. Solche Events sind isTrusted === false und lösen kein natives Scrollen aus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Praxis immer `"wheel"`.
$options	WheelEventInit	{}	Initialisierungsobjekt. Zusätzlich zu allen `MouseEventInit`-Feldern (`clientX`, `ctrlKey`, `bubbles`, `cancelable` …): `deltaX`, `deltaY`, `deltaZ` (`number`, Standard `0`) und `deltaMode` (`number`, Standard `0` = Pixel).

Rückgabewert

Typ

WheelEvent

Beschreibung

Beim Konstruktor eine neue WheelEvent-Instanz. Wichtige Eigenschaften (alle schreibgeschützt): deltaX, deltaY, deltaZ (number, positive deltaY = nach unten/vom Nutzer weg) und deltaMode (0|1|2).

Beispiele

Wheel-Ereignis abfangen und Werte auslesen

const box = document.querySelector('#box');

const modes = ['Pixel', 'Zeilen', 'Seiten'];

box.addEventListener('wheel', (event) => {
  console.log(
    `deltaX: ${event.deltaX}, deltaY: ${event.deltaY}, Einheit: ${modes[event.deltaMode]}`
  );
});

deltaX: 0, deltaY: 100, Einheit: Pixel

Zoom per Mausrad (auch Touchpad-Pinch mit ctrlKey)

const image = document.querySelector('#bild');
let scale = 1;

const onWheel = (event) => {
  // Verhindert das Scrollen bzw. den Browser-Zoom
  event.preventDefault();

  // Zeilen/Seiten grob in Pixel umrechnen
  const factor = event.deltaMode === WheelEvent.DOM_DELTA_LINE ? 16
    : event.deltaMode === WheelEvent.DOM_DELTA_PAGE ? 800 : 1;
  const delta = event.deltaY * factor;

  scale = Math.min(5, Math.max(0.2, scale * Math.exp(-delta * 0.001)));
  image.style.transform = `scale(${scale})`;
};

// passive: false ist nötig, damit preventDefault() wirkt
image.addEventListener('wheel', onWheel, { passive: false });

// Später wieder entfernen
// image.removeEventListener('wheel', onWheel);

Vertikales Rad in horizontales Scrollen umwandeln

const carousel = document.querySelector('.karussell');

carousel.addEventListener('wheel', (event) => {
  // Nur eingreifen, wenn überwiegend vertikal gedreht wird
  if (Math.abs(event.deltaY) > Math.abs(event.deltaX)) {
    event.preventDefault();
    carousel.scrollLeft += event.deltaY;
  }
}, { passive: false });

Synthetisches WheelEvent für Tests erzeugen

const target = document.body;

target.addEventListener('wheel', (e) => {
  console.log(e.type, e.deltaY, e.deltaMode, e.isTrusted);
});

const fake = new WheelEvent('wheel', {
  deltaY: 120,
  deltaMode: WheelEvent.DOM_DELTA_PIXEL,
  bubbles: true,
  cancelable: true
});

target.dispatchEvent(fake);

wheel 120 0 false

// Wichtig · Fallstricke

Passive Listener: Chrome, Edge und Firefox behandeln wheel-Listener auf window, document und document.body standardmäßig als passive: true. preventDefault() wird dort ignoriert (mit Konsolenwarnung). Wer das Scrollen unterdrücken will, muss { passive: false } explizit angeben – das kann aber die Scroll-Performance verschlechtern.
Delta-Werte sind nicht einheitlich: Betrag und deltaMode hängen von Browser, Betriebssystem, Gerät und Nutzereinstellungen ab. Firefox liefert bei klassischen Mausrädern teils DOM_DELTA_LINE, Chromium meist Pixel. Touchpads erzeugen viele kleine Events mit Trägheit (Momentum). Immer deltaMode prüfen und nur Richtung bzw. relative Größe auswerten.
Das Lesen von deltaMode vor den Delta-Werten kann in Firefox zu Zeilen-Einheiten führen; wer Pixel will, liest zuerst deltaY.
Performance: wheel feuert sehr häufig. Aufwendige Arbeit per requestAnimationFrame bündeln oder drosseln.
Veraltet: Die nicht standardisierten Events mousewheel und DOMMouseScroll sowie die Eigenschaften wheelDelta, wheelDeltaX, wheelDeltaY und detail nicht mehr verwenden.
Barrierefreiheit: Das Kapern des Scrollens (Scroll-Jacking) frustriert Nutzer; bieten Sie Tastatur- und Schaltflächen-Alternativen an.
Auf reinen Touch-Geräten wird bei Wischgesten kein wheel-Event ausgelöst – dort sind Pointer- bzw. Touch-Events zuständig.

Siehe auch

Element SVGElement TextEvent TimeEvent BlobEvent