BatteryManager: chargingchange — Ereignis · JavaScript-Referenz

Signatur

batteryManager.addEventListener("chargingchange", handler)

Beschreibung

Das Ereignis chargingchange gehört zur Battery Status API. Es wird am BatteryManager-Objekt ausgelöst, sobald sich die schreibgeschützte Eigenschaft BatteryManager.charging ändert. Das passiert zum Beispiel, wenn das Netzteil eingesteckt oder abgezogen wird. Das Ereignis ist ein einfaches Event ohne zusätzliche Daten. Den neuen Zustand liest man daher über event.target.charging oder direkt am BatteryManager aus.

Das BatteryManager-Objekt bekommt man nur über das Promise von navigator.getBattery(). Einen Handler kann man auf zwei Arten registrieren: mit addEventListener("chargingchange", handler) oder über die Eigenschaft onchargingchange. Die Eigenschaft kann immer nur einen Handler halten. Mit addEventListener lassen sich mehrere Handler registrieren und gezielt wieder entfernen.

Typische Einsatzfälle: Man schaltet rechenintensive Funktionen ab, wenn das Gerät im Akkubetrieb läuft (etwa Animationen, Hintergrund-Synchronisierung oder Video in hoher Auflösung), und schaltet sie wieder ein, sobald das Gerät am Netz hängt. Außerdem kann man den Ladezustand in der Oberfläche anzeigen. Oft kombiniert man das Ereignis mit levelchange, chargingtimechange und dischargingtimechange.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Name des Ereignisses, hier immer `"chargingchange"`.
$handler Pflicht	(event: Event) => void		Die Rückruffunktion. Sie bekommt ein einfaches `Event`; `event.target` ist der `BatteryManager`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal` (`AbortSignal`), mit denen man den Handler automatisch wieder entfernen kann.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der neue Ladezustand steht in BatteryManager.charging (boolean).

Beispiele

Ladezustand mit addEventListener überwachen

const initBattery = async () => {
  if (!('getBattery' in navigator)) {
    console.log('Battery Status API nicht verfügbar');
    return;
  }
  const battery = await navigator.getBattery();

  const report = () => {
    console.log(battery.charging ? 'Gerät wird geladen' : 'Akkubetrieb');
  };

  report(); // Ausgangszustand anzeigen
  battery.addEventListener('chargingchange', report);
};

initBattery();

Akkubetrieb // nach dem Einstecken des Netzteils: Gerät wird geladen

Energiesparmodus über die Eigenschaft onchargingchange

const battery = await navigator.getBattery();

const applyPowerMode = () => {
  document.body.classList.toggle('power-saving', !battery.charging);
};

battery.onchargingchange = applyPowerMode;
applyPowerMode();

// Handler später wieder entfernen:
// battery.onchargingchange = null;

Handler mit removeEventListener und AbortController entfernen

const battery = await navigator.getBattery();

const onChargingChange = (event) => {
  console.log('charging:', event.target.charging);
};

battery.addEventListener('chargingchange', onChargingChange);

// Variante 1: gezielt entfernen
battery.removeEventListener('chargingchange', onChargingChange);

// Variante 2: über ein AbortSignal entfernen
const controller = new AbortController();
battery.addEventListener('chargingchange', onChargingChange, {
  signal: controller.signal,
});
controller.abort(); // Listener ist entfernt

// Wichtig · Fallstricke

Browser-Unterstützung: Die API gibt es nur in Chromium-basierten Browsern. Firefox hat sie aus Datenschutzgründen wieder entfernt (ab Version 52 für Webinhalte), und Safari hat sie nie unterstützt. Deshalb immer vorher mit 'getBattery' in navigator prüfen und eine Ausweichlösung vorsehen.
Sicherer Kontext: navigator.getBattery() funktioniert nur über HTTPS (oder localhost). In Iframes kann die Permissions Policy battery den Zugriff sperren.
Das Ereignis enthält keine Daten: Es gibt kein event.charging. Den Wert immer über battery.charging bzw. event.target.charging lesen.
Kein Ereignis beim Start: Beim Registrieren wird chargingchange nicht ausgelöst. Den Ausgangszustand muss man selbst einmal auslesen.
Auf Desktop-Rechnern ohne Akku meldet die API in der Regel charging: true und level: 1. Das Ereignis wird dort praktisch nie ausgelöst.
Datenschutz: Akkudaten lassen sich zum Fingerprinting missbrauchen. Deshalb nur verwenden, wenn es einen echten Nutzen gibt.

Siehe auch

BatteryManager: chargingtimechange BatteryManager: dischargingtimechange BatteryManager: levelchange IDBDatabase: versionchange AudioContext: sinkchange