Signatur
Beschreibung
Die schreibgeschützte Eigenschaft z der Schnittstelle Gyroscope gibt die aktuelle Winkelgeschwindigkeit um die z-Achse des Geräts in Radiant pro Sekunde (rad/s) zurück. Die z-Achse steht senkrecht zum Bildschirm und zeigt bei einem Smartphone zum Betrachter hin. Eine Drehung um diese Achse entspricht also dem Drehen des Geräts flach auf dem Tisch, wie bei einem Lenkrad oder einem Kompass.
Der Wert wird bei jedem neuen Messwert aktualisiert, den der Sensor meldet. Ein Messwert ist erst verfügbar, nachdem der Sensor mit start() gestartet wurde und das erste reading-Event ausgelöst hat. Vorher (oder nach einem Fehler) ist z gleich null. Positive Werte bedeuten eine Drehung gegen den Uhrzeigersinn, wenn man von der positiven Achse aus auf das Gerät blickt (Rechte-Hand-Regel).
Typische Anwendungen sind Spiele mit Lenksteuerung, Drehgesten, Stabilisierung von Kamerabildern und die Sensorfusion mit Accelerometer und Magnetometer. Wenn Sie nur eine absolute Ausrichtung brauchen, sind AbsoluteOrientationSensor oder RelativeOrientationSensor meist die bessere Wahl, weil Sie die Winkelgeschwindigkeit dann nicht selbst integrieren müssen.
Rückgabewert
null, wenn noch kein Messwert vorliegt.Beispiele
Drehung um die z-Achse live auslesen
if ('Gyroscope' in window) {
const gyro = new Gyroscope({ frequency: 30 });
gyro.addEventListener('reading', () => {
// Umrechnung von rad/s in Grad/s zur besseren Lesbarkeit
const gradProSek = gyro.z * 180 / Math.PI;
console.log(`z: ${gyro.z.toFixed(3)} rad/s (${gradProSek.toFixed(1)} °/s)`);
});
gyro.addEventListener('error', (e) => {
console.error(e.error.name, e.error.message);
});
gyro.start();
} else {
console.warn('Gyroscope wird nicht unterstützt.');
}Lenkwinkel für ein Spiel integrieren
const gyro = new Gyroscope({ frequency: 60 });
let lenkwinkel = 0; // in Radiant
let letzteZeit = null;
gyro.onreading = () => {
if (letzteZeit !== null) {
const dt = (gyro.timestamp - letzteZeit) / 1000; // ms -> s
lenkwinkel += gyro.z * dt;
// Auf ±90° begrenzen
lenkwinkel = Math.max(-Math.PI / 2, Math.min(Math.PI / 2, lenkwinkel));
}
letzteZeit = gyro.timestamp;
document.querySelector('#lenkrad').style.transform =
`rotate(${-lenkwinkel}rad)`;
};
gyro.start();Berechtigung prüfen und Drehgeste erkennen
const starteGestenErkennung = async () => {
const { state } = await navigator.permissions.query({ name: 'gyroscope' });
if (state === 'denied') {
console.warn('Zugriff auf das Gyroskop verweigert.');
return;
}
const gyro = new Gyroscope({ frequency: 20 });
const SCHWELLE = 3; // rad/s
gyro.addEventListener('reading', () => {
if (gyro.z > SCHWELLE) console.log('Schnelle Drehung nach links');
else if (gyro.z < -SCHWELLE) console.log('Schnelle Drehung nach rechts');
});
gyro.start();
// Nach 10 Sekunden stoppen, um Akku zu sparen
setTimeout(() => gyro.stop(), 10_000);
};
starteGestenErkennung();// Wichtig · Fallstricke
- Browser-Unterstützung: nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen die Generic Sensor API nicht. Prüfen Sie deshalb immer mit
'Gyroscope' in windowund sehen Sie einen Fallback über dasdevicemotion-Event (rotationRate.alpha, in Grad/s) vor. - Sicherer Kontext: Die API steht nur über HTTPS zur Verfügung. In iframes muss die Berechtigungsrichtlinie
gyroscopeerlaubt sein (allow="gyroscope"). - Einheit: Der Wert ist in rad/s angegeben, nicht in Grad/s wie bei
DeviceMotionEvent.rotationRate. - Drift: Wenn Sie
züber die Zeit aufsummieren, sammeln sich Messfehler an. Für stabile Winkel sollten Sie eine Sensorfusion oder einenOrientationSensorverwenden. - Bezugssystem: Standardmäßig beziehen sich die Achsen auf das Gerät. Mit
{ referenceFrame: 'screen' }werden sie an die aktuelle Bildschirmausrichtung angepasst. - Vor dem ersten
reading-Event ist der Wertnull. Methoden wietoFixed()werfen dann einen Fehler. - Aus Datenschutzgründen (Fingerprinting) können Browser die Abtastrate drosseln oder den Zugriff in Hintergrund-Tabs pausieren.