new GravitySensor() — Methode · JavaScript-Referenz

Signatur

new GravitySensor(options)

Beschreibung

Der Konstruktor GravitySensor() gehört zur Generic Sensor API und erstellt einen Sensor, der ausschließlich den Schwerkraftanteil der Beschleunigung liefert. Anders als der Accelerometer, der Schwerkraft und Bewegung zusammen misst, oder der LinearAccelerationSensor, der die Schwerkraft herausrechnet, gibt der GravitySensor nur den Vektor der Erdanziehung zurück. Die Werte stehen in den Eigenschaften x, y und z (in m/s²) bereit.

Typische Einsatzfälle sind das Bestimmen der Geräteneigung (z. B. für Wasserwaagen-Apps), das Erkennen der Ausrichtung (Hoch- oder Querformat, Display nach oben oder unten) und neigungsgesteuerte Spiele. Da die Werte meist durch Sensorfusion aus Beschleunigungsmesser und Gyroskop entstehen, sind sie ruhiger als rohe Beschleunigungswerte.

Mit dem Konstruktor wird der Sensor nur angelegt; die Messung beginnt erst mit start(). Neue Werte kommen über das Event reading, Fehler (fehlende Berechtigung, nicht vorhandene Hardware) über das Event error. Mit stop() beendet man die Messung wieder, um Akku zu sparen.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Konfigurationsobjekt mit folgenden Eigenschaften.
$options.frequency	number	gerätespezifisch	Gewünschte Anzahl Messungen pro Sekunde (Hz). Der Browser kann den Wert nach unten begrenzen.
$options.referenceFrame	"device" \| "screen"	"device"	Koordinatensystem der Messwerte: `"device"` bezieht sich auf das Gerät, `"screen"` auf die aktuelle Bildschirmausrichtung (berücksichtigt Drehung ins Querformat).

Rückgabewert

Typ

GravitySensor

Beschreibung

Ein neues, noch nicht gestartetes GravitySensor-Objekt. activated ist false, bis start() aufgerufen wurde und die erste Messung vorliegt.

Beispiele

Sensor anlegen und Schwerkraftwerte ausgeben

if ('GravitySensor' in window) {
  const sensor = new GravitySensor({ frequency: 10 });

  sensor.addEventListener('reading', () => {
    console.log(`x: ${sensor.x.toFixed(2)}, y: ${sensor.y.toFixed(2)}, z: ${sensor.z.toFixed(2)}`);
  });

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

  sensor.start();
} else {
  console.warn('GravitySensor wird nicht unterstützt.');
}

x: 0.02, y: 0.10, z: 9.81 // Gerät liegt flach auf dem Tisch

Berechtigungen prüfen und Fehler sauber abfangen

const startGravitySensor = async () => {
  const results = await Promise.all([
    navigator.permissions.query({ name: 'accelerometer' }),
    navigator.permissions.query({ name: 'gyroscope' })
  ]);

  if (results.some((r) => r.state === 'denied')) {
    console.warn('Sensorzugriff wurde verweigert.');
    return null;
  }

  try {
    const sensor = new GravitySensor({ frequency: 30, referenceFrame: 'screen' });
    sensor.onerror = (event) => {
      if (event.error.name === 'NotReadableError') {
        console.warn('Sensor ist nicht verfügbar.');
      }
    };
    sensor.start();
    return sensor;
  } catch (err) {
    // SecurityError (Permissions-Policy) oder ReferenceError
    console.error('Sensor konnte nicht erstellt werden:', err.name);
    return null;
  }
};

startGravitySensor();

Wasserwaage: Neigungswinkel aus dem Schwerkraftvektor

const sensor = new GravitySensor({ frequency: 20 });
const toDeg = (rad) => (rad * 180) / Math.PI;

sensor.onreading = () => {
  const { x, y, z } = sensor;
  const pitch = toDeg(Math.atan2(y, Math.hypot(x, z)));
  const roll = toDeg(Math.atan2(-x, z));
  console.log(`Nicken: ${pitch.toFixed(1)}°, Rollen: ${roll.toFixed(1)}°`);
};

sensor.start();

// Nach 10 Sekunden stoppen, um Akku zu sparen
setTimeout(() => sensor.stop(), 10_000);

Nicken: 0.6°, Rollen: -0.1°

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur in Chromium-basierten Browsern (ab Version 91) verfügbar, hauptsächlich auf Mobilgeräten. Firefox und Safari unterstützen die Generic Sensor API nicht – immer mit 'GravitySensor' in window prüfen und ggf. auf devicemotion ausweichen.
Sicherer Kontext: Funktioniert nur über HTTPS (oder localhost).
Berechtigungen: Benötigt die Berechtigungen accelerometer und gyroscope. In iframes müssen diese per Permissions-Policy (allow="accelerometer; gyroscope") freigegeben sein, sonst wirft der Konstruktor einen SecurityError.
Fehlt die Hardware, wirft der Konstruktor meist nicht; stattdessen feuert nach start() ein error-Event mit NotReadableError. Daher immer sowohl try/catch als auch einen error-Handler vorsehen.
Vor der ersten Messung sind x, y und z null.
Messungen werden pausiert, wenn die Seite nicht sichtbar ist. Hohe Frequenzen erhöhen den Akkuverbrauch; nicht benötigte Sensoren mit stop() beenden.
Datenschutz: Bewegungssensoren können für Fingerprinting missbraucht werden; Browser reduzieren deshalb ggf. Genauigkeit und Frequenz.

Siehe auch

Accelerometer Gyroscope Sensor.prototype.start() new RTCError() new Sanitizer()