バッテリーステータスAPI

この文書のステータス

このセクションは、本書の公開時点でのステータスについて説明しています。現行のW3C の出版物と、この技術レポートの最新版は、W3C技術レポート一覧 https://www.w3.org/TR/ で確認できます。

Devices and Sensors Working Groupは、本仕様に編集上の近代化を適用し、APIのセキュリティ及びプライバシーの側面について自己レビューと改訂を行い、水平レビューを申請する前に一巡します。既存のセキュリティとプライバシーの課題が公開されています。

本書はDevices and Sensors Working Groupによって勧告プロセスを用いて作業草案として公開されました。

作業草案として公開された文書は、W3Cおよびそのメンバーによる承認を意味するものではありません。

本書はドラフト文書であり、いつでも更新・置換・廃止される可能性があります。進行中の作業以外の目的で本書を引用することは適切ではありません。

本書は W3C 特許ポリシーの下で活動するグループによって作成されました。 W3Cは、グループの成果物に関連する公開特許開示リストを管理しています。そのページには特許開示の手続きも記載されています。個人が本仕様に関連する必須請求項を含む特許について知っている場合は、 W3C特許ポリシー第6節に従い開示する必要があります。

WebIDL[SecureContext]
partial interface Navigator {
  Promise<BatteryManager> getBattery();
};

注

このメソッドはPR #51まで非セキュアコンテキストでも公開されていました。

内部スロット	初期値	説明
[[BatteryPromise]]	`null`	`Promise`は、`getBattery()`の呼び出しで返されます。
[[BatteryManager]]	`null`	`BatteryManager` インスタンスは、 `Navigator`が `getBattery()`によって作成された後に関連付けられます。

getBattery() メソッドの手順は以下の通りです：

this.[[BatteryPromise]]がnullなら、新しいPromiseを thisの関連realmで設定する。
thisの関連グローバルオブジェクトの関連付けられたDocumentが "battery" ポリシー制御機能の利用を許可されていない場合、 reject this.[[BatteryPromise]]に "NotAllowedError" DOMExceptionを返す。
それ以外の場合：
1. this.[[BatteryManager]]が nullなら、新しい BatteryManagerを thisの関連realmで作成する。
2. resolve this.[[BatteryPromise]]に this.[[BatteryManager]]を設定する。
this.[[BatteryPromise]]を返す。

WebIDL[SecureContext, Exposed=Window]
interface BatteryManager : EventTarget {
    readonly        attribute boolean             charging;
    readonly        attribute unrestricted double chargingTime;
    readonly        attribute unrestricted double dischargingTime;
    readonly        attribute double              level;
                    attribute EventHandler        onchargingchange;
                    attribute EventHandler        onchargingtimechange;
                    attribute EventHandler        ondischargingtimechange;
                    attribute EventHandler        onlevelchange;
};

BatteryManager インターフェイスは、ホストデバイスの現在のバッテリー状態情報を表します。

ユーザーエージェントは、何らかの属性値を報告できない場合、例えばユーザーやシステムの設定、制限などにより、バッテリー状態情報を報告できないとされます。

注

BatteryManager インスタンスは、以下の内部スロットを持って作成されます:

内部スロット	初期値
[[Charging]]	`true`
[[ChargingTime]]	0
[[DischargingTime]]	正の無限大
[[Level]]	1.0

[[Charging]] 内部スロットは、システムバッテリーの充電状態を表します。バッテリーが放電中の場合は false に、充電中の場合、状態を報告できない場合、バッテリーがシステムに接続されていない場合、その他の場合は true に設定 しなければならない 。

システムバッテリーの充電状態が変化したとき、ユーザーエージェントはバッテリー状態を更新して通知アルゴリズムを、[[Charging]]、true または false（充電か放電か）、および "chargingchange" を用いて実行しなければなりません。

[[ChargingTime]] 内部スロットは、システムバッテリーがフル充電になるまでの残り時間（秒）を表します。バッテリーが満タンの場合やバッテリーが接続されていない場合は 0 に、放電中の場合、残り充電時間を報告できない場合、その他の場合は正の無限大に設定 しなければならない 。

バッテリーの充電時間が更新された際、ユーザーエージェントはバッテリー状態を更新して通知アルゴリズムを、[[ChargingTime]]、新しい充電時間（秒）、および "chargingtimechange" を用いて実行します。

[[DischargingTime]] 属性は、システムバッテリーが完全に放電し、システムがサスペンドされるまでの残り時間（秒）を表します。バッテリーが充電中の場合、残り放電時間を報告できない場合、バッテリーが接続されていない場合、その他の場合は正の無限大に設定 しなければならない 。

