MouseScrollEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface MouseScrollEvent extends MouseEvent

Beschreibung

Die Schnittstelle MouseScrollEvent stellt Ereignisse dar, die ausgelöst werden, wenn der Benutzer ein Mausrad oder ein ähnliches Eingabegerät (z. B. ein Touchpad mit Scroll-Geste) bewegt. Sie ist eine proprietäre Erweiterung von Gecko (Firefox) und wurde nie standardisiert. Die zugehörigen Ereignisse heißen DOMMouseScroll (Scrollen in Zeilen) und MozMousePixelScroll (Scrollen in Pixeln).

MouseScrollEvent erbt von MouseEvent und bietet deshalb Eigenschaften wie clientX, shiftKey oder ctrlKey. Die eigentliche Scroll-Information steckt in zwei Eigenschaften:

detail (von UIEvent geerbt): Anzahl der gescrollten Zeilen (bei DOMMouseScroll) bzw. Pixel (bei MozMousePixelScroll). Positive Werte bedeuten nach unten/rechts, negative nach oben/links. Bei seitenweisem Scrollen liefert DOMMouseScroll den Wert ±32768 (UIEvent.SCROLL_PAGE_DOWN/SCROLL_PAGE_UP).
axis: die Scrollachse, entweder MouseScrollEvent.HORIZONTAL_AXIS (1) oder MouseScrollEvent.VERTICAL_AXIS (2).

In modernem Code solltest du MouseScrollEvent nicht mehr verwenden. Das standardisierte wheel-Ereignis mit der Schnittstelle WheelEvent (deltaX, deltaY, deltaZ, deltaMode) funktioniert in allen aktuellen Browsern, auch in Firefox. Die Schnittstelle ist nur noch relevant, wenn du alten Code verstehen oder warten musst, der sehr alte Firefox-Versionen unterstützt.

Parameter

Name	Typ	Default	Beschreibung
$detail	number		Geerbt von `UIEvent`: Scrollmenge in Zeilen (`DOMMouseScroll`) oder Pixeln (`MozMousePixelScroll`). Vorzeichen gibt die Richtung an.
$axis	number		Scrollachse: `1` (`HORIZONTAL_AXIS`) oder `2` (`VERTICAL_AXIS`). Nur lesbar.
$HORIZONTAL_AXIS	number	1	Konstante für die horizontale Achse.
$VERTICAL_AXIS	number	2	Konstante für die vertikale Achse.

Rückgabewert

Typ

MouseScrollEvent

Beschreibung

Das Ereignisobjekt, das an Handler für DOMMouseScroll bzw. MozMousePixelScroll übergeben wird.

Beispiele

Legacy: DOMMouseScroll in altem Firefox-Code auswerten

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

const onLegacyScroll = (event) => {
  // axis: 1 = horizontal, 2 = vertikal
  const achse = event.axis === 1 ? 'horizontal' : 'vertikal';
  const richtung = event.detail > 0 ? 'vorwärts' : 'rückwärts';
  console.log(`${achse}, ${richtung}, ${Math.abs(event.detail)} Zeilen`);
};

box.addEventListener('DOMMouseScroll', onLegacyScroll);

// Später wieder abmelden
// box.removeEventListener('DOMMouseScroll', onLegacyScroll);

vertikal, vorwärts, 3 Zeilen

Moderner Ersatz: wheel-Ereignis mit WheelEvent

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

karte.addEventListener('wheel', (event) => {
  event.preventDefault(); // Seitenscrollen verhindern
  zoom *= event.deltaY < 0 ? 1.1 : 0.9;
  zoom = Math.min(Math.max(zoom, 0.5), 4);
  karte.style.transform = `scale(${zoom})`;
  console.log('Zoom:', zoom.toFixed(2));
}, { passive: false });

Zoom: 1.10

Migration: altes und neues Ereignis vereinheitlichen

const normalisiereScroll = (event) => {
  if (event.type === 'wheel') {
    // deltaMode 1 = Zeilen, 0 = Pixel
    return event.deltaMode === 1 ? event.deltaY * 16 : event.deltaY;
  }
  if (event.type === 'DOMMouseScroll') {
    return event.detail * 16; // Zeilen grob in Pixel umrechnen
  }
  return 0;
};

const handler = (event) => {
  console.log('Pixel:', normalisiereScroll(event));
};

// 'onwheel' in window prüft die Unterstützung des Standard-Ereignisses
const typ = 'onwheel' in window ? 'wheel' : 'DOMMouseScroll';
window.addEventListener(typ, handler, { passive: true });

Pixel: 100

// Wichtig · Fallstricke

Nicht standardisiert und veraltet: Die Schnittstelle gab es nur in Gecko/Firefox. Chrome, Safari und Edge haben sie nie unterstützt. Verwende stattdessen wheel/WheelEvent, das Firefox seit Version 17 unterstützt.
Die frühere Methode initMouseScrollEvent() wurde entfernt. Synthetische Scroll-Ereignisse erzeugst du mit new WheelEvent('wheel', {...}).
Die Richtung von detail ist beim alten mousewheel-Ereignis (WebKit, wheelDelta) umgekehrt. Bei gemischtem Legacy-Code führt das oft zu Fehlern bei der Richtung.
Registriere nie gleichzeitig wheel und DOMMouseScroll, sonst verarbeitest du dieselbe Radbewegung in Firefox doppelt.
Leistung: Rufst du im wheel-Handler preventDefault() auf, musst du ihn mit { passive: false } registrieren. Das kann das Scrollen ruckeln lassen. Ohne Abbruch lieber { passive: true } verwenden.

Siehe auch

MouseEvent XRSessionEvent CustomEvent ErrorEvent InstallEvent