AmbientLightSensor — Schnittstelle · JavaScript-Referenz

Beschreibung

AmbientLightSensor gehört zur Generic Sensor API und erbt von Sensor (und damit von EventTarget). Die Schnittstelle liefert über die Eigenschaft illuminance die aktuelle Beleuchtungsstärke in Lux. Den Wert misst der Lichtsensor des Geräts, der meist neben der Frontkamera von Smartphones und Laptops sitzt.

Typische Einsatzfälle sind Oberflächen, die sich an das Umgebungslicht anpassen: ein automatischer Dunkelmodus bei schwachem Licht, mehr Kontrast bei Sonnenlicht oder ein Leseansicht-Modus. Auch in Smart-Home- oder Messanwendungen lassen sich Helligkeitswerte erfassen.

Die Nutzung folgt dem üblichen Sensor-Muster:

Instanz mit new AmbientLightSensor({ frequency }) erzeugen.
Auf die Ereignisse reading, activate und error hören. Dafür eignen sich addEventListener oder die Eigenschaften onreading, onactivate und onerror.
Mit start() die Messung beginnen und mit stop() beenden.

Weitere geerbte Eigenschaften sind activated, hasReading und timestamp. Die API funktioniert nur in einem sicheren Kontext (HTTPS). Außerdem muss sowohl die Berechtigung "ambient-light-sensor" als auch die gleichnamige Permissions-Policy-Direktive das erlauben.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt für den Konstruktor `new AmbientLightSensor(options)`.
$options.frequency	number	gerätespezifisch	Gewünschte Anzahl der Messungen pro Sekunde (Hz). Das ist nur ein Wunschwert: Der Browser kann eine niedrigere Frequenz verwenden.

Rückgabewert

Typ

AmbientLightSensor

Beschreibung

Der Konstruktor gibt ein neues Sensor-Objekt zurück. Die Eigenschaft illuminance (number | null) enthält den zuletzt gemessenen Wert in Lux. Solange noch keine Messung vorliegt, ist sie null.

Beispiele

Sensor starten und Lux-Werte ausgeben

if ('AmbientLightSensor' in window) {
  const sensor = new AmbientLightSensor({ frequency: 1 });

  sensor.addEventListener('reading', () => {
    console.log(`Aktuelle Helligkeit: ${sensor.illuminance} lx`);
  });

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

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

Aktuelle Helligkeit: 250 lx

Automatischer Dunkelmodus nach Umgebungslicht

const DARK_THRESHOLD = 50; // Lux

const initLightTheme = async () => {
  if (!('AmbientLightSensor' in window)) return;

  const { state } = await navigator.permissions.query({ name: 'ambient-light-sensor' });
  if (state === 'denied') {
    console.warn('Zugriff auf den Lichtsensor verweigert.');
    return;
  }

  const sensor = new AmbientLightSensor({ frequency: 0.5 });
  sensor.onreading = () => {
    const dark = sensor.illuminance < DARK_THRESHOLD;
    document.documentElement.classList.toggle('dark', dark);
  };
  sensor.onerror = (e) => console.error(e.error.name);
  sensor.start();
};

initLightTheme();

Sensor nur bei sichtbarer Seite betreiben (Akku sparen)

const sensor = new AmbientLightSensor();
sensor.onreading = () => console.log(sensor.illuminance, sensor.timestamp);
sensor.onactivate = () => console.log('Sensor aktiv:', sensor.activated);

const toggle = () => {
  document.hidden ? sensor.stop() : sensor.start();
};

document.addEventListener('visibilitychange', toggle);
toggle();

Sensor aktiv: true 200 1234.56

// Wichtig · Fallstricke

Kompatibilität: Die Schnittstelle ist experimentell. In Chrome, Edge und anderen Chromium-Browsern steht sie nur zur Verfügung, wenn das Flag #enable-generic-sensor-extra-classes aktiviert ist. Firefox hat seine frühere Umsetzung entfernt, Safari unterstützt die Schnittstelle nicht. Prüfen Sie die Verfügbarkeit daher immer mit 'AmbientLightSensor' in window und sehen Sie einen Fallback vor, etwa die CSS-Media-Query prefers-color-scheme.

Datenschutz und Sicherheit: Lichtwerte lassen sich für Seitenkanal-Angriffe missbrauchen, zum Beispiel um den Browserverlauf oder Bildschirminhalte auszuspähen, und sie eignen sich zum Fingerprinting. Die Spezifikation schreibt deshalb vor, die Werte zu runden, und begrenzt die Messfrequenz. Rechnen Sie also nicht mit feinen Abstufungen.

Fallstricke:

Der Konstruktor kann einen SecurityError auslösen, wenn eine Permissions Policy den Zugriff blockiert. Umschließen Sie ihn deshalb mit try/catch.
Laufzeitfehler kommen über das Ereignis error an, zum Beispiel NotAllowedError (Berechtigung verweigert) oder NotReadableError (Sensor nicht verfügbar).
Die API funktioniert nur über HTTPS. In iframes ist zusätzlich allow="ambient-light-sensor" nötig.
Stoppen Sie den Sensor, wenn Sie ihn nicht brauchen, um Akku zu sparen.

Siehe auch

Sensor Sensor.prototype.start() Sensor.prototype.stop() Permissions.prototype.query() Accelerometer