DeviceMotionEvent.acceleration — Eigenschaft · JavaScript-Referenz

Signatur

DeviceMotionEvent.acceleration

Beschreibung

Die schreibgeschützte Eigenschaft acceleration des DeviceMotionEvent-Interfaces gibt an, wie stark das Gerät gerade beschleunigt wird, und zwar in Metern pro Sekunde zum Quadrat (m/s²). Der Wert ist ein DeviceMotionEventAcceleration-Objekt mit den Eigenschaften x, y und z. Die Achsen beziehen sich auf das Koordinatensystem des Geräts: x zeigt nach rechts, y zur Oberkante des Bildschirms und z aus dem Bildschirm heraus zum Betrachter.

Im Gegensatz zu accelerationIncludingGravity ist hier die Erdanziehung bereits herausgerechnet. Liegt das Gerät ruhig auf dem Tisch, liegen alle drei Werte also ungefähr bei 0. Für die Berechnung braucht das Gerät ein Gyroskop. Fehlt es, ist acceleration oft null oder die einzelnen Achsen sind null. Dann bleibt nur accelerationIncludingGravity.

Typische Einsatzgebiete sind Schüttel- und Stoßerkennung, Schrittzähler, Bewegungssteuerung in Spielen und Anwendungen, die Bewegungen aufzeichnen. Die Werte kommen über das Ereignis devicemotion am window-Objekt an, meist in einem festen Takt (siehe DeviceMotionEvent.interval, oft etwa 16 ms).

Rückgabewert

Typ

DeviceMotionEventAcceleration | null

Beschreibung

Ein Objekt mit den Eigenschaften x, y und z (jeweils number | null, in m/s², ohne Schwerkraft). Der Wert ist null, wenn das Gerät die Beschleunigung ohne Schwerkraft nicht bestimmen kann.

Beispiele

Beschleunigung live auslesen

const handleMotion = (event) => {
  const acc = event.acceleration;
  if (!acc || acc.x === null) {
    console.log('Keine Beschleunigung ohne Schwerkraft verfügbar');
    return;
  }
  console.log(`x: ${acc.x.toFixed(2)}, y: ${acc.y.toFixed(2)}, z: ${acc.z.toFixed(2)} m/s²`);
};

window.addEventListener('devicemotion', handleMotion);

x: 0.03, y: -0.12, z: 0.08 m/s²

Schütteln erkennen mit Schwellenwert und Entprellung

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

const onMotion = ({ acceleration }) => {
  if (!acceleration) return;
  const { x = 0, y = 0, z = 0 } = acceleration;
  const magnitude = Math.hypot(x ?? 0, y ?? 0, z ?? 0);
  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, z. B. beim Verlassen der Ansicht:
// window.removeEventListener('devicemotion', onMotion);

Schütteln erkannt (18.4 m/s²)

Berechtigung unter iOS anfordern (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 a = e.acceleration;
    console.log(a ? [a.x, a.y, a.z] : 'nicht verfügbar');
  });
});

[0.01, -0.04, 0.02]

// Wichtig · Fallstricke

Kann null sein: Geräte ohne Gyroskop (und viele Desktop-Rechner) liefern entweder null oder Achsenwerte von null. Prüfen Sie das immer und greifen Sie notfalls auf accelerationIncludingGravity zurück.
Sicherer Kontext: Das Ereignis devicemotion wird nur über HTTPS (oder localhost) ausgelöst.
iOS/Safari: Ab iOS 13 muss DeviceMotionEvent.requestPermission() aufgerufen werden, und zwar direkt aus einer Nutzeraktion heraus (z. B. einem Klick). Sonst kommen keine Ereignisse an.
Permissions-Policy: In iframes muss das Recht über allow="accelerometer; gyroscope" freigegeben sein.
Datenschutz: Bewegungsdaten eignen sich für Fingerprinting und können sogar Rückschlüsse auf Tastatureingaben erlauben. Browser verringern deshalb teilweise die Genauigkeit oder die Abtastrate.
Leistung: Das Ereignis feuert sehr häufig. Halten Sie den Handler schlank, bündeln Sie DOM-Änderungen über requestAnimationFrame und melden Sie den Listener mit removeEventListener ab, wenn er nicht mehr gebraucht wird. Das schont den Akku.
Die Achsen folgen dem Gerät, nicht der Bildschirmausrichtung. Wenn das Gerät ins Querformat gedreht wird, müssen Sie die Werte selbst umrechnen (siehe screen.orientation).

Siehe auch

DeviceMotionEventAcceleration.x DeviceMotionEvent.interval DeviceMotionEvent.rotationRate DeviceMotionEvent.accelerationIncludingGravity DeviceMotionEventAcceleration.y