new Gyroscope() — Methode · JavaScript-Referenz

Signatur

new Gyroscope(options)

Beschreibung

Der Konstruktor Gyroscope() gehört zur Generic Sensor API. Er erzeugt einen Sensor, der die Drehrate des Geräts um die drei Achsen liefert. Die Werte stehen danach in den Eigenschaften x, y und z und werden in Radiant pro Sekunde angegeben. Typische Einsätze sind Spielsteuerung durch Neigen, 360°-Ansichten, Bildstabilisierung oder die Erkennung von Gesten.

Wenn Sie den Konstruktor aufrufen, wird noch nichts gemessen. Erst mit sensor.start() beginnt die Messung. Neue Messwerte melden sich über das Ereignis reading, Fehler (z. B. fehlende Berechtigung oder fehlende Hardware) über error. Mit stop() beenden Sie die Messung wieder, das spart Akku.

Über options legen Sie fest, wie oft gemessen wird (frequency) und auf welches Koordinatensystem sich die Achsen beziehen (referenceFrame): entweder das Gerät selbst oder den Bildschirm, dessen Ausrichtung sich beim Drehen ändert.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Einstellungsobjekt mit den Feldern `frequency` und `referenceFrame`.
$options.frequency	number	vom Gerät abhängig	Gewünschte Anzahl der Messungen pro Sekunde (Hz). Der Browser kann den Wert auf das unterstützte Maximum begrenzen.
$options.referenceFrame	'device' \| 'screen'	'device'	`'device'`: Achsen beziehen sich auf das physische Gerät. `'screen'`: Achsen beziehen sich auf die aktuelle Bildschirmausrichtung.

Rückgabewert

Typ

Gyroscope

Beschreibung

Ein neues, noch nicht gestartetes Gyroscope-Objekt (erbt von Sensor und EventTarget).

Beispiele

Sensor erzeugen und Drehraten ausgeben

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

  gyro.addEventListener('reading', () => {
    console.log(`x: ${gyro.x.toFixed(3)} y: ${gyro.y.toFixed(3)} 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 nicht unterstützt');
}

x: 0.012 y: -0.004 z: 0.231 rad/s

Erst Berechtigung prüfen, dann sicher starten

const startGyro = async () => {
  const { state } = await navigator.permissions.query({ name: 'gyroscope' });
  if (state === 'denied') {
    console.warn('Zugriff auf das Gyroskop wurde verweigert');
    return null;
  }

  try {
    const gyro = new Gyroscope({ frequency: 60, referenceFrame: 'screen' });
    gyro.onerror = (e) => {
      if (e.error.name === 'NotReadableError') {
        console.warn('Sensor nicht verfügbar');
      }
    };
    gyro.start();
    return gyro;
  } catch (err) {
    // SecurityError (z. B. per Permissions-Policy blockiert) oder ReferenceError
    console.error('Konstruktor fehlgeschlagen:', err.name);
    return null;
  }
};

startGyro();

Drehwinkel integrieren und Sensor wieder stoppen

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

gyro.onreading = () => {
  if (last !== null) {
    const dt = (gyro.timestamp - last) / 1000; // ms -> s
    angleZ += gyro.z * dt;
  }
  last = gyro.timestamp;
};

gyro.start();

// Nach 5 Sekunden stoppen und Ergebnis in Grad ausgeben
setTimeout(() => {
  gyro.stop();
  console.log(`Gedreht um ca. ${(angleZ * 180 / Math.PI).toFixed(1)}°`);
}, 5000);

Gedreht um ca. 87.4°

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-basierte Browser (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen die Generic Sensor API nicht. Prüfen Sie daher vorher mit 'Gyroscope' in window. Als Ausweichlösung eignet sich das Ereignis devicemotion (event.rotationRate, dort in Grad pro Sekunde).
Nur in sicherem Kontext: Die API funktioniert nur über HTTPS (oder auf localhost).
Permissions-Policy: In iframes muss das Feature gyroscope erlaubt sein (allow="gyroscope"). Sonst wirft der Konstruktor einen SecurityError. Fehlt die Hardware, meldet das Ereignis error einen NotReadableError; bei verweigerter Berechtigung kommt ein NotAllowedError.
Einheit: Die Werte sind Radiant pro Sekunde, keine Winkel. Wenn Sie über die Zeit aufsummieren, sammelt sich Drift an. Für eine stabile Ausrichtung nehmen Sie besser AbsoluteOrientationSensor oder RelativeOrientationSensor.
Vor dem ersten Messwert sind x, y und z gleich null.
Akku und Datenschutz: Hohe Messraten verbrauchen viel Energie, und Bewegungsdaten eignen sich zum Wiedererkennen von Nutzern (Fingerprinting). Messen Sie nur so oft wie nötig und rufen Sie stop() auf, zum Beispiel wenn die Seite in den Hintergrund wechselt (visibilitychange).

Siehe auch

Gyroscope Sensor Accelerometer Sensor.prototype.start() new CSSScale()