BatteryManager: dischargingtimechange — Ereignis · JavaScript-Referenz

Signatur

batteryManager.addEventListener("dischargingtimechange", handler)

Beschreibung

Das Ereignis dischargingtimechange gehört zur Battery Status API. Der Browser löst es an einem BatteryManager-Objekt aus, sobald er den Wert von dischargingTime neu berechnet hat. Dieser Wert ist die geschätzte Zeit in Sekunden, bis der Akku leer ist. Den BatteryManager erhältst du über navigator.getBattery(), das ein Promise zurückgibt.

Du kannst das Ereignis auf zwei Arten abonnieren: mit battery.addEventListener("dischargingtimechange", handler) oder über die Eigenschaft battery.ondischargingtimechange = handler. Das Ereignis ist ein einfaches Event ohne zusätzliche Daten. Den neuen Wert liest du im Handler direkt aus battery.dischargingTime oder aus event.target.dischargingTime.

Typische Einsatzfälle sind eine Restlaufzeit-Anzeige in Web-Apps und ein Energiesparmodus: Wird die Restlaufzeit knapp, kannst du zum Beispiel Animationen, Abfragen im Hintergrund oder die Videoqualität reduzieren. Solange das Gerät lädt, ist dischargingTime gleich Infinity. Deshalb kombiniert man das Ereignis meist mit chargingchange.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"dischargingtimechange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Aktualisierung von `dischargingTime` aufgerufen wird. Er erhält ein einfaches `Event`, dessen `target` der `BatteryManager` ist.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal`, z. B. um den Listener mit einem `AbortController` zu entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der neue Wert steht im Handler in battery.dischargingTime: eine Zahl in Sekunden oder Infinity.

Beispiele

Restlaufzeit mit addEventListener anzeigen

const formatTime = (seconds) => {
  if (!Number.isFinite(seconds)) return 'unbekannt / lädt';
  const h = Math.floor(seconds / 3600);
  const m = Math.floor((seconds % 3600) / 60);
  return `${h} h ${m} min`;
};

const init = async () => {
  if (!('getBattery' in navigator)) {
    console.log('Battery Status API wird nicht unterstützt.');
    return;
  }
  const battery = await navigator.getBattery();
  console.log('Start:', formatTime(battery.dischargingTime));

  battery.addEventListener('dischargingtimechange', () => {
    console.log('Restlaufzeit:', formatTime(battery.dischargingTime));
  });
};

init();

Start: unbekannt / lädt Restlaufzeit: 3 h 12 min

Variante mit der on-Property ondischargingtimechange

const battery = await navigator.getBattery();

battery.ondischargingtimechange = (event) => {
  const secs = event.target.dischargingTime;
  console.log(`Noch ca. ${Math.round(secs / 60)} Minuten`);
};

// Handler wieder entfernen:
// battery.ondischargingtimechange = null;

Noch ca. 187 Minuten

Energiesparmodus aktivieren und Listener per removeEventListener entfernen

const LOW_THRESHOLD = 15 * 60; // 15 Minuten in Sekunden

const battery = await navigator.getBattery();

const onDischargingTimeChange = () => {
  const lowPower = battery.dischargingTime < LOW_THRESHOLD;
  document.documentElement.classList.toggle('power-save', lowPower);
  if (lowPower) console.log('Energiesparmodus aktiv');
};

battery.addEventListener('dischargingtimechange', onDischargingTimeChange);

// Aufräumen, z. B. beim Verlassen einer Ansicht in einer SPA
const cleanup = () => {
  battery.removeEventListener('dischargingtimechange', onDischargingTimeChange);
};

setTimeout(cleanup, 60_000);

Energiesparmodus aktiv

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-Browser unterstützen die API, also Chrome, Edge und Opera. Firefox hat sie aus Datenschutzgründen entfernt, Safari hat sie nie unterstützt. Prüfe vor der Nutzung immer mit 'getBattery' in navigator.
Sicherer Kontext: navigator.getBattery() funktioniert nur über HTTPS. Außerdem kann eine Permissions-Policy (battery) den Zugriff z. B. in iframes sperren.
Infinity: Solange das Gerät lädt, der Wert noch nicht berechnet ist oder das System keine Schätzung liefert, ist dischargingTime gleich Infinity. Fange das bei Berechnungen und Anzeigen ab.
Ungenau und in Stufen: Der Wert ist nur eine Schätzung des Betriebssystems und wird in unregelmäßigen Abständen aktualisiert. Auf Desktop-Geräten ohne Akku wird das Ereignis eventuell nie ausgelöst.
Datenschutz: Akkudaten wurden schon für Browser-Fingerprinting missbraucht. Verwende sie nur für Funktionen, die Nutzer direkt betreffen, und nicht zum Tracking.

Siehe auch

BatteryManager: chargingtimechange BatteryManager: chargingchange BatteryManager: levelchange RTCIceTransport: gatheringstatechange PaymentRequest: shippingoptionchange