Navigator.getBattery() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.getBattery()

Beschreibung

navigator.getBattery() ist der Einstiegspunkt der Battery Status API. Die Methode gibt ein Promise zurück, das mit einem BatteryManager erfüllt wird. Dieses Objekt stellt die Eigenschaften level (0.0–1.0), charging, chargingTime und dischargingTime (in Sekunden) bereit. Außerdem löst es Ereignisse wie levelchange oder chargingchange aus, wenn sich der Zustand ändert.

Typische Anwendungsfälle sind energiebewusste Webanwendungen: Bei niedrigem Akkustand kann eine App zum Beispiel Animationen reduzieren, Hintergrund-Synchronisation aussetzen, die Videoqualität senken oder den Nutzer warnen, dass ungespeicherte Arbeit verloren gehen könnte.

Wiederholte Aufrufe liefern in der Regel dasselbe BatteryManager-Objekt. Man ruft die Methode also einmal auf und registriert danach Ereignis-Listener, statt den Zustand ständig neu abzufragen. Die Methode steht nur in sicheren Kontexten (HTTPS) zur Verfügung. Man sollte sie immer mit einer Funktionsprüfung absichern, weil viele Browser sie nicht unterstützen.

Rückgabewert

Typ

Promise<BatteryManager>

Beschreibung

Ein Promise, das mit einem BatteryManager-Objekt erfüllt wird. Es wird mit einer DOMException vom Typ NotAllowedError abgelehnt, wenn eine Permissions-Policy (battery) den Zugriff verbietet, zum Beispiel in einem Cross-Origin-iframe.

Beispiele

Batteriezustand einmalig auslesen

const zeigeBatterie = async () => {
  if (!('getBattery' in navigator)) {
    console.log('Battery Status API wird nicht unterstützt.');
    return;
  }
  const battery = await navigator.getBattery();
  console.log(`Ladestand: ${Math.round(battery.level * 100)} %`);
  console.log(`Lädt gerade: ${battery.charging ? 'ja' : 'nein'}`);
  console.log(`Restlaufzeit: ${battery.dischargingTime} s`);
};

zeigeBatterie();

Ladestand: 76 % Lädt gerade: nein Restlaufzeit: 14280 s

Auf Änderungen reagieren und Energiesparmodus aktivieren

const initEnergiesparen = async () => {
  if (!navigator.getBattery) return;
  const battery = await navigator.getBattery();

  const aktualisieren = () => {
    const sparen = !battery.charging && battery.level < 0.2;
    document.body.classList.toggle('energiesparmodus', sparen);
    console.log(sparen ? 'Energiesparmodus aktiv' : 'Normalbetrieb');
  };

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

initEnergiesparen();

Normalbetrieb

Fehlerbehandlung bei blockierter Permissions-Policy

const ladestandHolen = async () => {
  try {
    const { level } = await navigator.getBattery();
    return level;
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      console.warn('Zugriff durch Permissions-Policy blockiert.');
    } else {
      console.warn('Battery API nicht verfügbar:', err.message);
    }
    return null;
  }
};

ladestandHolen().then((level) => console.log('Level:', level));

Level: 0.76

// Wichtig · Fallstricke

Browser-Kompatibilität: Wird nur von Chromium-basierten Browsern unterstützt (Chrome, Edge, Opera, Samsung Internet). Firefox hat die API ab Version 52 aus Datenschutzgründen für Webinhalte entfernt, und Safari hat sie nie angeboten. Prüfen Sie deshalb immer mit 'getBattery' in navigator, ob die Methode vorhanden ist.
Datenschutz: Ladestand und Restlaufzeiten wurden früher für Browser-Fingerprinting missbraucht. Manche Browser runden die Werte deshalb oder geben feste Werte zurück, zum Beispiel level = 1 und charging = true.
Nur in sicheren Kontexten: Die Methode ist nur über HTTPS (oder localhost) verfügbar. In iframes kann sie über die Permissions-Policy battery gesperrt sein.
Auf Geräten ohne Akku, etwa Desktop-PCs, meldet die API meist charging: true, level: 1 und dischargingTime: Infinity.
chargingTime und dischargingTime können Infinity sein, wenn das System keine Schätzung liefern kann. Prüfen Sie das mit Number.isFinite(), bevor Sie die Werte anzeigen.
Die frühere, synchrone Eigenschaft navigator.battery ist veraltet und entfernt worden.

Siehe auch

Navigator Navigator.getAutoplayPolicy() Navigator.getGamepads() Navigator.vibrate() Navigator.getUserMedia()