Signatur
Beschreibung
Die Eigenschaft x eines Gyroscope-Objekts gibt die zuletzt gemessene Winkelgeschwindigkeit um die x-Achse des Geräts in Radiant pro Sekunde (rad/s) zurück. Die x-Achse verläuft bei einem Smartphone im Hochformat waagerecht von links nach rechts über das Display. Eine Drehung um diese Achse entspricht also einem Vor- bzw. Zurückkippen des Geräts (Nicken, engl. „pitch“).
Der Wert wird bei jedem neuen Messwert aktualisiert. Wann das passiert, legt die im Konstruktor übergebene frequency fest. In der Regel liest man x im Handler des reading-Events. Solange der Sensor nicht gestartet wurde oder noch keinen Messwert geliefert hat, ist der Wert null.
Das Vorzeichen folgt der Rechte-Hand-Regel: Ein positiver Wert bedeutet eine Drehung gegen den Uhrzeigersinn, wenn man entlang der positiven x-Achse auf den Ursprung blickt. Das Bezugssystem lässt sich mit der Konstruktor-Option referenceFrame umstellen: "device" (Standard) oder "screen", das die Bildschirmausrichtung berücksichtigt.
Typische Anwendungen sind Gestenerkennung (z. B. Kippen zum Blättern), Spielsteuerung, Bildstabilisierung und die Fusion mit Beschleunigungsdaten zur Lagebestimmung.
Rückgabewert
null, solange noch kein Messwert vorliegt oder der Sensor gestoppt ist.Beispiele
Winkelgeschwindigkeit um die x-Achse auslesen
if ('Gyroscope' in window) {
const gyro = new Gyroscope({ frequency: 30 });
gyro.addEventListener('reading', () => {
console.log(`x: ${gyro.x.toFixed(3)} rad/s`);
});
gyro.addEventListener('error', (event) => {
console.error(event.error.name, event.error.message);
});
gyro.start();
} else {
console.warn('Gyroscope wird nicht unterstützt.');
}Kippgeste erkennen (Nicken nach vorn/hinten)
const SCHWELLE = 2; // rad/s
const gyro = new Gyroscope({ frequency: 60 });
let sperreBis = 0;
gyro.onreading = () => {
const jetzt = performance.now();
if (jetzt < sperreBis) return;
if (gyro.x > SCHWELLE) {
console.log('Nach hinten gekippt → vorherige Seite');
sperreBis = jetzt + 500;
} else if (gyro.x < -SCHWELLE) {
console.log('Nach vorn gekippt → nächste Seite');
sperreBis = jetzt + 500;
}
};
gyro.start();Berechtigung prüfen und Drehwinkel integrieren
const starteMessung = async () => {
const status = await navigator.permissions.query({ name: 'gyroscope' });
if (status.state === 'denied') {
console.warn('Zugriff auf das Gyroskop verweigert.');
return;
}
const gyro = new Gyroscope({ frequency: 50, referenceFrame: 'screen' });
let winkel = 0; // in Radiant
let letzterZeitpunkt = null;
gyro.addEventListener('reading', () => {
if (letzterZeitpunkt !== null) {
const dt = (gyro.timestamp - letzterZeitpunkt) / 1000; // ms → s
winkel += gyro.x * dt;
}
letzterZeitpunkt = gyro.timestamp;
});
gyro.start();
// Nach 3 Sekunden auswerten und stoppen
setTimeout(() => {
gyro.stop();
console.log(`Gesamtdrehung um x: ${(winkel * 180 / Math.PI).toFixed(1)}°`);
console.log(gyro.x); // nach stop()
}, 3000);
};
starteMessung();// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Generic Sensor API wird nur von Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet) unterstützt. Firefox und Safari kennen
Gyroscopenicht. Als Ausweichlösung dient dasdevicemotion-Event mitrotationRate.beta, das allerdings Grad pro Sekunde liefert statt Radiant. - Sicherer Kontext: Die Schnittstelle gibt es nur über HTTPS (oder
localhost). In iframes muss die Permissions Policygyroscopeerlaubt sein, sonst wird einSecurityErrorausgelöst. nullabfangen: Vor dem erstenreading-Event und nachstop()istxgleichnull. Ein Aufruf wiegyro.x.toFixed()außerhalb des Handlers wirft dann einenTypeError.- Drift: Integriert man Winkelgeschwindigkeiten zu einem Winkel auf, summieren sich Messfehler mit der Zeit. Für eine stabile Lagebestimmung ist
AbsoluteOrientationSensoroderRelativeOrientationSensorbesser geeignet, weil diese mehrere Sensoren kombinieren. - Datenschutz: Bewegungssensoren lassen sich für Fingerprinting oder zum Ausspähen von Eingaben missbrauchen. Browser begrenzen deshalb die Frequenz und können den Zugriff sperren, wenn der Tab nicht sichtbar ist.