Gyroscope — Schnittstelle · JavaScript-Referenz

Signatur

interface Gyroscope extends Sensor

Beschreibung

Gyroscope gehört zur Generic Sensor API und erbt von Sensor (und damit von EventTarget). Ein Objekt dieser Klasse liest den eingebauten Gyroskop-Sensor des Geräts aus. Die Eigenschaften x, y und z enthalten die aktuelle Winkelgeschwindigkeit um die jeweilige Achse in rad/s. Solange noch kein Messwert vorliegt oder der Sensor nicht aktiv ist, haben sie den Wert null.

Typische Einsatzgebiete sind Bewegungssteuerung in Spielen, 360°-Ansichten und VR-Viewer, Gestenerkennung (z. B. Schütteln oder Drehen) und Bildstabilisierung. Wer nur die Ausrichtung des Geräts braucht, greift besser zu AbsoluteOrientationSensor bzw. RelativeOrientationSensor, die Gyroskop, Beschleunigungssensor und ggf. Magnetometer bereits verrechnen.

Ablauf: Sensor mit new Gyroscope(options) anlegen, auf die Events reading und error hören und mit start() die Messung starten. Mit stop() wird der Sensor wieder abgeschaltet. Das spart Akku und sollte immer passieren, wenn keine Werte mehr gebraucht werden.

Die Schnittstelle gibt es nur in einem sicheren Kontext (HTTPS). Außerdem muss die Berechtigung gyroscope erteilt sein und die Permissions Policy gyroscope den Zugriff erlauben. Das gilt besonders in <iframe>-Elementen.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt für den Konstruktor `new Gyroscope(options)`.
$options.frequency	number	gerätespezifisch	Gewünschte Messrate in Hertz (Messungen pro Sekunde). Das ist nur ein Wunsch: Die tatsächliche Rate kann niedriger ausfallen.
$options.referenceFrame	"device" \| "screen"	"device"	Bezugssystem der Achsen: `"device"` nutzt die Geräteachsen, `"screen"` die aktuelle Bildschirmausrichtung (berücksichtigt also Hoch- und Querformat).

Rückgabewert

Typ

Gyroscope

Beschreibung

Eine neue Gyroscope-Instanz. Wichtige Mitglieder: x, y, z (number | null, rad/s), geerbt von Sensor: activated, hasReading, timestamp, start(), stop() sowie die Events reading, activate und error.

Beispiele

Gyroskop instanziieren und Messwerte ausgeben

if ('Gyroscope' in window) {
  const gyro = new Gyroscope({ frequency: 30 });

  gyro.addEventListener('reading', () => {
    console.log(`x: ${gyro.x.toFixed(3)} rad/s, y: ${gyro.y.toFixed(3)} rad/s, z: ${gyro.z.toFixed(3)} rad/s`);
  });

  gyro.addEventListener('error', (event) => {
    console.error(`${event.error.name}: ${event.error.message}`);
  });

  gyro.start();
} else {
  console.warn('Gyroscope wird von diesem Browser nicht unterstützt.');
}

x: 0.012 rad/s, y: -0.004 rad/s, z: 0.031 rad/s ...

Berechtigung prüfen und Fehler sauber behandeln

const startGyroscope = async () => {
  if (!('Gyroscope' in window)) {
    throw new Error('Nicht unterstützt');
  }

  const { state } = await navigator.permissions.query({ name: 'gyroscope' });
  if (state === 'denied') {
    throw new Error('Zugriff auf das Gyroskop wurde verweigert.');
  }

  try {
    const gyro = new Gyroscope({ frequency: 60, referenceFrame: 'screen' });
    gyro.onerror = (event) => {
      if (event.error.name === 'NotAllowedError') {
        console.error('Berechtigung fehlt.');
      } else if (event.error.name === 'NotReadableError') {
        console.error('Sensor ist nicht verfügbar.');
      }
    };
    gyro.start();
    return gyro;
  } catch (error) {
    // SecurityError z. B. durch Permissions Policy
    console.error('Sensor konnte nicht erstellt werden:', error.name);
  }
};

startGyroscope().catch((err) => console.warn(err.message));

Schüttel- bzw. Drehgeste erkennen und Sensor stoppen

const gyro = new Gyroscope({ frequency: 50 });
const THRESHOLD = 5; // rad/s

const onReading = () => {
  const magnitude = Math.hypot(gyro.x, gyro.y, gyro.z);
  if (magnitude > THRESHOLD) {
    console.log(`Schnelle Drehung erkannt (${magnitude.toFixed(1)} rad/s)`);
    gyro.removeEventListener('reading', onReading);
    gyro.stop(); // Akku schonen
  }
};

gyro.addEventListener('reading', onReading);
gyro.start();

Schnelle Drehung erkannt (6.4 rad/s)

Drehwinkel um die z-Achse aufsummieren

const gyro = new Gyroscope({ frequency: 60 });
let angleZ = 0;
let lastTimestamp = null;

gyro.onreading = () => {
  if (lastTimestamp !== null) {
    const dt = (gyro.timestamp - lastTimestamp) / 1000; // ms -> s
    angleZ += gyro.z * dt;
  }
  lastTimestamp = gyro.timestamp;
  const degrees = (angleZ * 180) / Math.PI;
  document.title = `Drehung: ${degrees.toFixed(1)}°`;
};

gyro.start();

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Browser (Chrome, Edge, Opera, Samsung Internet) ab Version 67, und auch dort nur auf Geräten mit echtem Gyroskop. Firefox und Safari unterstützen die Generic Sensor API nicht. Als Ausweichlösung eignet sich das Event devicemotion mit event.rotationRate (Achtung: dort in Grad pro Sekunde). Unter iOS muss man dafür DeviceMotionEvent.requestPermission() aufrufen.
Sicherer Kontext: Die API gibt es nur über HTTPS (oder localhost). In Iframes muss allow="gyroscope" gesetzt sein, sonst wirft der Konstruktor einen SecurityError.
Fehler kommen auf zwei Wegen: Der Konstruktor kann synchron werfen (SecurityError, ReferenceError). Laufzeitfehler wie NotAllowedError oder NotReadableError kommen dagegen über das error-Event. Beides muss man behandeln.
Drift: Wer Winkelgeschwindigkeiten aufsummiert (integriert), sammelt Fehler an. Für eine stabile Ausrichtung besser RelativeOrientationSensor bzw. AbsoluteOrientationSensor verwenden.
Datenschutz und Akku: Aus Bewegungsdaten lassen sich Fingerabdrücke des Geräts erstellen und sogar Eingaben ableiten. Browser drosseln deshalb die Messrate und liefern keine Werte, solange die Seite im Hintergrund oder nicht im Fokus ist. Den Sensor mit stop() abschalten, sobald er nicht mehr gebraucht wird.
frequency ist nur ein Richtwert. Die tatsächliche Rate misst man über die Differenz der timestamp-Werte.

Siehe auch

Sensor Accelerometer Magnetometer Permissions.prototype.query() BarProp