Signatur
Beschreibung
Die Eigenschaft illuminance eines AmbientLightSensor-Objekts enthält den zuletzt gemessenen Wert des Umgebungslichtsensors in Lux. Mit dem Wert können Webanwendungen auf die Lichtverhältnisse reagieren, etwa automatisch in einen dunklen Modus wechseln, den Kontrast anpassen oder in E-Book-Readern die Hintergrundfarbe ändern.
Einen Wert gibt es erst, nachdem der Sensor mit start() gestartet wurde und das erste reading-Ereignis ausgelöst hat. Vorher und nach einem Fehler ist die Eigenschaft null. Am besten liest man den Wert im reading-Handler aus. Mit der Option frequency im Konstruktor legt man fest, wie oft Messwerte eintreffen.
Zur Einordnung ungefähre Werte: unter 50 lx ist es ein dunkler Raum, 100–500 lx entsprechen Büro- und Wohnraumlicht, 1.000–10.000 lx Tageslicht im Schatten, und direktes Sonnenlicht reicht bis über 100.000 lx.
Rückgabewert
null, solange noch kein Messwert vorliegt (vor dem ersten reading-Ereignis oder nach einem Fehler).Beispiele
Lichtstärke fortlaufend auslesen
if ('AmbientLightSensor' in window) {
const sensor = new AmbientLightSensor({ frequency: 2 });
sensor.addEventListener('reading', () => {
console.log(`Aktuelle Lichtstärke: ${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.');
}Automatischer Dunkelmodus mit Hysterese
const DUNKEL = 30; // unter 30 lx: dunkles Design einschalten
const HELL = 80; // über 80 lx: helles Design einschalten
const startLichtsteuerung = async () => {
const { state } = await navigator.permissions.query({ name: 'ambient-light-sensor' });
if (state === 'denied') {
console.log('Zugriff auf den Lichtsensor verweigert.');
return;
}
const sensor = new AmbientLightSensor({ frequency: 1 });
sensor.onreading = () => {
const lux = sensor.illuminance;
if (lux < DUNKEL) document.body.classList.add('dark');
else if (lux > HELL) document.body.classList.remove('dark');
};
sensor.onerror = (e) => console.error(e.error.name);
sensor.start();
};
startLichtsteuerung();Wert vor dem ersten Messwert ist null
const sensor = new AmbientLightSensor();
console.log(sensor.illuminance); // noch nicht gestartet
sensor.start();
sensor.onreading = () => {
console.log(Math.round(sensor.illuminance));
sensor.stop(); // nur einen einzigen Messwert holen
};// Wichtig · Fallstricke
- Kompatibilität: Die API ist experimentell. Sie läuft nur in Chromium-basierten Browsern, und dort erst nach Aktivieren des Flags
chrome://flags/#enable-generic-sensor-extra-classes. Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer mit'AmbientLightSensor' in window, ob sie verfügbar ist, und plane einen Ausweichweg ein, zum Beispiel die Media Queryprefers-color-scheme. - Sicherer Kontext und Berechtigung: Die API funktioniert nur über HTTPS. Sie braucht die Berechtigung
ambient-light-sensorund kann über die Permissions Policy gesperrt sein. In diesem Fall wirft der Konstruktor einenSecurityError, oder es wird einerror-Ereignis mitNotAllowedErrorausgelöst. - Datenschutz: Lichtsensoren wurden schon für Seitenkanalangriffe missbraucht, etwa um Bildschirminhalte oder den Browserverlauf auszuspähen. Browser runden die Werte deshalb (in Chrome auf Vielfache von 50 lx) und begrenzen die Messfrequenz. Rechne nicht mit fein aufgelösten Werten.
- Genauigkeit: Wie genau die Werte sind, hängt stark von der Hardware und der Einbauposition des Sensors ab. Verwende Schwellwerte mit Hysterese, damit die Oberfläche nicht ständig zwischen zwei Zuständen hin- und herspringt.
- Rufe
stop()auf, sobald du keine Messwerte mehr brauchst. Das spart Akku.