GravitySensor — Schnittstelle · JavaScript-Referenz

Signatur

interface GravitySensor extends Accelerometer

Beschreibung

GravitySensor gehört zur Generic Sensor API und erbt von Accelerometer (und damit von Sensor und EventTarget). Anders als der normale Accelerometer, der die gesamte Beschleunigung misst, und der LinearAccelerationSensor, der die Schwerkraft herausrechnet, liefert GravitySensor nur den Schwerkraftanteil. Die Werte stehen in den geerbten Eigenschaften x, y und z und werden in Metern pro Sekunde zum Quadrat (m/s²) angegeben.

Typische Anwendungen sind die Neigungs- und Lageerkennung: Liegt ein Gerät flach auf dem Tisch, zeigt z etwa 9,81 m/s² und x und y liegen nahe 0. Daraus lassen sich Wasserwaagen, neigungsgesteuerte Spiele oder die Hochkant-/Querformat-Erkennung umsetzen, ohne Bewegungsanteile selbst herausfiltern zu müssen. Meist handelt es sich um einen Fusionssensor, den der Browser bzw. das Betriebssystem aus Beschleunigungs- und Gyroskopdaten berechnet.

Der Ablauf ist immer gleich: Instanz mit new GravitySensor(options) erzeugen, Handler für die Ereignisse reading, activate und error registrieren, dann start() aufrufen. Mit stop() wird der Sensor wieder abgeschaltet. Das ist wichtig, damit der Akku geschont wird.

Die API steht nur in einem sicheren Kontext (HTTPS) zur Verfügung. Sie ist über die Permissions Policy accelerometer abgesichert und benötigt die Berechtigung "accelerometer".

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt für den Konstruktor `new GravitySensor(options)`.
$options.frequency	number	gerätespezifisch	Gewünschte Anzahl der Messungen pro Sekunde (Hz). Das ist nur eine Anforderung: Die tatsächliche Rate kann niedriger sein.
$options.referenceFrame	"device" \| "screen"	"device"	Bezugssystem der Achsen: `"device"` bezieht sich auf das physische Gerät, `"screen"` auf die aktuelle Bildschirmausrichtung. Bei `"screen"` werden die Achsen beim Drehen des Bildschirms mitgedreht.

Rückgabewert

Typ

GravitySensor

Beschreibung

Eine neue, noch inaktive Sensor-Instanz. Die Messwerte stehen erst nach start() und dem ersten reading-Ereignis in x, y und z (jeweils number | null, in m/s²).

Beispiele

Sensor erzeugen und Schwerkraftwerte auslesen

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

  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.05 z: 9.80 (Gerät liegt flach)

Wasserwaage: Neigungswinkel berechnen

const sensor = new GravitySensor({ frequency: 60, referenceFrame: 'screen' });
const toDeg = (rad) => rad * 180 / Math.PI;

sensor.onreading = () => {
  const { x, y, z } = sensor;
  // Neigung nach vorn/hinten und seitlich
  const pitch = toDeg(Math.atan2(y, Math.hypot(x, z)));
  const roll = toDeg(Math.atan2(-x, z));
  document.querySelector('#level').textContent =
    `Pitch: ${pitch.toFixed(1)}°, Roll: ${roll.toFixed(1)}°`;
};

sensor.start();

// Beim Verlassen der Seite Sensor stoppen, um den Akku zu schonen
document.addEventListener('visibilitychange', () => {
  document.hidden ? sensor.stop() : sensor.start();
});

Pitch: 12.3°, Roll: -4.7°

Berechtigung prüfen und Fehler behandeln

const startGravity = async () => {
  const { state } = await navigator.permissions.query({ name: 'accelerometer' });
  if (state === 'denied') {
    console.warn('Zugriff auf Bewegungssensoren verweigert.');
    return null;
  }

  try {
    const sensor = new GravitySensor({ frequency: 10 });
    sensor.onactivate = () => console.log('Sensor aktiv');
    sensor.onerror = ({ error }) => {
      if (error.name === 'NotAllowedError') console.warn('Berechtigung fehlt.');
      else if (error.name === 'NotReadableError') console.warn('Sensor nicht verfügbar.');
    };
    sensor.start();
    return sensor;
  } catch (err) {
    // SecurityError z. B. durch Permissions Policy, ReferenceError ohne Unterstützung
    console.error('Sensor konnte nicht erzeugt werden:', err.name);
    return null;
  }
};

startGravity();

Sensor aktiv

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Chromium-Browser ab Version 91 unterstützen die Schnittstelle, und auch das nur auf Geräten mit passender Hardware (meist Android). Firefox und Safari unterstützen die Generic Sensor API nicht. Prüfe die Unterstützung vorher mit 'GravitySensor' in window und plane einen Fallback über das devicemotion-Ereignis (accelerationIncludingGravity) ein.
Sicherer Kontext: Die API funktioniert nur über HTTPS. In iframes muss sie per allow="accelerometer" freigegeben werden, sonst wirft der Konstruktor einen SecurityError.
Werte am Anfang null: Bis zum ersten reading-Ereignis sind x, y und z null. Lies die Werte deshalb nicht direkt nach start() aus.
Fehler kommen asynchron: Fehlende Hardware (NotReadableError) oder eine verweigerte Berechtigung (NotAllowedError) werden über das error-Ereignis gemeldet, nicht als Ausnahme. Registriere deshalb immer einen error-Handler.
Datenschutz und Akku: Bewegungsdaten eignen sich für Fingerprinting und Seitenkanalangriffe. Browser können deshalb die Frequenz drosseln und Messungen in Hintergrund-Tabs aussetzen. Wähle eine möglichst niedrige frequency und rufe stop() auf, sobald du den Sensor nicht mehr brauchst.
Vorzeichen: Die Werte beschreiben die Reaktionskraft auf die Schwerkraft. Liegt das Gerät flach mit dem Display nach oben, ist z deshalb positiv (≈ +9,81).

Siehe auch

Accelerometer Sensor Gyroscope RTCRtpSender Navigator