バッテリーの放電時間が更新された際、ユーザーエージェントはバッテリー状態を更新して通知アルゴリズムを、[[DischargingTime]]、新しい放電時間（秒）、および "dischargingtimechange" を用いて実行します。

[[Level]] 内部スロットは、システムバッテリーのレベルを表します。バッテリーが枯渇しシステムがサスペンド直前の場合は 0 に、バッテリーが満タンの場合、レベルを報告できない場合、バッテリーが接続されていない場合は 1.0 に設定 しなければならない 。

バッテリーレベルが更新された際、ユーザーエージェントはバッテリー状態を更新して通知アルゴリズムを、[[Level]]、新しいバッテリーレベル、および "levelchange" を用いて実行します。

注

"chargingtimechange"、"dischargingtimechange"、および "levelchange" イベントがどのくらいの頻度で発火されるかは実装に委ねられています。

charging の getter 手順は、this.[[Charging]] を返します。

chargingTime の getter 手順は、this.[[ChargingTime]] を返します。

dischargingTime の getter 手順は、this.[[DischargingTime]] を返します。

level の getter 手順は、this.[[Level]] を返します。

以下は、イベントハンドラ（および対応するイベントハンドライベントタイプ）であり、BatteryManager オブジェクトの属性として サポートしなければならない ものです:

イベントハンドラ	イベントハンドライベントタイプ
`onchargingchange`	`chargingchange`
`onchargingtimechange`	`chargingtimechange`
`ondischargingtimechange`	`dischargingtimechange`
`onlevelchange`	`levelchange`

内部スロット slot、value、および eventName を受け取り、バッテリー状態を更新して通知するには、以下の手順を実行します:

global を現在のグローバルオブジェクトとします。
global が Window でない場合、この手順を中止します。
navigator を global に関連付けられた Navigator とします。
batteryManager を navigator の値、すなわち [[BatteryManager]] とします。
batteryManager が null の場合、この手順を中止します。
グローバルタスクをキューに、battery status task source を global に指定して、以下の手順を実行します:
1. batteryManager.slot を value に設定します。
2. event を発火し、名前は eventName、対象は batteryManager です。

ホストデバイスに複数のバッテリーが含まれる場合、BatteryManager はバッテリーの統合ビューを 提供すべき です。

[[Charging]] 内部スロットは、少なくとも1つのバッテリーの充電状態が true の場合は true に、それ以外は false に設定 しなければならない 。

[[ChargingTime]] 内部スロットは、並列充電の場合は個々のバッテリーの最大充電時間、直列充電の場合は個々の充電時間の合計に設定できます。

[[DischargingTime]] 内部スロットは、並列放電の場合は個々のバッテリーの最大放電時間、直列放電の場合は個々の放電時間の合計に設定できます。

[[Level]] 内部スロットは、同容量のバッテリーの場合はレベルの平均値、容量が異なるバッテリーの場合は容量加重平均に設定できます。

// Promiseが解決された時点で初期値を取得... navigator.getBattery().then(function(battery) { console.log(battery.level); // ...そして以降の更新も取得 battery.onlevelchange = function() { console.log(this.level); }; });

