BatteryManager.level — Eigenschaft · JavaScript-Referenz

Signatur

BatteryManager.level

Beschreibung

Die Eigenschaft level des BatteryManager-Interfaces gibt den Ladezustand des Geräte-Akkus als Gleitkommazahl zwischen 0.0 und 1.0 an. Ein Wert von 0.42 steht also für 42 %. Den BatteryManager bekommt man nicht direkt, sondern über das Promise von navigator.getBattery().

Typische Einsatzfälle sind energiesparende Web-Anwendungen: Bei niedrigem Akkustand kann man etwa Animationen abschalten, Hintergrund-Synchronisation seltener ausführen, Videoqualität senken oder den Nutzer warnen, bevor ungespeicherte Arbeit verloren geht.

Der Wert ändert sich laufend. Statt ihn regelmäßig abzufragen, sollte man auf das Ereignis levelchange hören (per addEventListener("levelchange", …) oder über die Eigenschaft onlevelchange). Hat das Gerät keine Batterie oder kann der Browser den Zustand nicht ermitteln, meldet level den Wert 1.0, und charging ist dann true.

Rückgabewert

Typ

number

Beschreibung

Gleitkommazahl von 0.0 bis einschließlich 1.0, die den Ladezustand angibt. Geräte ohne Batterie oder mit unbekanntem Zustand liefern 1.0.

Beispiele

Akkustand in Prozent auslesen

const zeigeAkkustand = async () => {
  if (!('getBattery' in navigator)) {
    console.log('Battery Status API wird nicht unterstützt.');
    return;
  }
  const battery = await navigator.getBattery();
  const prozent = Math.round(battery.level * 100);
  console.log(`Akkustand: ${prozent} %`);
};

zeigeAkkustand();

Akkustand: 76 %

Mit levelchange auf Änderungen reagieren

const beobachteAkku = async () => {
  const battery = await navigator.getBattery();
  const anzeige = document.querySelector('#akku');

  const aktualisieren = () => {
    anzeige.textContent = `${Math.round(battery.level * 100)} %`;
  };

  aktualisieren();
  battery.addEventListener('levelchange', aktualisieren);

  // Später wieder abmelden, z. B. beim Verlassen der Ansicht
  return () => battery.removeEventListener('levelchange', aktualisieren);
};

const abmelden = await beobachteAkku();

Energiesparmodus bei niedrigem Akku aktivieren

const SCHWELLE = 0.2; // 20 %

const pruefeEnergiesparmodus = (battery) => {
  const sparen = battery.level <= SCHWELLE && !battery.charging;
  document.body.classList.toggle('energiesparen', sparen);
  console.log(sparen ? 'Energiesparmodus aktiv' : 'Normaler Modus');
};

navigator.getBattery?.().then((battery) => {
  pruefeEnergiesparmodus(battery);
  battery.onlevelchange = () => pruefeEnergiesparmodus(battery);
  battery.onchargingchange = () => pruefeEnergiesparmodus(battery);
});

Energiesparmodus aktiv

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Battery Status API gibt es nur in Chromium-basierten Browsern. Firefox hat sie aus Datenschutzgründen entfernt (ab Version 52 nicht mehr für Webinhalte verfügbar), Safari hat sie nie eingebaut. Deshalb vorher immer mit 'getBattery' in navigator prüfen.
Nur in sicheren Kontexten: navigator.getBattery() steht nur unter HTTPS zur Verfügung und kann per Permissions-Policy (battery) gesperrt sein, zum Beispiel in iframes.
Kein Prozentwert: level ist ein Anteil, keine Prozentzahl. Für die Anzeige mit 100 multiplizieren und runden, weil Gleitkommawerte wie 0.8700000047683716 vorkommen können.
Standardwert 1.0: Desktop-Rechner ohne Akku melden 1.0. Daraus lässt sich nicht sicher ableiten, ob überhaupt eine Batterie vorhanden ist.
Datenschutz: Genaue Akkuwerte wurden früher für Browser-Fingerprinting missbraucht. Manche Browser runden die Werte deshalb. Die Anwendung sollte also nicht auf exakte Werte angewiesen sein.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert bzw. löst im Strict Mode einen TypeError aus.

Siehe auch

AbortController.signal MediaStreamTrack.label BatteryManager.charging BatteryManager.chargingTime BatteryManager.dischargingTime