WheelEvent.deltaZ — Eigenschaft · JavaScript-Referenz

Signatur

WheelEvent.deltaZ

Beschreibung

deltaZ gibt an, wie weit ein Eingabegerät entlang der z-Achse „gescrollt“ hat. Das ist die Achse senkrecht zur Bildschirmebene. Sie entspricht also einer Bewegung zum Betrachter hin oder von ihm weg. Die Eigenschaft gehört zum wheel-Ereignis, zusammen mit deltaX (horizontal) und deltaY (vertikal).

Mit normalen Mausrädern und Touchpads ist deltaZ praktisch immer 0. Werte ungleich null kommen nur von speziellen Geräten, etwa 3D-Mäusen (z. B. SpaceMouse), manchen Joysticks oder Grafiktabletts mit Zusatzachse. Das gilt auch nur, wenn Betriebssystem und Browser diese Achse weitergeben.

Die Einheit des Werts steht in deltaMode: 0 (DOM_DELTA_PIXEL) für Pixel, 1 (DOM_DELTA_LINE) für Zeilen und 2 (DOM_DELTA_PAGE) für Seiten. Positive Werte bedeuten meist eine Bewegung vom Nutzer weg, negative eine Bewegung zum Nutzer hin. Die genaue Richtung hängt aber vom Gerät ab.

Einsetzen kann man deltaZ zum Beispiel für 3D-Szenen (WebGL/Three.js), Zoom-Steuerungen oder CAD-Viewer. Dort liefert man damit eine zusätzliche Achse, falls das Gerät sie bereitstellt. Nutzer ohne ein solches Gerät brauchen immer eine Alternative, z. B. deltaY mit gedrückter Strg-Taste.

Rückgabewert

Typ

number

Beschreibung

Gleitkommazahl (double) mit der Scrollmenge entlang der z-Achse in der Einheit von deltaMode. Bei gewöhnlichen Mäusen und Touchpads ist der Wert 0.

Beispiele

deltaZ im wheel-Ereignis auslesen

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

box.addEventListener('wheel', (event) => {
  const modes = ['Pixel', 'Zeilen', 'Seiten'];
  console.log(`x=${event.deltaX}, y=${event.deltaY}, z=${event.deltaZ} (${modes[event.deltaMode]})`);
});

x=0, y=100, z=0 (Pixel)

3D-Kamera zoomen, mit Ersatz über Strg + Mausrad

const canvas = document.querySelector('canvas');
let cameraZ = 10;

// Zeilen/Seiten in Pixel umrechnen
const toPixels = (delta, mode) =>
  mode === WheelEvent.DOM_DELTA_LINE ? delta * 16 :
  mode === WheelEvent.DOM_DELTA_PAGE ? delta * window.innerHeight :
  delta;

canvas.addEventListener('wheel', (event) => {
  // z-Achse bevorzugen, sonst Strg + vertikales Scrollen
  let dz = event.deltaZ;
  if (dz === 0 && event.ctrlKey) dz = event.deltaY;
  if (dz === 0) return;

  event.preventDefault();
  cameraZ = Math.min(100, Math.max(1, cameraZ + toPixels(dz, event.deltaMode) * 0.01));
  console.log('Kamera-Z:', cameraZ.toFixed(2));
}, { passive: false });

Kamera-Z: 11.00

Synthetisches WheelEvent mit deltaZ (z. B. für Tests)

const target = document.body;

target.addEventListener('wheel', (e) => {
  console.log('deltaZ:', e.deltaZ, 'Modus:', e.deltaMode);
}, { once: true });

target.dispatchEvent(new WheelEvent('wheel', {
  deltaZ: -3,
  deltaMode: WheelEvent.DOM_DELTA_LINE,
  bubbles: true,
  cancelable: true
}));

deltaZ: -3 Modus: 1

// Wichtig · Fallstricke

Fast immer 0: Übliche Mäuse und Touchpads haben keine z-Achse. Baue deshalb keine Funktion, die nur über deltaZ bedienbar ist, sondern biete immer eine Alternative an (z. B. deltaY mit ctrlKey).
Einheit prüfen: Der Wert ist nur zusammen mit deltaMode sinnvoll. Firefox meldet beim Mausrad oft DOM_DELTA_LINE, Chromium meist DOM_DELTA_PIXEL.
Nur lesbar: Eine Zuweisung an event.deltaZ wird ignoriert. Eigene Werte lassen sich nur über den WheelEvent-Konstruktor setzen.
Passive Listener: Chrome behandelt wheel-Listener auf window, document und body standardmäßig als passiv. Wenn du preventDefault() aufrufen willst, musst du { passive: false } angeben.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Das veraltete Ereignis mousewheel und die Eigenschaft wheelDelta haben keine z-Achse.

Siehe auch

WheelEvent WheelEvent.deltaX WheelEvent.deltaY WheelEvent.deltaMode Event.preventDefault() FetchEvent.isReload