cordova-plugin-battery-status で端末の電源状況を確認する

cordova-plugin-battery-status を入れると、端末のバッテリー状況をチェックできる。バッテリーが低下してきたら cordova-plugin-brightness と組み合わせて自動的に画面を暗くしたり、USB 給電されている場合のみ動画を再生させたり、といった、電源状況に応じた処理分岐が可能になる。

• GitHub - apache/cordova-plugin-battery-status: Mirror of Apache Cordova Plugin battery-status

プラグインのインストール

$ cordova plugin add cordova-plugin-battery-status

検知できるイベントと情報

検知できるイベントは3種類。

• batterystatus は 1% でも充電の割合が変わったり、USB 接続や切断がされた時に発火する。
• batterylow は充電の割合が 20% 以下など、かなり低い状態になると発火する。
• batterycritical は充電の割合が 10% 以下など、バッテリー切れ直前になると発火する。

batterylow と batterycritical の基準値はデバイスによって異なる。

それぞれのイベントで取得できる内容は、バッテリーの割合 (level) と、USB 等で給電中か否か (isPlugged) の情報。

イベントの検知方法

以下のようにイベントを定義して情報を取得することができる。

document.addEventListener('deviceready', () => {
  window.addEventListener('batterystatus', (info) => {
    console.log(`バッテリー状況変化 : 残${info.level}%・${info.isPlugged ? '充電中' : '充電していない'}`);
  });
  
  window.addEventListener('batterylow', (info) => {
    console.log(`バッテリー少なめ : 残${info.level}%・${info.isPlugged ? '充電中' : '充電していない'}`);
  });
  
  window.addEventListener('batterycritical', (info) => {
    console.log(`バッテリー切れ寸前 : 残${info.level}%・${info.isPlugged ? '充電中' : '充電していない'}`);
  });
});

Cordova のコアが提供している deviceready イベントは document にアタッチされるが、Cordova プラグインの類はほとんどグローバル変数 (= window) 直下に配置されることが多いので、この Battery Status プラグインのイベントも window にアタッチするところに注意。

また、deviceready イベント発火後にイベント追加してやらないと、うまくイベントが設定できないので注意。Cordova プラグインが提供する独自のイベントハンドラは全て deviceready イベント発火後に設定してやるのが良さそう。例えば Cordova コアが提供する pause イベントの場合も、公式のリファレンスに以下のように記載されている。

通常は、 Cordova の 'deviceready' イベントを受け取った後、document.addEventListener を通じてイベントリスナーをセットします。

• 参考：pause - Apache Cordova

このプラグインだけだと電源状況を取得するだけだが、組み合わせ方次第で様々な使い方ができそうだ。