Battery API

La Battery API en JavaScript : surveiller l'état de la batterie

La Battery API en JavaScript est une interface qui permet aux pages web de lire l'état de la batterie d'un appareil : son niveau de charge, si elle est en cours de charge, et le temps restant avant d'être pleine ou vide. Grâce à ces informations, une application web peut adapter son comportement — par exemple, limiter les tâches en arrière-plan ou atténuer les animations lourdes lorsque l'appareil est en faible puissance. Cet article explique ce qu'est la Battery API, les données qu'elle expose, quand il vaut la peine de l'utiliser, et comment la lire correctement avec des promesses et des événements.

Remarque : Étant donné que le niveau de batterie est un signal d'identification fort (c'est un nombre quasi unique qui évolue lentement), les navigateurs ont progressivement restreint la Battery API. Elle a été retirée de Firefox et de Safari, et navigator.getBattery() n'est disponible que dans les navigateurs basés sur Chromium (Chrome, Edge, Opera) dans un contexte sécurisé (HTTPS). Traitez-la comme une amélioration progressive et effectuez toujours une détection de fonctionnalité avant de l'appeler — votre code doit fonctionner même si l'API est absente.

Qu'est-ce que la Battery API ?

La Battery API est exposée via une seule méthode, navigator.getBattery(), qui retourne une Promise qui se résout en un objet BatteryManager. Cet objet contient quatre propriétés en lecture seule décrivant l'état actuel, plus quatre événements qui se déclenchent chaque fois que l'une de ces valeurs change. Comme getBattery() est asynchrone, vous la lisez avec .then() ou avec async/await.

Propriétés de BatteryManager

Événements de BatteryManager

Chaque événement est un événement DOM standard, vous vous y abonnez donc avec addEventListener sur le BatteryManager.

Avantages de la Battery API

• Amélioration de l'expérience utilisateur : En accédant aux informations sur l'état de la batterie, les applications web peuvent adapter leur comportement pour économiser de l'énergie lorsque l'appareil fonctionne sur batterie, ou proposer des fonctionnalités améliorées lorsque l'appareil est branché et en charge.
• Efficacité énergétique : En exploitant les informations sur l'état de la batterie, les applications web peuvent optimiser les opérations gourmandes en ressources afin de réduire la consommation d'énergie et prolonger la durée de vie de la batterie.
• Mises à jour en temps réel : L'API fournit des mises à jour en temps réel sur les changements d'état de la batterie, permettant aux applications web de réagir immédiatement à des événements tels que le débranchement de l'appareil ou un niveau de batterie faible.
• Support des navigateurs : La Battery API est disponible dans plusieurs navigateurs modernes, bien que les développeurs doivent mettre en œuvre une détection de fonctionnalité pour assurer la compatibilité dans différents environnements.

Quand utiliser la Battery API

Envisagez d'utiliser la Battery API lorsque votre application web doit :

1. Proposer des fonctionnalités adaptées à l'alimentation : Adapter les fonctionnalités et le comportement de votre application selon que l'appareil fonctionne sur batterie, est en charge ou est complètement chargé.
2. Préserver la durée de vie de la batterie : Optimiser les opérations gourmandes en ressources lorsque l'appareil fonctionne sur batterie afin de réduire la consommation d'énergie et prolonger l'autonomie.
3. Afficher l'état de la batterie : Montrer aux utilisateurs des informations liées à la batterie, telles que le niveau de charge actuel ou le temps estimé avant que la batterie soit entièrement chargée.
4. Déclencher des actions lors d'événements de batterie : Exécuter des actions spécifiques lorsque l'état de la batterie change, comme afficher une alerte de batterie faible ou mettre en pause des tâches gourmandes en ressources.

Cas d'utilisation pratiques

1. Alerte batterie faible : Vous pouvez utiliser la Battery API pour déclencher une alerte de batterie faible lorsque le niveau de batterie de l'appareil descend en dessous d'un certain seuil, invitant les utilisateurs à économiser de l'énergie ou à brancher leur appareil.
2. Animations économes en énergie : Les applications web peuvent ajuster l'intensité et la fréquence des animations en fonction de l'état de la batterie pour réduire la consommation de celle-ci.
3. Gestion des processus en arrière-plan : Optimiser les processus en arrière-plan, tels que la synchronisation des données ou l'envoi de notifications, pour qu'ils se produisent moins fréquemment lorsque l'appareil fonctionne sur batterie afin d'économiser de l'énergie.
4. Chargement dynamique des ressources : Charger des images haute résolution ou du contenu gourmand en ressources uniquement lorsque l'appareil est en charge ou lorsque le niveau de batterie dépasse un certain seuil, améliorant ainsi les performances et l'efficacité énergétique.

Détection de fonctionnalité

Ne supposez jamais que getBattery() existe. Protégez chaque appel afin que les navigateurs non compatibles se replient gracieusement au lieu de lever une TypeError :

async function readBattery() {
  if (!('getBattery' in navigator)) {
    return 'Battery API not supported';
  }

  const battery = await navigator.getBattery();
  const percent = Math.round(battery.level * 100);
  return `${percent}% — ${battery.charging ? 'charging' : 'on battery'}`;
}

'getBattery' in navigator est la vérification canonique : elle vaut true uniquement lorsque l'API est présente. La forme async/await lit le BatteryManager résolu exactement comme la forme .then(), mais s'exécute de haut en bas.

Exemple de base : surveiller l'état de la batterie

