new AmbientLightSensor() — Methode · JavaScript-Referenz

Signatur

new AmbientLightSensor(options)

Beschreibung

Der Konstruktor AmbientLightSensor() gehört zur Generic Sensor API und erzeugt ein Sensor-Objekt, das die Beleuchtungsstärke rund um das Gerät in Lux (illuminance) liefert. Mit dem Aufruf allein wird noch nichts gemessen: Erst nach sensor.start() fängt der Sensor an, Werte zu liefern. Jede neue Messung löst das Ereignis reading aus.

Typische Einsatzfälle sind ein automatischer Dunkelmodus, eine an die Helligkeit angepasste Schriftgröße oder mehr Kontrast bei starkem Sonnenlicht. Über die Option frequency legst du fest, wie oft pro Sekunde gemessen werden soll. Der tatsächliche Wert hängt aber von der Hardware ab und kann niedriger ausfallen.

Die Berechtigung heißt ambient-light-sensor und lässt sich über die Permissions API abfragen. Die API ist nur in sicheren Kontexten (HTTPS) verfügbar und kann per Permissions-Policy gesperrt sein. Fehler, etwa eine fehlende Berechtigung oder ein fehlender Sensor, meldet das Ereignis error. Außerdem kann schon der Konstruktor eine Ausnahme werfen.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt.
$options.frequency	number	abhängig von der Implementierung	Gewünschte Anzahl Messungen pro Sekunde (Hz). Der Browser kann den Wert begrenzen.

Rückgabewert

Typ

AmbientLightSensor

Beschreibung

Ein neues, noch nicht aktives AmbientLightSensor-Objekt. Messwerte liefert es erst nach start(), und zwar über die Eigenschaft illuminance.

Beispiele

Sensor erzeugen und Lux-Werte auslesen

if ('AmbientLightSensor' in window) {
  try {
    const sensor = new AmbientLightSensor({ frequency: 2 });
    sensor.addEventListener('reading', () => {
      console.log(`Helligkeit: ${sensor.illuminance} lx`);
    });
    sensor.addEventListener('error', (event) => {
      console.error(event.error.name, event.error.message);
    });
    sensor.start();
  } catch (err) {
    // z. B. SecurityError durch Permissions-Policy
    console.error('Sensor nicht nutzbar:', err.name);
  }
} else {
  console.log('AmbientLightSensor wird nicht unterstützt.');
}

Helligkeit: 312 lx Helligkeit: 305 lx

Automatischer Dunkelmodus nach Umgebungslicht

const startAutoTheme = async () => {
  const { state } = await navigator.permissions.query({ name: 'ambient-light-sensor' });
  if (state === 'denied') return console.log('Berechtigung verweigert');

  const sensor = new AmbientLightSensor({ frequency: 1 });
  sensor.onreading = () => {
    const dunkel = sensor.illuminance < 50;
    document.documentElement.classList.toggle('dark', dunkel);
  };
  sensor.onerror = (e) => console.error(e.error.message);
  sensor.start();
  return sensor;
};

startAutoTheme();

Sensor beim Verlassen der Seite stoppen

const sensor = new AmbientLightSensor();
sensor.start();

document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    sensor.stop(); // spart Energie
  } else {
    sensor.start();
  }
});

sensor.onactivate = () => console.log('Sensor aktiv:', sensor.activated);

Sensor aktiv: true

// Wichtig · Fallstricke

Experimentell: Nur Chromium-Browser unterstützen die API, und auch dort nur hinter dem Flag chrome://flags/#enable-generic-sensor-extension-classes. Firefox hat die Unterstützung wieder entfernt, Safari hat sie nie angeboten. Prüfe deshalb immer vorher mit 'AmbientLightSensor' in window.
Nur in sicheren Kontexten (HTTPS) verfügbar. Der Konstruktor wirft einen SecurityError, wenn die Permissions-Policy ambient-light-sensor die Nutzung verbietet, etwa in einem iframe ohne allow-Attribut.
Datenschutz: Lichtwerte können als Seitenkanal dienen, z. B. zum Auslesen des Bildschirminhalts oder für Fingerprinting. Browser runden die Werte deshalb und senken die Messfrequenz.
Ein fehlender Sensor fällt oft erst nach start() auf: Dann feuert das Ereignis error mit einem NotReadableError oder NotAllowedError. Behandle also sowohl Ausnahmen im Konstruktor als auch das Ereignis error.
Rufe stop() auf, sobald du keine Werte mehr brauchst. Das schont den Akku.

Siehe auch

Sensor Sensor.prototype.start() Permissions.prototype.query() new AbsoluteOrientationSensor() new GravitySensor()