Battery Status API （日本語訳）

◎要約

この仕様は、 ~hostしている~deviceの~battery状態sについての情報を供する~APIを定義する。 ◎ This specification defines an API that provides information about the battery status of the hosting device.

1. 序論

◎非規範的

`~battery状態s~API^cite（ `Battery Status API^en ）は、 ~web開発者~用に［ ~hostしている~deviceの~battery状態sを~program的に決定する手段］を定義する。 ~web開発者は、［ ~deviceの~battery状態sを知り得ない下で~web~appを設計する］ときは，［ ~battery~levelは、目下の~task用に足りている］と見做すしかなくなる。このことは、［ ~deviceの~batteryは、欲されるより速く枯渇し得る］ことを意味する — ~web開発者は、 ~battery状態sに基づいて裁定を下せないので。 ~battery状態sの知識がある下では、 ~web開発者は，~web内容と~appを効率的に電力を使うよう細工-可能になり、その結果，利用者~体験も改善される。しかしながら、作者は，［この~APIの素朴な実装【利用？】は、 ~batteryを短命にし得る］ことを自覚するべきである。 ◎ The Battery Status API specification defines a means for web developers to programmatically determine the battery status of the hosting device. Without knowing the battery status of a device, a web developer must design the web application with an assumption of sufficient battery level for the task at hand. This means the battery of a device may exhaust faster than desired because web developers are unable to make decisions based on the battery status. Given knowledge of the battery status, web developers are able to craft web content and applications which are power-efficient, thereby leading to improved user experience. Authors should be aware, however, that a naïve implementation of this API can negatively affect the battery life.

`~battery状態s~API^citeは、 ~deviceの~batteryが［充電-中でないか, 残り少ない］ときには，作業を［先送りする／縮小する］ために利用できる。高度な~web~appの模範型（ `archetype^en ）や ~web上の~email~clientは、［ ~deviceを充電している間は、数秒ごとに新着~emailの有無を~serverに問い合わせる］一方で，［ ~deviceの~batteryが［充電-中でない／残り少ない］場合には、その頻度を下げる］こともあろう。別の例として、 ~web上の編集~appは，［ ~battery~levelを監視して、 ~batteryが尽きる前に変更を保存して，~data喪失を防止する］こともできる。 ◎ The Battery Status API can be used to defer or scale back work when the device is not charging in or is low on battery. An archetype of an advanced web application, a web-based email client, may check the server for new email every few seconds if the device is charging, but do so less frequently if the device is not charging or is low on battery. Another example is a web-based word processor which could monitor the battery level and save changes before the battery runs out to prevent data loss.

2. 適合性

【この節の内容は ~W3C日本語訳共通~pageに移譲。】

3. ~security／~privacyの考慮点

この仕様に定義される~APIは、 ~hostしている~deviceの~battery状態sを決定するために利用される。 ~UAは： ◎ The API defined in this specification is used to determine the battery status of the hosting device.

~battery状態s情報の高-精度な読出を公開するベキでない — 新たな指紋収集~行路を導入し得るので。 ◎ The user agent SHOULD not expose high precision readouts of battery status information as that can introduce a new fingerprinting vector.
~battery状態s情報への~access【の許可】を利用者に依頼してもヨイ。あるいは、私的~閲覧~modeにおいては，利用者~許可の要件を施行してもヨイ。 ◎ The user agent MAY ask the user for battery status information access, or alternatively, enforce the user permission requirement in its private browsing modes.
~scriptによるこの~APIの利用を控えめな方式で，利用者に伝えるベキである — 透明性を援助するため，および ~API~access【の許可】を~revokeすることを利用者に許容するため。 ◎ The user agent SHOULD inform the user of the API use by scripts in an unobtrusive manner to aid transparency and to allow the user to revoke the API access.
［ ~hostしている~deviceには~batteryは無い／ ~batteryは充電-中／捏造した値を公開している］場合には、公開される値を作者が直に知り得ない仕方でボヤカしてもヨイ。 ◎ The user agent MAY obfuscate the exposed value in a way that authors cannot directly know if a hosting device has no battery, is charging or is exposing fake values.

4. 概念

この仕様~内に言及される`~task$用の`~task~source$は、 `~battery状態s~task~source@ とする。 ◎ The task source for the tasks mentioned in this specification is the battery status task source.

5. `Navigator^I ~interfaceに対する拡張