L'exemple ci-dessous lit la batterie une fois puis maintient le texte affiché à l'écran synchronisé en écoutant les événements pertinents. Notez l'utilitaire toHours — chargingTime et dischargingTime sont exprimés en secondes, donc diviser par 3600 les convertit en heures lisibles. Les deux valeurs peuvent être Infinity, nous traitons donc ce cas explicitement.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Battery Time Estimation</title>
</head>
<body>
    <h1>Battery Time Estimation</h1>
    <div>Time Remaining: <span id="timeRemaining">Calculating...</span></div>

    <script>
    if ('getBattery' in navigator) {
        navigator.getBattery().then(function(battery) {
            const output = document.getElementById('timeRemaining');

            function toHours(seconds) {
                return (seconds / 3600).toFixed(1);
            }

            function updateTimeRemaining() {
                if (battery.charging) {
                    if (battery.chargingTime === Infinity) {
                        output.textContent = 'Plugged in, charge time unknown';
                    } else {
                        output.textContent = `Charging, ${toHours(battery.chargingTime)} hours until full`;
                    }
                } else if (battery.dischargingTime === Infinity) {
                    output.textContent = 'On battery, time remaining unknown';
                } else {
                    output.textContent = `On battery, ${toHours(battery.dischargingTime)} hours remaining`;
                }
            }

            updateTimeRemaining();

            battery.addEventListener('chargingchange', updateTimeRemaining);
            battery.addEventListener('levelchange', updateTimeRemaining);
            battery.addEventListener('chargingtimechange', updateTimeRemaining);
            battery.addEventListener('dischargingtimechange', updateTimeRemaining);
        }).catch(function(error) {
            document.getElementById('timeRemaining').textContent = 'Battery API not available or access denied.';
            console.error('Battery API error:', error);
        });
    } else {
        document.getElementById('timeRemaining').textContent = 'Battery API not supported in this browser.';
    }
    </script>
</body>
</html>

Comment ça fonctionne :

• Estimation du temps : Le script vérifie si la batterie est en charge ou en décharge et affiche un temps estimé avant que la batterie soit entièrement chargée ou épuisée.
• Écouteurs d'événements : Il met à jour l'affichage en temps réel au fur et à mesure que l'état de la batterie change.

Cet exemple illustre comment la Battery API peut fournir des informations détaillées sur l'utilisation de la batterie, y compris des estimations de temps, ce qui peut être particulièrement utile pour les appareils mobiles et les ordinateurs portables dans la gestion de la consommation d'énergie et la planification de l'utilisation.

Réagir à une batterie faible

Un modèle courant consiste à passer la page en mode « économie d'énergie » dès que la charge descend en dessous d'un seuil tout en fonctionnant sur batterie. Écoutez levelchange et chargingchange ensemble afin de réévaluer le mode sur l'un ou l'autre signal :

async function watchPowerSaver(onChange) {
  if (!('getBattery' in navigator)) return;

  const battery = await navigator.getBattery();

  function evaluate() {
    // Save power only when on battery and below 20%.
    const lowPower = !battery.charging && battery.level < 0.2;
    onChange(lowPower);
  }

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

// Usage: pause heavy animations when low on power.
watchPowerSaver((lowPower) => {
  document.body.classList.toggle('reduce-motion', lowPower);
});

C'est bien moins coûteux que d'interroger régulièrement via un minuteur : le rappel ne s'exécute que lorsque l'état de la batterie change réellement.

Pièges courants

• Elle peut ne jamais résoudre vers des données utiles. Sur un ordinateur de bureau sans batterie, charging vaut true, level vaut 1, et les deux propriétés de temps valent 0 ou Infinity. Ne traitez pas l'API comme un indicateur fiable de « sur un ordinateur portable ».
• Infinity est normal. chargingTime est Infinity chaque fois que l'appareil n'est pas en charge, et dischargingTime est Infinity chaque fois que le temps ne peut pas être estimé. Branchez toujours une condition dessus avant de le formater.
• Les estimations sont grossières et arrondies. Pour réduire les risques d'identification, les navigateurs arrondissent level et les valeurs de temps ; ne construisez donc pas de comptes à rebours précis sur cette base.
• Un contexte sécurisé est requis. getBattery() n'est disponible que sur les pages HTTPS (et localhost). Sur du HTTP simple, elle est undefined, ce que votre vérification de fonctionnalité détecte.
• Supprimez les écouteurs dont vous n'avez plus besoin. Si vous attachez des écouteurs dans un composant, détachez-les avec removeEventListener lors du démontage pour éviter les fuites mémoire.

Conclusion

La Battery API en JavaScript offre aux développeurs web un outil pour accéder à l'état de la batterie des appareils utilisateurs et y réagir. En exploitant cette API, les applications web peuvent améliorer l'expérience utilisateur, préserver la durée de vie de la batterie et optimiser l'efficacité énergétique. Bien que le support des navigateurs varie en raison de considérations de confidentialité, la Battery API vous permet de créer des expériences adaptées à l'alimentation là où elle est prise en charge — à condition de détecter la fonctionnalité, de gérer les valeurs de temps Infinity, et de traiter les données comme une indication approximative plutôt que comme une garantie.

Sujets connexes

• Promises — getBattery() en retourne une.
• async / await — la façon la plus claire de la lire.
• Introduction aux événements du navigateur — comment fonctionnent les événements de BatteryManager.
• Geolocation API — une autre API d'état d'appareil avec des modèles similaires de permission et de détection de fonctionnalité.

Practice