Sensor — Schnittstelle · JavaScript-Referenz

Signatur

interface Sensor extends EventTarget

Beschreibung

Sensor ist die gemeinsame Grundlage aller Schnittstellen der Generic Sensor API. Man erzeugt sie nie direkt, denn new Sensor() wirft einen TypeError. Stattdessen instanziiert man abgeleitete Klassen wie Accelerometer, LinearAccelerationSensor, GravitySensor, Gyroscope, Magnetometer, AbsoluteOrientationSensor, RelativeOrientationSensor oder AmbientLightSensor. Sie alle erben dasselbe Verhalten von Sensor.

Die Schnittstelle stellt die folgenden Mitglieder bereit:

Eigenschaften: activated (boolean: Liefert der Sensor schon Messwerte?), hasReading (boolean: Gibt es bereits einen Messwert?) und timestamp (DOMHighResTimeStamp des letzten Messwerts, sonst null).
Methoden: start() aktiviert den Sensor, stop() deaktiviert ihn.
Ereignisse: activate, reading (neuer Messwert) und error (SensorErrorEvent). Man hört sie über addEventListener() oder über die Eigenschaften onactivate, onreading und onerror ab.

Die Konstruktoren der abgeleiteten Klassen nehmen ein Optionsobjekt entgegen. Darin legt man meist frequency fest, also die gewünschte Abtastrate in Hz, und bei räumlichen Sensoren zusätzlich referenceFrame ("device" oder "screen"). Nutzen lässt sich die API für Bewegungssteuerung in Spielen, Schrittzähler, AR/VR-Anwendungen, Kompass-Funktionen oder die automatische Anpassung an das Umgebungslicht.

Der Zugriff hängt von der Permissions API und der Permissions Policy ab (z. B. accelerometer, gyroscope, magnetometer, ambient-light-sensor). Man sollte die Berechtigung vor dem Start prüfen und Fehler immer über das error-Ereignis behandeln.

Parameter

Name	Typ	Default	Beschreibung
$options.frequency	number	gerätespezifisch	Gewünschte Abtastrate in Hz, wird an den Konstruktor der abgeleiteten Klasse übergeben. Der Browser kann sie nach unten begrenzen.
$options.referenceFrame	"device" \| "screen"	"device"	Bezugssystem für räumliche Sensoren (z. B. `Accelerometer`, `Gyroscope`). Mit `"screen"` werden die Achsen an die Bildschirmausrichtung angepasst.

Rückgabewert

Typ

Sensor

Beschreibung

Die Schnittstelle selbst lässt sich nicht instanziieren. Die Konstruktoren abgeleiteter Klassen liefern eine Instanz, die von Sensor erbt und anfangs inaktiv ist, bis start() aufgerufen wird.

Beispiele

Beschleunigungssensor instanziieren und auslesen

if ('Accelerometer' in window) {
  const acc = new Accelerometer({ frequency: 30 });

  acc.addEventListener('activate', () => {
    console.log('Aktiv:', acc.activated); // geerbt von Sensor
  });

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

  acc.addEventListener('error', (event) => {
    console.error(event.error.name, event.error.message);
  });

  acc.start();
} else {
  console.warn('Generic Sensor API wird nicht unterstützt.');
}

Aktiv: true x=0.12 y=0.03 z=9.81 @ 1834.5

Berechtigung prüfen und Fehler robust behandeln

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

  try {
    const gyro = new Gyroscope({ frequency: 60, referenceFrame: 'screen' });
    gyro.onerror = (event) => {
      if (event.error.name === 'NotAllowedError') {
        console.warn('Zugriff durch Berechtigung blockiert.');
      } else if (event.error.name === 'NotReadableError') {
        console.warn('Sensor nicht verfügbar.');
      }
    };
    gyro.onreading = () => console.log('Drehrate z:', gyro.z);
    gyro.start();
    return gyro;
  } catch (err) {
    // SecurityError (Permissions Policy) oder ReferenceError (nicht unterstützt)
    console.error('Sensor konnte nicht erzeugt werden:', err.name);
    return null;
  }
};

startGyroscope();

Drehrate z: 0.0021

Sensor bei verstecktem Tab stoppen (Akku sparen)

const light = new AmbientLightSensor();
light.onreading = () => {
  document.body.classList.toggle('dark', light.illuminance < 50);
};
light.start();

document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    light.stop();
    console.log('Gestoppt, activated =', light.activated);
  } else {
    light.start();
  }
});

Gestoppt, activated = false

Direkte Instanziierung schlägt fehl

try {
  new Sensor();
} catch (err) {
  console.log(err instanceof TypeError, err.message);
}

true Illegal constructor

// Wichtig · Fallstricke

Browserunterstützung: Die API gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht. Vorher per Feature-Erkennung prüfen ('Accelerometer' in window). Auf iOS bleibt als Alternative DeviceMotionEvent bzw. DeviceOrientationEvent.
Sicherer Kontext: Die API steht nur über HTTPS (oder localhost) zur Verfügung. In Iframes muss die Permissions Policy den Zugriff erlauben, z. B. allow="accelerometer; gyroscope". Sonst wirft der Konstruktor einen SecurityError.
Fehlerbehandlung: Viele Fehler, etwa NotAllowedError, NotReadableError oder NotSupportedError, treten nicht als Ausnahme auf. Sie kommen asynchron über das error-Ereignis. Einen onerror-Handler also immer registrieren.
Datenschutz: Sensordaten eignen sich für Fingerprinting und Seitenkanalangriffe, etwa um Tastatureingaben aus Bewegungsdaten abzuleiten. Browser begrenzen deshalb die Frequenz und runden die Werte. AmbientLightSensor ist oft nur hinter einem Flag verfügbar.
Performance: Hohe Frequenzen kosten Akku. Sensoren bei visibilitychange stoppen und nicht mehr benötigte Instanzen mit stop() beenden. In Hintergrund-Tabs liefert der Browser keine Messwerte.
Vor dem ersten reading-Ereignis sind hasReading gleich false, timestamp gleich null und die Messwert-Eigenschaften ebenfalls null.

Siehe auch

Accelerometer Gyroscope Magnetometer Sensor.prototype.start() Permissions.prototype.query()