DeviceMotionEvent.accelerationIncludingGravity — Eigenschaft · JavaScript-Referenz

Signatur

DeviceMotionEvent.accelerationIncludingGravity

Beschreibung

Die Eigenschaft accelerationIncludingGravity eines DeviceMotionEvent liefert ein DeviceMotionEventAcceleration-Objekt mit den Feldern x, y und z. Jeder Wert gibt die Beschleunigung entlang der jeweiligen Geräteachse in Metern pro Quadratsekunde (m/s²) an – inklusive des Anteils der Schwerkraft (ca. 9,81 m/s²).

Liegt ein Smartphone flach und ruhig auf dem Tisch, zeigt z daher etwa 9.81 (bzw. je nach Plattform -9.81), während x und y nahe 0 liegen. Das macht die Eigenschaft ideal, um die Neigung des Geräts zu bestimmen, z. B. für Kugel-Labyrinth-Spiele, Wasserwaagen oder Schüttelerkennung.

Viele Geräte besitzen kein Gyroskop, mit dem sich die Schwerkraft herausrechnen lässt. In diesem Fall ist acceleration (ohne Schwerkraft) null, accelerationIncludingGravity aber verfügbar, weil sie direkt vom Beschleunigungssensor stammt. Sie ist deshalb oft die verlässlichere Datenquelle.

Die Werte erhält man über das Ereignis devicemotion auf window – per window.addEventListener("devicemotion", handler) oder window.ondevicemotion. Das Ereignis feuert in regelmäßigen Abständen (siehe DeviceMotionEvent.interval).

Rückgabewert

Typ

DeviceMotionEventAcceleration | null

Beschreibung

Objekt mit den Eigenschaften x, y und z (jeweils number oder null) in m/s², inklusive Schwerkraft. null, wenn der Sensor keine Daten liefern kann.

Beispiele

Rohwerte des Beschleunigungssensors anzeigen

const handleMotion = (event) => {
  const acc = event.accelerationIncludingGravity;
  if (!acc) return;
  console.log(`x: ${acc.x?.toFixed(2)}  y: ${acc.y?.toFixed(2)}  z: ${acc.z?.toFixed(2)}`);
};

window.addEventListener("devicemotion", handleMotion);

// Nach 5 Sekunden wieder abmelden, um Akku zu sparen
setTimeout(() => window.removeEventListener("devicemotion", handleMotion), 5000);

x: 0.03 y: -0.12 z: 9.79 (Gerät flach auf dem Tisch)

Neigungswinkel für eine Wasserwaage berechnen

const level = document.querySelector("#level");

window.ondevicemotion = ({ accelerationIncludingGravity: g }) => {
  if (!g || g.x === null) return;
  // Neigung um die Längs- und Querachse in Grad
  const roll = Math.atan2(g.x, g.z) * (180 / Math.PI);
  const pitch = Math.atan2(g.y, Math.hypot(g.x, g.z)) * (180 / Math.PI);
  level.textContent = `Roll: ${roll.toFixed(1)}°, Pitch: ${pitch.toFixed(1)}°`;
};

Roll: 0.2°, Pitch: -0.7°

Schütteln erkennen – mit iOS-Berechtigungsabfrage

const THRESHOLD = 25; // m/s²
let lastShake = 0;

const onMotion = (event) => {
  const { x, y, z } = event.accelerationIncludingGravity ?? {};
  if (x == null) return;
  const magnitude = Math.hypot(x, y, z);
  const now = Date.now();
  if (magnitude > THRESHOLD && now - lastShake > 1000) {
    lastShake = now;
    console.log("Gerät wurde geschüttelt!", magnitude.toFixed(1));
  }
};

document.querySelector("#start").addEventListener("click", async () => {
  // iOS 13+ verlangt eine Freigabe durch Nutzergeste
  if (typeof DeviceMotionEvent.requestPermission === "function") {
    const state = await DeviceMotionEvent.requestPermission();
    if (state !== "granted") return console.warn("Zugriff verweigert");
  }
  window.addEventListener("devicemotion", onMotion);
});

Gerät wurde geschüttelt! 31.4

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Das Ereignis devicemotion wird ausschließlich über HTTPS (oder localhost) ausgelöst.
iOS/Safari: Seit iOS 13 muss DeviceMotionEvent.requestPermission() innerhalb einer Nutzergeste (z. B. Klick) aufgerufen werden, sonst kommen keine Ereignisse an.
Vorzeichen unterscheiden sich: Je nach Browser/Plattform (ältere Android-Versionen vs. iOS) können die Achsen invertiert sein. Werte vor produktivem Einsatz auf Zielgeräten kalibrieren.
Werte können null sein: Desktop-Browser feuern das Ereignis teils mit null-Werten oder gar nicht. Immer auf null prüfen.
Performance & Akku: Das Ereignis feuert sehr häufig (oft 60 Hz). Aufwendige Berechnungen drosseln oder mit requestAnimationFrame entkoppeln und Listener entfernen, wenn sie nicht gebraucht werden.
Datenschutz: Bewegungssensordaten können für Fingerprinting missbraucht werden; in iframes ist der Zugriff per Permissions-Policy (accelerometer) steuerbar.
Die Werte hängen von der Geräteausrichtung ab, nicht von der Bildschirmausrichtung – bei gedrehtem Bildschirm ggf. screen.orientation.angle berücksichtigen.

Siehe auch

DeviceMotionEventAcceleration.z DeviceMotionEvent.acceleration DeviceMotionEvent.rotationRate DeviceMotionEvent.interval DeviceMotionEventAcceleration.y