DeviceMotionEventAcceleration.z — Eigenschaft · JavaScript-Referenz

Signatur

DeviceMotionEventAcceleration.z

Beschreibung

Die Eigenschaft z eines DeviceMotionEventAcceleration-Objekts gibt an, wie stark das Gerät entlang der Z-Achse beschleunigt wird. Die Einheit ist Meter pro Sekunde zum Quadrat (m/s²). Die Z-Achse steht senkrecht auf dem Bildschirm und zeigt vom Display weg zum Betrachter: Positive Werte bedeuten eine Beschleunigung nach „oben“ aus dem Bildschirm heraus.

Du bekommst das Objekt über das Event devicemotion, und zwar in zwei Varianten:

event.acceleration: Beschleunigung ohne Erdanziehung. Liegt ein Gerät ruhig auf dem Tisch, ist z hier ungefähr 0.
event.accelerationIncludingGravity: Beschleunigung mit Erdanziehung. Liegt das Gerät mit dem Display nach oben flach auf dem Tisch, ist z hier ungefähr 9.81.

Typische Einsatzzwecke sind: erkennen, ob das Gerät mit dem Display nach oben oder nach unten liegt, Schüttel- und Stoßgesten, Schrittzähler sowie Steuerungen für Spiele oder AR. Weil Sensordaten verrauscht sind, solltest du die Werte in der Praxis glätten (z. B. mit einem Tiefpassfilter) oder mit Schwellenwerten arbeiten.

Rückgabewert

Typ

number | null

Beschreibung

Die Beschleunigung entlang der Z-Achse in m/s² als Gleitkommazahl oder null, wenn die Hardware bzw. der Browser keinen Wert liefern kann.

Beispiele

Z-Beschleunigung mit addEventListener auslesen

const handleMotion = (event) => {
  const z = event.accelerationIncludingGravity?.z;
  if (z == null) {
    console.log('Kein Z-Wert verfügbar');
    return;
  }
  console.log(`Z (inkl. Schwerkraft): ${z.toFixed(2)} m/s²`);
};

window.addEventListener('devicemotion', handleMotion);

// Später wieder abmelden, z. B. beim Verlassen der Ansicht:
// window.removeEventListener('devicemotion', handleMotion);

Z (inkl. Schwerkraft): 9.79 m/s²

Erkennen, ob das Display nach oben oder unten zeigt

const statusEl = document.querySelector('#status');

window.ondevicemotion = ({ accelerationIncludingGravity: g }) => {
  if (!g || g.z === null) return;

  if (g.z > 8) {
    statusEl.textContent = 'Display zeigt nach oben';
  } else if (g.z < -8) {
    statusEl.textContent = 'Display zeigt nach unten';
  } else {
    statusEl.textContent = 'Gerät ist geneigt oder steht aufrecht';
  }
};

Display zeigt nach oben

Berechtigung unter iOS anfordern und Stöße entlang Z erkennen

const THRESHOLD = 12; // m/s², ohne Schwerkraft

const onMotion = (event) => {
  const z = event.acceleration?.z ?? 0;
  if (Math.abs(z) > THRESHOLD) {
    console.log(`Stoß erkannt: ${z.toFixed(1)} m/s²`);
  }
};

document.querySelector('#start').addEventListener('click', async () => {
  // iOS 13+ verlangt eine ausdrückliche Zustimmung nach einer Nutzeraktion
  if (typeof DeviceMotionEvent?.requestPermission === 'function') {
    const state = await DeviceMotionEvent.requestPermission();
    if (state !== 'granted') {
      console.log('Zugriff auf Bewegungssensoren verweigert');
      return;
    }
  }
  window.addEventListener('devicemotion', onMotion);
});

Stoß erkannt: -14.3 m/s²

Werte mit einem Tiefpassfilter glätten

let smoothedZ = 0;
const ALPHA = 0.1; // kleiner = glatter, aber träger

window.addEventListener('devicemotion', (event) => {
  const z = event.accelerationIncludingGravity?.z;
  if (z == null) return;
  smoothedZ = ALPHA * z + (1 - ALPHA) * smoothedZ;
  console.log(`Geglättet: ${smoothedZ.toFixed(2)}`);
});

Geglättet: 9.80

// Wichtig · Fallstricke

Kann null sein: Auf Desktop-Rechnern ohne Beschleunigungssensor oder wenn der Browser keine schwerkraftbereinigten Werte berechnen kann, ist event.acceleration.z (oder das ganze Objekt) null. Prüfe das immer, bevor du rechnest.
Mit oder ohne Schwerkraft: Verwechsle acceleration und accelerationIncludingGravity nicht. Ruhig liegend ergibt das eine ≈ 0, das andere ≈ 9,81 m/s².
Vorzeichen unterscheiden sich: Ältere Android-Browser und alte iOS-Versionen haben bei accelerationIncludingGravity teilweise umgekehrte Vorzeichen geliefert. Teste deshalb auf echten Zielgeräten.
Berechtigungen: Die API funktioniert nur in sicheren Kontexten (HTTPS). Safari ab iOS 13 verlangt DeviceMotionEvent.requestPermission(), und dieser Aufruf muss durch eine Nutzeraktion ausgelöst werden. Mit einer Permissions Policy (accelerometer) lässt sich der Zugriff in iframes sperren.
Datenschutz: Bewegungsdaten eignen sich für Fingerprinting. Manche Browser verringern deshalb die Genauigkeit oder die Abtastrate.
Leistung: Das Event wird sehr oft ausgelöst (typisch alle 16–60 ms, siehe event.interval). Halte den Handler schlank, führe DOM-Aktualisierungen gebündelt über requestAnimationFrame aus und melde den Listener ab, wenn du ihn nicht mehr brauchst. Das spart Akku.
Für neue Projekte ist die moderne Generic Sensor API (Accelerometer, LinearAccelerationSensor) eine Alternative. Sie wird aber bisher nur von Chromium-Browsern unterstützt.

Siehe auch

DeviceMotionEventAcceleration.x DeviceMotionEventAcceleration.y DeviceMotionEvent.acceleration DeviceMotionEvent.rotationRate DeviceMotionEvent.interval