[`SecureContext$]
partial interface `Navigator$I {
  `Promise$<`BatteryManager$I> `getBattery$m();
};

注記： `getBattery()^m ~methodは、 pull 要請 #51 が取り込まれるまでは， ~secureでない文脈にも公開されていた。 ◎ Note This method was exposed to a non-secure context until PR #51.

各 `Navigator$I ~obj %~navigator は、次に挙げる内部~slotを伴う：

`BatteryPromise@sl: 初期~値は ~NULL とする。; %~navigator に対する `getBattery()$m の~callに対し返される `Promise$c 。
`BatteryManager@sl: 初期~値は ~NULL とする。; %~navigator に結付けられた `BatteryManager$I ~instance — `getBattery()$m を介して作成されたならば。

◎ 5.1 Internal slots ◎ Internal slot｜Initial value｜Description [[BatteryPromise]]｜null｜A Promise returned by calls to getBattery(). [[BatteryManager]]｜null｜The BatteryManager instance associated with a given Navigator after it has been created via getBattery().

`getBattery()@m ~method手続きは： ◎ 5.2 The getBattery() method ◎ The getBattery() method steps are:

~test： `battery-promise-window$test, `battery-promise$test （これらの~testには、~secureな接続（~HTTPS）が要求される） ◎ tests: 2 • battery-promise-window 🔒 • battery-promise 🔒

~IF［コレ.`BatteryPromise$sl ~EQ ~NULL ］ ⇒ コレ.`BatteryPromise$sl ~SET `新たな~promise$( コレに`関連な~realm$ ) ◎ If this.[[BatteryPromise]] is null, then set it to a new promise in this's relevant realm.
%文書 ~LET コレに`関連な大域~obj$に`結付けられた文書$ ◎ ↓
~IF［ %文書には［ `battery^l で識別される`施策により制御される特能$ ］の`利用は許容されて$いない］ ⇒ `~promiseを却下する$( コレ.`BatteryPromise$sl, `NotAllowedError$E 例外 ) ◎ If this's relevant global object's associated Document is not allowed to use the "battery" policy-controlled feature, then reject this.[[BatteryPromise]] with a "NotAllowedError" DOMException.
~ELSE： ◎ Otherwise:
1. ~IF［コレ.`BatteryManager$sl ~EQ ~NULL ］ ⇒ コレ.`BatteryManager$sl ~SET `新たな~obj$( `BatteryManager$I, コレに`関連な~realm$ ) ◎ If this.[[BatteryManager]] is null, then set it to the result of creating a new BatteryManager in this's relevant realm.
2. `~promiseを解決する$( コレ.`BatteryPromise$sl, コレ.`BatteryManager$sl ) ◎ Resolve this.[[BatteryPromise]] with this.[[BatteryManager]].
~RET コレ.`BatteryPromise$sl ◎ Return this.[[BatteryPromise]].

6. `BatteryManager^I ~interface

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

`BatteryManager@I ~interfaceは、 ~hostしている~deviceの `現在の~battery状態s情報@ を表現する。 ◎ The BatteryManager interface represents the current battery status information of the hosting device.

~UAは、 — 例えば、［利用者または~system ］の［選好／設定／制限］に因り — 【！any of】ある属性~用の値を報告-不能な場合，【その属性に関して？】 `~battery状態s情報を報告-不能@ であるとされる。 ◎ The user agent is said to be unable to report the battery status information if it is not able to report the values for any of the attributes, for example, due to a user or system preference, setting, or limitation.

注記： ~UAが`~battery状態s情報を報告-不能$な場合、 `BatteryManager$I の各~内部~slotは，各自の既定の値であり続ける — それは、全部的に充電された~batteryを模倣する。このことは、例えば［ ~battery状態s情報が可用にされていない場合］に，［指紋収集の~~可能性を抑制すること, および ~appが処理能を退行させるのを防止すること］を目指す。 ◎ Note If the user agent is unable to report the battery status information, the BatteryManager's internal slots will remain with their default values, which emulate a fully charged and plugged in battery. This is aimed at reducing the potential for fingerprinting and preventing applications from degrading performance, if the battery status information is not made available, for example.

6.1. 内部~slot

各 `BatteryManager$I ~instanceは、次に挙げる`内部~slot$を伴って作成される： ◎ 6.1 Internal slots ◎ BatteryManager instances are created with the following internal slots: ◎ Internal slot｜Initial value [[Charging]]｜true [[ChargingTime]]｜0 [[DischargingTime]]｜Positive Infinity [[Level]]｜1.0

`Charging@sl ◎ The [[Charging]] internal slot

初期~値は `true^jv とする。 ◎ ↑

~systemの~batteryの充電~状態を表現する： ◎ The [[Charging]] internal slot represents the charging state of the system's battery.＼

次に該当する場合は ~F に設定するモノトスル ⇒＃ ~batteryは放電-中 ◎ It MUST be set to false if the battery is discharging,＼
他の場合 — 次に該当する場合など — は ~T に設定するモノトスル ⇒＃実装は~battery充電~状態を報告-不能である／ ~batteryは充電-中／ ~systemは~batteryを装備していない ◎ and set to true if the battery is charging, the implementation is unable to report the state, or there is no battery attached to the system, or otherwise.

~system~batteryの充電~状態が変化したときは、次を走らすモノトスル：

%値 ~LET 当の~batteryは［充電-中ならば ~T ／放電-中ならば ~F ］
`~battery状態sを更新して通知する$( `Charging$sl, %値, `chargingchange$et )

◎ When the system battery's charging state changes, the user agent must run the update the battery status and notify algorithm with [[Charging]], true or false depending on whether the battery is charging or discharging, and "chargingchange".

`ChargingTime@sl ◎ 6.1.2 The [[ChargingTime]] internal slot

初期~値は `0^jv とする。 ◎ ↑

［ ~systemの~batteryが全部的に充電される］までの残り時間を，秒数で表現する： ◎ The [[ChargingTime]] internal slot represents the remaining time in seconds until the system's battery is fully charged.＼

次に該当する場合は 0 に設定するモノトスル ⇒＃ ~batteryは満杯／ ~systemは~batteryを装備していない ◎ It MUST be set to 0 if the battery is full or there is no battery attached to the system,＼
他の場合 — 次に該当する場合など — は `+Infinity^jv に設定するモノトスル ⇒＃ ~batteryは放電-中／実装は残りの充電~時間を報告-不能 ◎ and to the value positive Infinity if the battery is discharging, the implementation is unable to report the remaining charging time, or otherwise.

~battery充電~時間が更新されたときは、次を走らすモノトスル ⇒ `~battery状態sを更新して通知する$( `ChargingTime$sl, 秒数による新たな充電~時間, `chargingtimechange$et ) ◎ When the battery charging time is updated, the user agent must run the update the battery status and notify algorithm with [[ChargingTime]], the new charging time in seconds, and "chargingtimechange".

`DischargingTime@sl ◎ 6.1.3 The [[DischargingTime]] internal slot

初期~値は `+Infinity^jv とする。 ◎ ↑

［ ~systemの~batteryが完全に放電され，~systemは休止されようとする］までの残り時間を，秒数で表現する。 ◎ The [[DischargingTime]] attribute represents the remaining time in seconds until the system's battery is completely discharged and the system is about to be suspended.＼

放電していない場合【！or otherwise】 — 次に該当する場合など — は `+Infinity^jv に設定するモノトスル ⇒＃ ~batteryは充電-中／実装は残りの放電~時間を報告-不能／ ~systemは~batteryを装備していない ◎ It MUST be set to the value positive Infinity if the battery is charging, the implementation is unable to report the remaining discharging time, there is no battery attached to the system, or otherwise.

~battery放電~時間が更新されたときは、次を走らすモノトスル ⇒ `~battery状態sを更新して通知する$( `DischargingTime$sl, 秒数による新たな放電~時間, `dischargingtimechange$et ) ◎ When the battery discharging time is updated, the user agent must run the update the battery status and notify algorithm with [[DischargingTime]], the new discharging time in seconds, and "dischargingtimechange".

`Level@sl ◎ 6.1.4 The [[Level]] internal slot

初期~値は `1.0^jv とする。 ◎ ↑

~systemの~batteryの~levelを表現する。 ◎ The [[Level]] internal slot represents the system's battery's level.＼

次に該当する場合は 0 に設定するモノトスル ⇒＃ ~batteryを使い果たしたため~systemは休止されつつある ◎ It MUST be set to 0 if the system's battery is depleted and the system is about to be suspended,＼
次に該当する場合は 1.0 に設定するモノトスル ⇒＃ ~batteryは満杯／実装は~battery~levelを報告-不能／ ~systemは~batteryを装備していない ◎ and to 1.0 if the battery is full, the implementation is unable to report the battery's level, or there is no battery attached to the system.

~battery~levelが更新されたときは、次を走らすモノトスル ⇒ `~battery状態sを更新して通知する$( `Level$sl, 新たな~battery~level, `levelchange$et ) ◎ When the battery level is updated, the user agent must run the update the battery status and notify algorithm with [[Level]], the new battery level, and "levelchange".

注記：［ `chargingtimechange$et ／ `dischargingtimechange$et ／ `levelchange$et ］~eventを発火する~~頻度は、実装に委ねられる。 ◎ Note The definition of how often the "chargingtimechange", "dischargingtimechange", and "levelchange" events are fired is left to the implementation.

6.2.〜6.5. 属性

`charging@m 取得子~手続きは ⇒ ~RET コレ.`Charging$sl ◎ 6.2 The charging attribute ◎ The charging getter steps are to return this.[[Charging]].

`chargingTime@m 取得子~手続きは ⇒ ~RET コレ.`ChargingTime$sl ◎ 6.3 The chargingTime attribute ◎ The chargingTime getter steps are to return this.[[ChargingTime]].

`dischargingTime@m 取得子~手続きは ⇒ ~RET コレ.`DischargingTime$sl ◎ 6.4 The dischargingTime attribute ◎ The dischargingTime getter steps are to return this.[[DischargingTime]].

`level@m 取得子~手続きは ⇒ ~RET コレ.`Level$sl ◎ 6.5 The level attribute ◎ The level getter steps are to return this.[[Level]].

6.6. ~event~handler

`BatteryManager$I ~objは、その属性として，次に挙げる`~event~handler$ （および，それぞれに対応する`~event~handler~event型$）を~supportするモノトスル： ◎ The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the BatteryManager object:

~event~handler	~event~handler~event型
`onchargingchange@m	`chargingchange@et
`onchargingtimechange@m	`chargingtimechange@et
`ondischargingtimechange@m	`dischargingtimechange@et
`onlevelchange@m	`levelchange@et

6.7. ~algo

`~battery状態sを更新して通知する@ ときは、所与の ( 内部~slot %~slot, %値, %~event名 ) に対し，次の手続きを走らす： ◎ To update the battery status and notify given an internal slot slot, a value and an eventName, run the following steps:

%大域~obj ~LET `現在の大域~obj$ ◎ Let global be the current global object.
~IF［ %大域~obj は `Window$I でない］ ⇒ ~RET ◎ If global is not a Window, abort these steps.
%~navigator ~LET %大域~obj に結付けられた `Navigator$I ~obj ◎ Let navigator be global's associated Navigator.
%~battery管理器 ~LET %~navigator.`BatteryManager$sl ◎ Let batteryManager be the value of navigator. [[BatteryManager]].
~IF［ %~battery管理器 ~EQ ~NULL ］ ⇒ ~RET ◎ If batteryManager is null, abort these steps.
`大域~taskを~queueする$( `~battery状態s~task~source$, %大域~obj, 次の手続き ) ◎ Queue a global task on the battery status task source given global to＼
手続きは： ◎ run the following steps:
1. %~battery管理器.%~slot ~SET %値 ◎ Set batteryManager.slot to value.
2. `~eventを発火する$( %~battery管理器, %~event名 ) ◎ Fire an event named eventName at batteryManager.

6.8. ~batteryが複数個ある場合

~hostしている~deviceが複数個の~batteryを備えている場合、 `BatteryManager$I は，それらの~batteryを一体化した~viewを公開するベキである： ◎ If a hosting device contains more than one battery, BatteryManager SHOULD expose a unified view of the batteries.

