Element: mousewheel — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("mousewheel", handler)

Beschreibung

Das Ereignis mousewheel war die frühe, proprietäre Lösung von Internet Explorer und WebKit, um Drehungen am Mausrad zu melden. Registriert wird es über element.addEventListener("mousewheel", handler) oder über die Eigenschaft element.onmousewheel. Der Handler erhält ein WheelEvent-Objekt, das zusätzlich die nicht standardisierten Eigenschaften wheelDelta, wheelDeltaX und wheelDeltaY hat.

Der Wert von wheelDelta ist in der Regel ein Vielfaches von 120 pro Raste. Ein positiver Wert heißt, dass nach oben bzw. vom Nutzer weg gescrollt wird. Beim Standard-Ereignis wheel ist das Vorzeichen von deltaY genau andersherum.

Für neuen Code solltest du immer das standardisierte wheel-Ereignis verwenden. Es läuft in allen modernen Browsern und liefert mit deltaX, deltaY, deltaZ und deltaMode genauere Werte. mousewheel ist nur noch wichtig, wenn du alten Code pflegst oder sehr alte Browser unterstützen musst.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"mousewheel"`.
$handler Pflicht	(event: WheelEvent) => void		Callback-Funktion. Sie erhält ein `WheelEvent` mit den proprietären Eigenschaften `wheelDelta`, `wheelDeltaX` und `wheelDeltaY`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `{ passive: false }`. Das ist nötig, wenn du `preventDefault()` aufrufen willst.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein WheelEvent.

Beispiele

Alten mousewheel-Handler registrieren

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

box.addEventListener('mousewheel', (event) => {
  // wheelDelta: +120 = eine Raste nach oben, -120 = eine Raste nach unten
  const richtung = event.wheelDelta > 0 ? 'hoch' : 'runter';
  console.log(`Scroll ${richtung}: ${event.wheelDelta}`);
});

Scroll runter: -120

Über die on-Property registrieren und wieder entfernen

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

liste.onmousewheel = (event) => {
  console.log('wheelDeltaY:', event.wheelDeltaY);
};

// Später wieder entfernen
liste.onmousewheel = null;

// Äquivalent mit removeEventListener
const onWheelAlt = (e) => console.log(e.wheelDelta);
liste.addEventListener('mousewheel', onWheelAlt);
liste.removeEventListener('mousewheel', onWheelAlt);

Zoom per Mausrad, moderner Weg mit wheel und Rückfall auf mousewheel

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

const aufZoom = (richtung) => {
  zoom = Math.min(4, Math.max(0.25, zoom + richtung * 0.1));
  bild.style.transform = `scale(${zoom})`;
};

if ('onwheel' in bild) {
  // Standard: deltaY > 0 bedeutet nach unten scrollen
  bild.addEventListener('wheel', (e) => {
    e.preventDefault();
    aufZoom(e.deltaY < 0 ? 1 : -1);
  }, { passive: false });
} else {
  // Rückfall für sehr alte Browser: Vorzeichen umgekehrt
  bild.addEventListener('mousewheel', (e) => {
    e.preventDefault();
    aufZoom(e.wheelDelta > 0 ? 1 : -1);
  }, { passive: false });
}

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: mousewheel steht in keiner Spezifikation. Firefox hat es nie unterstützt, dort gab es früher stattdessen DOMMouseScroll bzw. MozMousePixelScroll. Verwende wheel.
Umgekehrtes Vorzeichen: Bei wheelDelta ist ein positiver Wert ein Scrollen nach oben, bei deltaY von wheel ein Scrollen nach unten. Das wird bei Migrationen oft übersehen.
Keine festen Schrittgrößen: Der Wert 120 pro Raste gilt nicht für Touchpads und hochauflösende Mausräder. Dort kommen viele kleine Werte an.
Passive Listener: Chrome behandelt Mausrad-Listener auf window, document und body standardmäßig als passiv. Dort musst du { passive: false } angeben, sonst wird preventDefault() ignoriert.
Das Ereignis sagt nichts darüber aus, ob tatsächlich gescrollt wurde. Um auf die Scrollposition zu reagieren, verwende das Ereignis scroll.

Siehe auch

WheelEvent EventTarget.addEventListener() Element: auxclick Element: beforematch Element: mouseenter