Introduction à l'API javascript Battery Status

Un article de TiranusKBX

Le 2015-11-28 18:48:09, par TiranusKBX, Expert confirmé

Présentation
L'API "Battery Status", sert à fournir des informations sur le niveau de charge d'un système et permet d'envoyer des événements pour prévenir d'un changement du niveau de charge de la batterie ou du changement du mode de charge(charge/décharge). Cela peut être utilisé pour ajuster la consommation d'énergie ou encore déclencher une sauvegarde de données quand la batterie est bientôt vide.

Vu que l'API n'est pas fixée de manière définitive, elle n'est actuellement supportée que par Chrome/Chromium et Firefox.
N’hésitez donc pas à consulter les sources pour la liste de compatibilité.

Mise en pratique
L'interface navigator.battery étant dépréciée nous verrons donc comment utiliser l'accès aux informations de batterie à travers navigator.getBattery().
La méthode navigator.getBattery() retourne un promise pouvant servir à obtenir des informations de manière asynchrone.

Code Javascript :

1
2
navigator.getBattery().then(function(battery) {/* votre code ici */ 
});

Ce promise retourne un objet BatteryManager.

L'objet BatteryManager a plusieurs propriétés directement disponibles en lecture seule , en voici une liste :

charging	indique si le chargeur secteur est branché avec un booléen
chargingTime	temps estimé de rechrge de la batterie en secondes(si batterie plaine= 0, 'Infinity' si débranché)
dischargingTime	temps de décharge estimé en secondes, si branché retourne 'Infinity'
level	le niveau batterie dans un nombre entre 0 et 1, pour avoir en pourcentage multipliez le par 100

Abordons maintenant la gestion des événements. Comme souvent, pour les objets Javascript acceptants des événements, les méthodes .addEventListener() et .removeEventListener() sont disponibles mais aussi la méthode .dispatchEvent(). Cependant, il existe d'autres événements :

chargingchange	se déclenche lorsque le chargeur secteur est branché ou débranché
chargingtimechange	se déclenche lorsque le temps de chargement change
dischargingtimechange	se déclenche lorsque le temps de déchargement change
levelchange	se déclenche lorsque le niveau de batterie change

Vous pouvez donc par exemple les utiliser de la manière suivante :

Code Javascript :

1
2
3
4
5
6
7
navigator.getBattery().then( 
    function(battery) { 
        battery.onlevelchange=function(e){ 
            console.log(navigator.battery.level) 
        ;} 
    ;} 
);

ou de manière plus propre :

Code Javascript :

1
2
3
4
5
6
7
navigator.getBattery().then( 
    function(battery) { 
        battery.addEventListener('levelchange',function(e){ 
            console.log(navigator.battery.level) 
        ;}, false) 
    ;} 
);

Sur Firefox, les paliers pour le niveau de batterie est de 10%. De ce fait, la propriété level vous retournera 0.1, 0.2, 0.3, 0.4 ... 1.0 mais à +5%(ex: 85% donne 0.9 et 84% donne 0.8)

Voici donc un exemple plus complète pour vous mettre l'eau à la bouche :

Code Javascript :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
navigator.getBattery().then(function(battery) { 
    console.log("Battery charging ? " + (battery.charging ? "Yes" : "No")); 
    console.log("Battery level: " + battery.level * 100 + "%"); 
    console.log("Battery charging time: " + battery.chargingTime + " seconds"); 
    console.log("Battery discharging time: " + battery.dischargingTime + " seconds"); 
  
    battery.addEventListener('chargingchange', function() { 
        console.log("Battery charging? " + (battery.charging ? "Yes" : "No")); 
    }); 
  
    battery.addEventListener('levelchange', function() { 
        console.log("Battery level: " + battery.level * 100 + "%"); 
    }); 
  
    battery.addEventListener('chargingtimechange', function() { 
        console.log("Battery charging time: " + battery.chargingTime + " seconds"); 
    }); 
  
    battery.addEventListener('dischargingtimechange', function() { 
        console.log("Battery discharging time: " + battery.dischargingTime + " seconds"); 
    }); 
  
});

Conclusion
Dans cette rapide introduction, je vous ai montré qu'il est simple d'utiliser l'API javascript Battery Status. Pour le moment le support est surtout sur Firefox et Chrome y compris en mobile.

N'en doutons pas, cette API est principalement pensée pour les terminaux mobiles mais peut aussi se montrer utile avec les PC portables. Il ne vous reste plus qu'à décider ce que vous en ferrez ensuite

Sources :

MDN API BatteryManager

MDN API GetBattery

Discussion forum

3 commentaires

SylvainPV
Rédacteur/Modérateur

Je retire le préfixe FAQ mis par erreur sur tes contributions d'article. Il faut absolument qu'on prenne le temps de gabariser, relire et publier tout ça.

le 06/03/2016 à 22:31
melka one
Membre expérimenté

bonjour

tu aurais pus évité cette ligne

(pourquoi Apple ce ferait chier à développer une API pas encore validée )

ca fait pas propre et surtout ca n'a rien a faire ici un cour ce doit être intègre.

il y a un deuxième point qui me titille c'est la taille de la police trop grosse et qui a mon avis sert faire plus espacé c'est pas top du tout.

le 01/12/2015 à 21:22
TiranusKBX
Expert confirmé

Envoyé par melka one

il y a un deuxième point qui me titille c'est la taille de la police trop grosse et qui a mon avis sert faire plus espacé c'est pas top du tout.

l'écriture en gros sert bien à aérer le texte car trop de texte suivit de près fatigue les yeux et n'incite pas à lire la suite, de plus cela rend plus visibles les textes en couleur

le 01/12/2015 à 22:36