`Charging$sl 内部~slotは、［ある~batteryの充電~状態が上で述べたとおり ~T になるならば ~T ／ ~ELSE_ ~F ］に設定するモノトスル。 ◎ The [[Charging]] internal slot MUST be set to true if at least one battery's charging state as described above is true. Otherwise, it MUST be set to false.
`ChargingTime$sl 内部~slotは、［並列に充電している場合は個々の~batteryの最大~充電~時間／直列に充電している場合は個々の充電~時間の総和］に設定できる。 ◎ The [[ChargingTime]] internal slot can be set to the maximum charging time of the individual batteries if charging in parallel, and to the sum of the individual charging times if charging serially.
`DischargingTime$sl 内部~slotは、［並列に放電している場合は個々の~batteryの最大~放電~時間／直列に放電している場合は個々の放電~時間の総和］に設定できる。 ◎ The [[DischargingTime]] internal slot can be set to the maximum discharging time of the individual batteries if discharging in parallel, and to the sum of individual discharging times if discharging serially.
`Level$sl 内部~slotは、［各~batteryの~battery~levelの容量に応じた加重~平均（容量がすべて同じなら，単に平均）］に設定できる。 ◎ The [[Level]] internal slot can be set to the average of the levels of batteries of same capacity, or the weighted average of the battery levels for batteries of different capacities.

