BatteryManager: levelchange — Ereignis · JavaScript-Referenz

Signatur

batteryManager.addEventListener("levelchange", handler)

Beschreibung

Das Ereignis levelchange gehört zum Interface BatteryManager der Battery Status API. Es wird ausgelöst, sobald der Browser einen neuen Wert für level meldet. Dieser Wert ist eine Zahl zwischen 0.0 (leer) und 1.0 (voll). Ein BatteryManager-Objekt erhält man über das Promise von navigator.getBattery().

Einen Handler registriert man entweder mit battery.addEventListener("levelchange", handler) oder über die Eigenschaft battery.onlevelchange = handler. Das Ereignis ist ein einfaches Event ohne eigene Zusatzdaten. Den neuen Wert liest man deshalb direkt aus event.target.level oder aus dem gespeicherten BatteryManager.

Typische Anwendungen sind Energiesparmodi: Bei niedrigem Ladestand kann eine Web-App zum Beispiel Animationen abschalten, Abfragen seltener ausführen (Polling), Videos in geringerer Qualität laden oder Entwürfe früher speichern. Kombiniert man das Ereignis mit chargingchange, lässt sich unterscheiden, ob das Gerät gerade lädt oder sich entlädt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"levelchange"`.
$handler Pflicht	(event: Event) => void		Callback, das bei jeder Änderung des Ladestands aufgerufen wird. `event.target` ist der `BatteryManager`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once`, `signal` (zum Entfernen per `AbortController`) oder `passive`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt.

Beispiele

Ladestand mit addEventListener überwachen

const battery = await navigator.getBattery();

const showLevel = () => {
  console.log(`Akku: ${Math.round(battery.level * 100)} %`);
};

showLevel(); // Startwert anzeigen
battery.addEventListener("levelchange", showLevel);

Akku: 76 % Akku: 75 %

Energiesparmodus bei niedrigem Akku (on-Property)

const battery = await navigator.getBattery();

const updatePowerMode = () => {
  const low = battery.level <= 0.2 && !battery.charging;
  document.body.classList.toggle("power-saving", low);
  console.log(low ? "Energiesparmodus aktiv" : "Normalbetrieb");
};

battery.onlevelchange = updatePowerMode;
battery.onchargingchange = updatePowerMode;
updatePowerMode();

Normalbetrieb

Listener mit removeEventListener und AbortController entfernen

const battery = await navigator.getBattery();

const onLevel = (event) => {
  const level = event.target.level;
  console.log("Neuer Ladestand:", level);
  if (level >= 1) {
    // Akku voll: nicht weiter überwachen
    battery.removeEventListener("levelchange", onLevel);
  }
};
battery.addEventListener("levelchange", onLevel);

// Alternative: alle Listener gemeinsam per Signal entfernen
const controller = new AbortController();
battery.addEventListener("levelchange", () => console.log("Level geändert"), {
  signal: controller.signal
});
// Später, z. B. beim Verlassen der Ansicht:
controller.abort();

Neuer Ladestand: 0.99 Neuer Ladestand: 1

Feature-Erkennung mit Fallback

const initBattery = async () => {
  if (!("getBattery" in navigator)) {
    console.log("Battery Status API nicht verfügbar");
    return;
  }
  const battery = await navigator.getBattery();
  battery.addEventListener("levelchange", () => {
    console.log("Level:", battery.level.toFixed(2));
  });
};

initBattery();

Battery Status API nicht verfügbar

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-Browser (Chrome, Edge, Opera, Samsung Internet) unterstützen die API. Firefox hat sie aus Datenschutzgründen entfernt (ab Version 52 für Webinhalte), Safari hat sie nie unterstützt. Deshalb immer mit "getBattery" in navigator prüfen, ob sie vorhanden ist.
Sicherer Kontext: navigator.getBattery() steht nur über HTTPS (oder auf localhost) zur Verfügung. In Iframes kann der Zugriff über die Permissions Policy battery gesperrt sein.
Datenschutz: Genaue Werte für den Ladestand wurden früher zum Fingerprinting missbraucht. Browser runden level deshalb oft, etwa auf ganze Prozent. Das Ereignis wird daher selten und in unregelmäßigen Abständen ausgelöst, nicht bei jeder winzigen Änderung.
Kein Startereignis: Beim Registrieren wird levelchange nicht sofort ausgelöst. Den Anfangswert muss man selbst einmal auslesen.
Auf Desktop-Rechnern ohne Akku meldet der Browser meist dauerhaft level === 1 und charging === true. Das Ereignis tritt dort praktisch nie auf.
Über onlevelchange lässt sich nur ein Handler setzen, eine neue Zuweisung ersetzt den alten. Für mehrere Handler addEventListener verwenden.

Siehe auch

BatteryManager: chargingchange BatteryManager: chargingtimechange BatteryManager: dischargingtimechange CaptureController: zoomlevelchange RTCDTMFSender: tonechange