Signatur
Beschreibung
Mit new WheelEvent() erzeugst du selbst ein Ereignis, das wie eine Bewegung des Mausrads oder eine Scroll-Geste auf dem Touchpad aussieht. WheelEvent erbt von MouseEvent, UIEvent und Event. Im options-Objekt kannst du deshalb neben den Rad-Werten (deltaX, deltaY, deltaZ, deltaMode) auch alle Maus-Eigenschaften wie clientX, ctrlKey oder buttons und die allgemeinen Event-Optionen wie bubbles und cancelable angeben.
Typische Einsatzfälle sind automatisierte Tests, etwa für Zoom-Funktionen in Kartenansichten, Canvas-Editoren oder eigene Scroll-Container, und das Weiterleiten von Rad-Eingaben an ein anderes Element. Das erzeugte Ereignis gibst du mit element.dispatchEvent(event) aus. Dabei laufen die registrierten wheel-Listener ab.
Wichtig: Ein selbst erzeugtes Ereignis ist nicht vertrauenswürdig (event.isTrusted === false). Der Browser führt deshalb kein echtes Scrollen oder Zoomen aus. Es reagiert nur dein eigener JavaScript-Code darauf.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses, auf das Groß- und Kleinschreibung achtet. In der Praxis fast immer "wheel". |
|
| $options | WheelEventInit | {} | Optionales Konfigurationsobjekt. Zusätzlich zu allen Feldern von MouseEventInit (z. B. clientX, clientY, ctrlKey, shiftKey, buttons) und EventInit (bubbles, cancelable, composed) gibt es folgende Felder:
|
Rückgabewert
WheelEvent-Objekt mit den angegebenen Eigenschaften. Nicht angegebene Felder erhalten ihren Standardwert.Beispiele
Einfaches WheelEvent erzeugen und auslesen
const event = new WheelEvent('wheel', {
deltaY: 120,
deltaMode: WheelEvent.DOM_DELTA_PIXEL,
bubbles: true,
cancelable: true
});
console.log(event.type, event.deltaY, event.deltaMode, event.isTrusted);Zoom-Handler mit Strg+Mausrad im Test auslösen
const canvas = document.createElement('canvas');
document.body.append(canvas);
let zoom = 1;
canvas.addEventListener('wheel', (e) => {
if (!e.ctrlKey) return;
e.preventDefault();
// Negatives deltaY = hineinzoomen
zoom *= e.deltaY < 0 ? 1.1 : 0.9;
console.log('Zoom:', zoom.toFixed(2));
}, { passive: false });
// Simulierter Zoom-Schritt nach innen an Position (100, 50)
canvas.dispatchEvent(new WheelEvent('wheel', {
deltaY: -100,
ctrlKey: true,
clientX: 100,
clientY: 50,
bubbles: true,
cancelable: true
}));Rad-Eingaben von einem Overlay an einen Scroll-Container weiterleiten
const overlay = document.querySelector('#overlay');
const list = document.querySelector('#list');
list.addEventListener('wheel', (e) => {
// Synthetische Events scrollen nicht von selbst – daher manuell
if (!e.isTrusted) list.scrollBy(e.deltaX, e.deltaY);
});
overlay.addEventListener('wheel', (e) => {
e.preventDefault();
list.dispatchEvent(new WheelEvent('wheel', {
deltaX: e.deltaX,
deltaY: e.deltaY,
deltaMode: e.deltaMode,
clientX: e.clientX,
clientY: e.clientY
}));
}, { passive: false });// Wichtig · Fallstricke
- Kein Standardverhalten: Ereignisse, die du mit
dispatchEvent()auslöst, habenisTrusted === false. Der Browser scrollt oder zoomt dabei nicht. Das musst du bei Bedarf selbst erledigen, z. B. mitscrollBy(). bubblesundcancelablesind standardmäßigfalse. Echtewheel-Ereignisse steigen dagegen im DOM auf und lassen sich abbrechen. Setze beide Optionen daher ausdrücklich, wenn Listener an Elternelementen reagieren oderpreventDefault()wirken soll.deltaModebeachten: Echte Ereignisse können je nach Browser und Betriebssystem in Zeilen (DOM_DELTA_LINE) statt in Pixeln geliefert werden. Das betrifft vor allem Firefox mit einem klassischen Mausrad. Robuster Code rechnet die Werte deshalb passend um.- Passive Listener: Browser registrieren
wheel-Listener anwindow,documentundbodystandardmäßig als passiv. Dort wirdpreventDefault()ignoriert, solange du nicht{ passive: false }angibst. - Verwende nicht das veraltete Ereignis
mousewheelund nichtinitWheelEvent(). Der Konstruktor ist der Standardweg. - Kompatibilität: Der Konstruktor wird in allen modernen Browsern unterstützt. Internet Explorer unterstützt ihn nicht.