DeviceMotionEventRotationRate — Schnittstelle · JavaScript-Referenz

Signatur

interface DeviceMotionEventRotationRate

Beschreibung

DeviceMotionEventRotationRate gehört zu den Device Orientation Events. Ein Objekt dieses Typs erhältst du über die Eigenschaft rotationRate eines DeviceMotionEvent, das beim Ereignis devicemotion am window ausgelöst wird. Es stellt die Messwerte des Gyroskops bereit.

Das Objekt hat drei schreibgeschützte Eigenschaften, jeweils in Grad pro Sekunde:

alpha: Drehrate um die z-Achse, die senkrecht aus dem Bildschirm zeigt.
beta: Drehrate um die x-Achse, die von links nach rechts verläuft.
gamma: Drehrate um die y-Achse, die von unten nach oben verläuft.

Typische Einsatzfälle sind Spiele mit Bewegungssteuerung, Gesten wie „Schütteln“ oder „Drehen“, Panorama- und 360°-Ansichten sowie das Aufzeichnen von Bewegungsdaten. Anders als DeviceOrientationEvent, das die absolute Lage liefert, beschreibt rotationRate die Winkelgeschwindigkeit, also wie schnell sich die Lage gerade ändert.

Einen eigenen Konstruktor gibt es nicht. Die Objekte erzeugt der Browser. Nur über den DeviceMotionEvent-Konstruktor lassen sich eigene Werte mitgeben, zum Beispiel für Tests. Hat das Gerät kein Gyroskop, kann rotationRate oder jede einzelne Eigenschaft null sein.

Parameter

Name	Typ	Default	Beschreibung
$alpha	number \| null	null	Schreibgeschützt. Drehrate um die z-Achse in °/s.
$beta	number \| null	null	Schreibgeschützt. Drehrate um die x-Achse in °/s.
$gamma	number \| null	null	Schreibgeschützt. Drehrate um die y-Achse in °/s.

Rückgabewert

Typ

DeviceMotionEventRotationRate | null

Beschreibung

Kommt über DeviceMotionEvent.rotationRate. Ist null, wenn das Gerät keine Drehraten liefern kann.

Beispiele

Drehrate im devicemotion-Ereignis auslesen

const onMotion = (event) => {
  const rate = event.rotationRate;
  if (!rate) return; // kein Gyroskop vorhanden
  const { alpha, beta, gamma } = rate;
  console.log(`α: ${alpha?.toFixed(1)} °/s, β: ${beta?.toFixed(1)} °/s, γ: ${gamma?.toFixed(1)} °/s`);
};

window.addEventListener('devicemotion', onMotion);

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

α: 0.3 °/s, β: -12.4 °/s, γ: 5.1 °/s

Berechtigung auf iOS anfragen und schnelle Drehung erkennen

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

const detectTwist = (event) => {
  const gamma = event.rotationRate?.gamma ?? 0;
  // Schnelles Drehen des Handgelenks: über 300 °/s um die y-Achse
  if (Math.abs(gamma) > 300) {
    console.log('Dreh-Geste erkannt!', Math.round(gamma), '°/s');
  }
};

startButton.addEventListener('click', async () => {
  // iOS 13+ verlangt eine Nutzeraktion und eine ausdrückliche Erlaubnis
  if (typeof DeviceMotionEvent?.requestPermission === 'function') {
    const state = await DeviceMotionEvent.requestPermission();
    if (state !== 'granted') {
      console.warn('Zugriff auf Bewegungssensoren verweigert');
      return;
    }
  }
  window.addEventListener('devicemotion', detectTwist);
});

Dreh-Geste erkannt! 342 °/s

Drehraten zu einem Winkel aufsummieren

let angleZ = 0;

window.addEventListener('devicemotion', ({ rotationRate, interval }) => {
  const alpha = rotationRate?.alpha;
  if (alpha == null) return;
  // interval ist in Millisekunden angegeben
  angleZ += alpha * (interval / 1000);
  document.querySelector('#compass').style.transform = `rotate(${-angleZ}deg)`;
});

Eigene Werte für Tests mitgeben

const fakeEvent = new DeviceMotionEvent('devicemotion', {
  rotationRate: { alpha: 10, beta: 20, gamma: 30 },
  interval: 16
});

console.log(fakeEvent.rotationRate.beta);
window.dispatchEvent(fakeEvent);

20

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Die Werte gibt es nur über HTTPS (oder localhost). In iframes muss die Permissions-Policy die Sensoren freigeben, etwa mit allow="accelerometer; gyroscope".
iOS/Safari: Ab iOS 13 muss DeviceMotionEvent.requestPermission() innerhalb einer Nutzeraktion aufgerufen werden, zum Beispiel in einem Klick-Handler. Ohne diesen Aufruf kommen keine Ereignisse an.
Einheiten und Achsen: In der Spezifikation sind die Werte in °/s angegeben. Ältere Chrome-Versionen für Android lieferten rad/s. Wenn es auf Genauigkeit ankommt, auf dem Zielgerät prüfen. Die Zuordnung der Achsen hängt vom Koordinatensystem des Geräts ab und nicht von der Bildschirmausrichtung. Im Querformat musst du also selbst umrechnen, etwa mithilfe von screen.orientation.angle.
null-Werte: Desktop-Geräte ohne Gyroskop lösen das Ereignis teils trotzdem aus, liefern aber null. Deshalb immer optional verketten (?.) und mit ?? absichern.
Drift: Wer Drehraten über die Zeit aufsummiert, sammelt Fehler an. Für absolute Winkel ist deviceorientation besser geeignet.
Leistung: Das Ereignis kommt sehr häufig, oft mit 60 Hz oder mehr. Aufwendige DOM-Arbeit bündelst du am besten mit requestAnimationFrame. Abmelden (removeEventListener) spart Akku.
Datenschutz: Mit Bewegungssensoren lässt sich ein Gerät wiedererkennen (Fingerprinting). Manche Browser runden die Werte deshalb oder schränken sie ein.

Siehe auch

Gyroscope DeviceMotionEventAcceleration DeviceMotionEvent DeviceOrientationEvent NavigationDestination