SensorErrorEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface SensorErrorEvent extends Event

Beschreibung

SensorErrorEvent gehört zur Generic Sensor API. Ein Objekt dieses Typs wird an den Handler des error-Ereignisses eines Sensor übergeben, zum Beispiel bei Accelerometer, Gyroscope, Magnetometer, AbsoluteOrientationSensor, RelativeOrientationSensor oder AmbientLightSensor. Das Ereignis wird ausgelöst, wenn ein Sensor nicht gestartet werden kann oder im laufenden Betrieb ausfällt.

Die wichtigste Eigenschaft ist error (nur lesbar). Sie enthält eine DOMException, deren name die Ursache angibt:

NotAllowedError: Der Zugriff wurde verweigert, etwa über die Permissions API oder eine Permissions Policy.
NotReadableError: Der Sensor ist vorhanden, liefert aber keine Werte, zum Beispiel wegen eines Hardwarefehlers.
NotSupportedError: Das Gerät hat keinen passenden Sensor, oder der User Agent unterstützt diesen Sensortyp nicht.
SecurityError: Der Sensor wurde in einem unsicheren Kontext oder in einem nicht erlaubten Frame verwendet.

Die Fehlerbehandlung besteht meist aus zwei Stufen. Fehler, die schon beim Erzeugen des Objekts auftreten (fehlende Policy, unsicherer Kontext), wirft der Konstruktor synchron. Fehler, die erst beim Starten oder später auftreten, kommen asynchron über das error-Ereignis mit einem SensorErrorEvent. Man braucht also sowohl try…catch als auch einen Listener. Den Konstruktor new SensorErrorEvent(type, options) braucht man selten, meist nur in Tests.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Konstruktor-Parameter: Name des Ereignisses, für Sensoren immer `"error"`.
$options Pflicht	{ error: DOMException, bubbles?: boolean, cancelable?: boolean, composed?: boolean }		Konstruktor-Parameter: Objekt mit der Pflicht-Eigenschaft `error` (eine `DOMException`) und den üblichen `EventInit`-Feldern.

Rückgabewert

Typ

SensorErrorEvent

Beschreibung

Das Event-Objekt. Die Eigenschaft error (DOMException, nur lesbar) enthält die Fehlerursache.

Beispiele

Beschleunigungssensor mit vollständiger Fehlerbehandlung

let sensor = null;

try {
  sensor = new Accelerometer({ frequency: 30 });

  sensor.addEventListener('error', (event) => {
    // event ist ein SensorErrorEvent
    const { name, message } = event.error;
    if (name === 'NotAllowedError') {
      console.warn('Zugriff auf den Sensor verweigert.');
    } else if (name === 'NotReadableError') {
      console.warn('Sensor ist nicht verfügbar.');
    } else {
      console.error(`Sensorfehler: ${name} – ${message}`);
    }
  });

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

  sensor.start();
} catch (err) {
  // Synchrone Fehler aus dem Konstruktor
  if (err.name === 'SecurityError') {
    console.error('Sensor durch Permissions Policy blockiert.');
  } else if (err.name === 'ReferenceError') {
    console.error('Accelerometer wird von diesem Browser nicht unterstützt.');
  } else {
    throw err;
  }
}

Zugriff auf den Sensor verweigert. // z. B. nach abgelehnter Berechtigung

Berechtigung vorher prüfen und onerror verwenden

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

  const gyro = new Gyroscope({ frequency: 10 });
  gyro.onerror = (event) => {
    console.log(event instanceof SensorErrorEvent, event.error.name);
    gyro.stop();
  };
  gyro.onreading = () => console.log('Drehrate z:', gyro.z);
  gyro.start();
};

startGyroscope();

true "NotReadableError" // wenn kein Gyroskop vorhanden ist

SensorErrorEvent manuell erzeugen (z. B. im Test)

const fakeError = new DOMException('Sensor getrennt', 'NotReadableError');
const event = new SensorErrorEvent('error', { error: fakeError });

console.log(event.type);        // "error"
console.log(event.error.name);  // "NotReadableError"
console.log(event.error.message);

error NotReadableError Sensor getrennt

// Wichtig · Fallstricke

Browser-Unterstützung: Die Generic Sensor API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, Samsung Internet). Firefox und Safari unterstützen sie nicht. Vorher mit 'Accelerometer' in window oder typeof SensorErrorEvent !== 'undefined' prüfen.
Nur in sicheren Kontexten (HTTPS oder localhost). In iframes muss die Permissions Policy den Zugriff erlauben, zum Beispiel allow="accelerometer; gyroscope". Sonst wirft der Konstruktor einen SecurityError.
Nicht jeder Fehler kommt als SensorErrorEvent. Synchrone Fehler aus dem Konstruktor müssen mit try…catch abgefangen werden. Beides einplanen.
Nach einem Fehler ist der Sensor nicht mehr aktiv (sensor.activated === false). Ein erneuter Versuch braucht einen neuen Aufruf von start(), eventuell erst nach einer Nutzeraktion.
Datenschutz: Mit Sensordaten lassen sich Nutzer wiedererkennen (Fingerprinting) oder Eingaben ausspähen. Browser können deshalb die Frequenz begrenzen oder Werte verweigern, wenn der Tab im Hintergrund ist. Fehlermeldungen daher nicht ungefiltert an den Nutzer oder an Server weitergeben.

Siehe auch

Sensor Accelerometer Gyroscope Permissions.prototype.query() Event