【 ~battery状態s情報を報告-不能なもの, 可能なものが混在している場合、どう挙動するべきかは述べられていない。】

7. 許可~施策との統合

`~battery状態s~API^citeは、 `施策により制御される特能$であり，文字列 `battery^l により識別される。その`既定の許容list$は、 `'self'$l とする。 ◎ The Battery Status API is a policy-controlled feature identified by the string "battery". Its default allowlist is 'self'.

8. 例

◎非規範的

~levelが変化する各回ごとに，~battery~levelを~consoleに書込む~~簡単な例： ◎ This trivial example writes the battery level to the console each time the level changes: ◎ Example 1

/* 
~promiseが解決されたとき、
初期~値を取得して…
◎
We get the initial value when the promise resolves ...
 */
navigator.`getBattery$0().then(function(%battery) {
  console.log(%battery.`level$0);
  /* 
…後続な更新も取得する。
◎
... and any subsequent updates.
 */
  %battery.`onlevelchange$0 = function() {
    console.log(this.`level$0);
  };
});

別法として， `addEventListener()$m ~methodを利用しても同じになる： ◎ Alternatively, the same using the addEventListener() method: ◎ Example 2

navigator.`getBattery$0().then(function(%battery) {
  console.log(%battery.`level$0);
  %battery.`addEventListener$0('`levelchange$et', function() {
    console.log(this.`level$0);
  });
});

次の例では、［充電~状態, ~level, 分単位の残り時間］を示す指示子を更新する： ◎ The following example updates the indicators to show the charging state, level and time remaining in minutes: ◎ Example 3

<!DOCTYPE html>
<html>
<head>
  <title>Battery Status API Example</title>
  <script>
    window.onload = function () {
      function updateBatteryStatus(%battery) {
        document.`querySelector$0('#charging').`textContent$0 = %battery.`charging$0 ? '充電-中' : '充電-中でない';
        document.`querySelector$0('#level').`textContent$0 = %battery.`level$0;
        document.`querySelector$0('#dischargingTime').`textContent$0 = %battery.`dischargingTime$0 / 60;
      }

      navigator.`getBattery$0().then(function(%battery) {
        /* 
初期~時に~promiseが解決されたとき，~battery状態sを更新して…
◎
Update the battery status initially when the promise resolves ...
 */
        updateBatteryStatus(%battery);

        /* 
…後続な更新も取得する。
◎
.. and for any subsequent updates.
 */
        %battery.`onchargingchange$0 = function () {
          updateBatteryStatus(%battery);
        };

        %battery.`onlevelchange$0 = function () {
          updateBatteryStatus(%battery);
        };

        %battery.`ondischargingtimechange$0 = function () {
          updateBatteryStatus(%battery);
        };
      });
    };
  </script>
</head>
<body>
  <div id="charging">（充電~状態は未知）</div>
  <div id="level">（~battery~levelは未知）</div>
  <div id="dischargingTime">（放電し切るまでの時間は未知）</div>
</body>
</html>

謝辞

The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and the Mozilla WebAPI team in general for their invaluable feedback based on prototype implementations. Many thanks to the people behind the System Information API and Device Orientation Event specification for the initial inspiration. Also thanks to the nice folks bringing us the Page Visibility specification, which motivated the editor of this specification to write the introduction chapter discussing some real-world high value use cases that apply equally to this specification. Special thanks to all the participants of the Device APIs Working Group and others who have sent in substantial feedback and comments, and made the Web a better place for everyone by doing so. Finally, thanks to Lukasz Olejnik, Gunes Acar, Claude Castelluccia, and Claudia Diaz for the privacy analysis of the API.