DeviceMotionEventAcceleration — Schnittstelle · JavaScript-Referenz

Signatur

interface DeviceMotionEventAcceleration

Beschreibung

DeviceMotionEventAcceleration ist Teil der Spezifikation Device Orientation Events. Objekte dieses Typs erzeugt man nicht selbst. Man bekommt sie über die Eigenschaften acceleration und accelerationIncludingGravity eines DeviceMotionEvent, das der Browser beim Ereignis devicemotion auf window auslöst.

Das Objekt hat drei schreibgeschützte Eigenschaften:

x: Beschleunigung entlang der X-Achse (von links nach rechts, bei Blick auf den Bildschirm im Hochformat), in m/s².
y: Beschleunigung entlang der Y-Achse (von unten nach oben), in m/s².
z: Beschleunigung entlang der Z-Achse (senkrecht aus dem Bildschirm heraus), in m/s².

Jeder Wert ist eine number oder null, wenn der Sensor die Achse nicht liefern kann. acceleration enthält die reine Beschleunigung durch Bewegung, also ohne Schwerkraft. Dafür braucht es meist ein Gyroskop. accelerationIncludingGravity enthält die Rohwerte des Beschleunigungssensors einschließlich der Erdanziehung (ca. 9,81 m/s²). Diese Werte sind auf mehr Geräten verfügbar.

Typische Anwendungen sind Schüttel-Erkennung, Schrittzähler, Neige-Steuerung in Spielen und Bewegungsanalysen. Das Ereignis kommt sehr häufig (oft 60 Hz oder mehr). Die Auswertung sollte deshalb schlank bleiben oder gedrosselt werden.

Parameter

Name	Typ	Beschreibung
$x	number \| null	Schreibgeschützt. Beschleunigung entlang der X-Achse in m/s², oder `null`, wenn nicht verfügbar.
$y	number \| null	Schreibgeschützt. Beschleunigung entlang der Y-Achse in m/s², oder `null`, wenn nicht verfügbar.
$z	number \| null	Schreibgeschützt. Beschleunigung entlang der Z-Achse in m/s², oder `null`, wenn nicht verfügbar.

Beispiele

Beschleunigungswerte auslesen

const handleMotion = (event) => {
  const acc = event.accelerationIncludingGravity;
  if (!acc) return;
  const fmt = (v) => (v ?? 0).toFixed(2);
  console.log(`x: ${fmt(acc.x)}  y: ${fmt(acc.y)}  z: ${fmt(acc.z)} m/s²`);
};

window.addEventListener('devicemotion', handleMotion);

x: 0.12 y: 0.34 z: 9.79 m/s²

Berechtigung auf iOS anfragen (per Klick)

const startButton = document.querySelector('#start');

startButton.addEventListener('click', async () => {
  if (typeof DeviceMotionEvent?.requestPermission === 'function') {
    const state = await DeviceMotionEvent.requestPermission();
    if (state !== 'granted') {
      console.log('Zugriff auf Bewegungssensoren verweigert');
      return;
    }
  }
  window.addEventListener('devicemotion', (e) => {
    const { x, y, z } = e.acceleration ?? {};
    console.log('Lineare Beschleunigung:', x, y, z);
  });
});

Lineare Beschleunigung: 0.02 -0.01 0.05

Schüttel-Erkennung mit Schwellwert und Sperrzeit

const THRESHOLD = 15; // m/s²
const COOLDOWN = 1000; // ms
let lastShake = 0;

const onMotion = ({ acceleration }) => {
  if (!acceleration || acceleration.x === null) return;
  const { x, y, z } = acceleration;
  const magnitude = Math.hypot(x, y, z);
  const now = Date.now();
  if (magnitude > THRESHOLD && now - lastShake > COOLDOWN) {
    lastShake = now;
    console.log(`Schütteln erkannt (${magnitude.toFixed(1)} m/s²)`);
  }
};

window.addEventListener('devicemotion', onMotion);
// Später wieder abmelden:
// window.removeEventListener('devicemotion', onMotion);

Schütteln erkannt (18.4 m/s²)

// Wichtig · Fallstricke

Nur sicherer Kontext: Das Ereignis devicemotion wird nur über HTTPS (oder localhost) ausgelöst.
iOS/Safari ab 13: Vor dem Zugriff muss DeviceMotionEvent.requestPermission() aufgerufen werden, und zwar direkt aus einer Nutzeraktion wie einem Klick. Sonst kommen keine Ereignisse an.
null-Werte: Auf Geräten ohne Gyroskop ist acceleration oft null, oder alle Achsen sind null. Prüfen Sie immer auf null und weichen Sie bei Bedarf auf accelerationIncludingGravity aus.
Desktop: Viele Desktop-Browser lösen das Ereignis nie aus, oder nur mit null-Werten. Zum Testen eignen sich die Sensor-Emulation der DevTools oder ein echtes Mobilgerät.
Achsen und Ausrichtung: Die Achsen beziehen sich auf das Gerät, nicht auf den Bildschirm. Beim Drehen ins Querformat werden sie nicht automatisch mitgedreht.
Einheitliche Werte: Ältere Android-Browser lieferten teils umgekehrte Vorzeichen. Kalibrieren Sie bei kritischen Anwendungen selbst.
Datenschutz und Leistung: Bewegungsdaten können sich für Fingerprinting eignen. Manche Browser verringern deshalb Genauigkeit oder Frequenz. Melden Sie den Listener ab, wenn Sie ihn nicht mehr brauchen, das schont den Akku.
Die modernere Alternative ist die Generic Sensor API mit Accelerometer und LinearAccelerationSensor. Sie ist bisher vor allem in Chromium-Browsern verfügbar.

Siehe auch

Accelerometer DeviceMotionEventRotationRate DeviceMotionEvent DeviceOrientationEvent NavigationActivation