<!DOCTYPE html> <html> <head> <title>Battery Status API 例</title> <script> window.onload = function () { function updateBatteryStatus(battery) { document.querySelector('#charging').textContent = battery.charging ? '充電中' : '未充電'; document.querySelector('#level').textContent = battery.level; document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60; } navigator.getBattery().then(function(battery) { // Promiseが解決された時点でバッテリー状態を更新 updateBatteryStatus(battery); // 以降の更新にも対応 battery.onchargingchange = function () { updateBatteryStatus(battery); }; battery.onlevelchange = function () { updateBatteryStatus(battery); }; battery.ondischargingtimechange = function () { updateBatteryStatus(battery); }; }); }; </script> </head> <body> <div id="charging">(充電状態不明)</div> <div id="level">(バッテリーレベル不明)</div> <div id="dischargingTime">(放電時間不明)</div> </body> </html>

battery status task source §4.
BatteryManager インターフェイス §6.
[[BatteryManager]] Navigator の内部スロット §5.1
[[BatteryPromise]] Navigator の内部スロット §5.1
charging BatteryManager の属性 §6.2
[[Charging]] BatteryManager の内部スロット §6.1
chargingchange §6.6
chargingTime BatteryManager の属性 §6.3
[[ChargingTime]] BatteryManager の内部スロット §6.1
chargingtimechange §6.6
current battery status information §6.
dischargingTime BatteryManager の属性 §6.4
[[DischargingTime]] BatteryManager の内部スロット §6.1
dischargingtimechange §6.6
getBattery() Navigator のメソッド §5.2
level BatteryManager の属性 §6.5
[[Level]] BatteryManager の内部スロット §6.1
levelchange §6.6
onchargingchange BatteryManager の属性 §6.6
onchargingtimechange BatteryManager の属性 §6.6
ondischargingtimechange BatteryManager の属性 §6.6
onlevelchange BatteryManager の属性 §6.6
unable to report the battery status information §6.
update the battery status and notify §6.7
user agent §2.

[DOM] で定義されるもの:
- EventTarget インターフェイス
- イベント発火
[ECMASCRIPT] で定義されるもの:
- 内部スロット
[HTML] で定義されるもの:
- 利用許可
- 関連付けられたDocument
- 現在のグローバルオブジェクト
- イベントハンドラのイベントタイプ
- イベントハンドラ
- EventHandler
- Navigator インターフェイス
- グローバルタスクのキュー
- 関連グローバルオブジェクト
- 関連レルム
- タスクソース
- タスク
- Window インターフェイス
[PERMISSIONS-POLICY] で定義されるもの:
- 'self' （デフォルト許可リスト用）
- デフォルト許可リスト（ポリシー管理機能用）
- ポリシー管理機能
[WEBIDL] で定義されるもの:
- 新しいpromise
- boolean 型
- DOMException インターフェイス
- double 型
- [Exposed] 拡張属性
- new
- NotAllowedError 例外
- Promise インターフェイス
- reject
- Resolve
- [SecureContext] 拡張属性
- this
- unrestricted double 型

WebIDL[SecureContext] partial interface Navigator { Promise<BatteryManager> getBattery(); }; [SecureContext, Exposed=Window] interface BatteryManager : EventTarget { readonly attribute boolean charging; readonly attribute unrestricted double chargingTime; readonly attribute unrestricted double dischargingTime; readonly attribute double level; attribute EventHandler onchargingchange; attribute EventHandler onchargingtimechange; attribute EventHandler ondischargingtimechange; attribute EventHandler onlevelchange; };

バッテリーステータスAPI

概要

この文書のステータス

1. はじめに

2. 適合性

3. セキュリティとプライバシーに関する考慮事項

4. 概念

5. `Navigator` インターフェースへの拡張

5.1 内部スロット

5.2 `getBattery()` メソッド

6. `BatteryManager` インターフェイス

6.1 内部スロット

6.1.1 `[[Charging]]` 内部スロット

6.1.2 `[[ChargingTime]]` 内部スロット

6.1.3 `[[DischargingTime]]` 内部スロット

6.1.4 `[[Level]]` 内部スロット

6.2 `charging` 属性

6.3 `chargingTime` 属性

6.4 `dischargingTime` 属性

6.5 `level` 属性

6.6 イベントハンドラ

6.7 アルゴリズム

6.8 複数バッテリー

7. Permissions Policyの統合

8. 例

A. 索引

A.1 本仕様書で定義される用語

A.2 他の規格で定義される用語

B. IDL索引

C. 謝辞

D. 参考文献

D.1 規範的参考文献

バッテリーステータスAPI

概要

この文書のステータス

1. はじめに

2. 適合性

3. セキュリティとプライバシーに関する考慮事項

4. 概念

5. Navigator インターフェースへの拡張

5.1 内部スロット

5.2 getBattery() メソッド

6. BatteryManager インターフェイス

6.1 内部スロット

6.1.1 [[Charging]] 内部スロット

6.1.2 [[ChargingTime]] 内部スロット

6.1.3 [[DischargingTime]] 内部スロット

6.1.4 [[Level]] 内部スロット

6.2 charging 属性

6.3 chargingTime 属性

6.4 dischargingTime 属性

6.5 level 属性

6.6 イベントハンドラ

6.7 アルゴリズム

6.8 複数バッテリー

7. Permissions Policyの統合

8. 例

A. 索引

A.1 本仕様書で定義される用語

A.2 他の規格で定義される用語

B. IDL索引

C. 謝辞

D. 参考文献

D.1 規範的参考文献

5. `Navigator` インターフェースへの拡張

5.2 `getBattery()` メソッド

6. `BatteryManager` インターフェイス

6.1.1 `[[Charging]]` 内部スロット

6.1.2 `[[ChargingTime]]` 内部スロット

6.1.3 `[[DischargingTime]]` 内部スロット

6.1.4 `[[Level]]` 内部スロット

6.2 `charging` 属性

6.3 `chargingTime` 属性

6.4 `dischargingTime` 属性

6.5 `level` 属性