电池状态 API

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

注

此方法在PR #51之前可在不安全的上下文中使用。

内部槽位	初始值	描述
[[BatteryPromise]]	`null`	对 `Promise` 的返回值，来源于对 `getBattery()` 的调用。
[[BatteryManager]]	`null`	在通过 `getBattery()` 创建后，关联到给定`Navigator` 的 `BatteryManager` 实例。

getBattery() 方法的步骤如下：

如果 this.[[BatteryPromise]] 为 null，则在 this 的相关域中创建一个新 Promise 并赋给它。
如果 this 的相关全局对象的关联 Document 不允许使用 “battery” 策略控制特性，则以 NotAllowedError 的DOMException 拒绝 this.[[BatteryPromise]]。
否则
1. 如果 this.[[BatteryManager]] 为 null，则在 this 的相关域中创建一个新的 BatteryManager 实例并赋给它。
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]] 内部槽位表示系统电池的充电状态。若电池在放电则**MUST**设为 false，若电池在充电、实现无法报告状态、或系统未连接电池等情况下则**MUST**设为 true。

当系统电池的充电状态发生变化时，用户代理必须以 true 或 false（取决于电池是充电还是放电）以及 “chargingchange” 为参数，运行更新电池状态并通知算法。

[[ChargingTime]] 内部槽位表示系统电池完全充满所剩余的秒数。若电池已满或系统未连接电池，则**MUST**设为 0；若电池在放电、实现无法报告剩余充电时间或其它情况，则**MUST**设为正无穷。

当电池的充电时间更新时，用户代理必须以新的充电时间（秒）以及 “chargingtimechange” 为参数，运行更新电池状态并通知算法。

[[DischargingTime]] 属性表示系统电池完全放电并导致系统即将挂起的剩余秒数。若电池在充电、实现无法报告剩余放电时间、系统未连接电池或其它情况，则**MUST**设为正无穷。

当电池的放电时间更新时，用户代理必须以新的放电时间（秒）以及 “dischargingtimechange” 为参数，运行更新电池状态并通知算法。

[[Level]] 内部槽位表示系统电池的电量水平。若系统电池电量耗尽且系统将被挂起，则**MUST**设为 0；若电池已满、实现无法报告电量或系统未连接电池，则**MUST**设为 1.0。

当电池电量水平更新时，用户代理必须以新的电量水平以及 “levelchange” 为参数，运行更新电池状态并通知算法。

注

关于何时触发 “chargingtimechange”、 “dischargingtimechange” 与 “levelchange” 事件的触发频率留给实现自行决定。

charging 的 getter 步骤为返回 this.[[Charging]]。

chargingTime 的 getter 步骤为返回 this.[[ChargingTime]]。

dischargingTime 的 getter 步骤为返回 this.[[DischargingTime]]。

level 的 getter 步骤为返回 this.[[Level]]。

以下是事件处理程序（及对应的事件类型），MUST 作为属性由BatteryManager 对象支持：

事件处理器	事件处理器事件类型
`onchargingchange`	`chargingchange`
`onchargingtimechange`	`chargingtimechange`
`ondischargingtimechange`	`dischargingtimechange`
`onlevelchange`	`levelchange`

要更新电池状态并通知（给定内部槽位 slot、值 value 与事件名 eventName），执行以下步骤：

令 global 为当前全局对象。
如果 global 不是Window，则终止本步骤。
令 navigator 为 global 的关联Navigator。
令 batteryManager 为 navigator 的[[BatteryManager]] 的值。
如果 batteryManager 为 null，则终止本步骤。
在全局任务队列的电池状态任务来源上，以 global 为上下文，执行以下步骤：
1. 将 batteryManager.slot 设为 value。
2. 在 batteryManager 上触发一个事件，其名称为 eventName。

如果宿主设备包含多个电池，BatteryManager SHOULD 提供统一的电池视图。

内部槽位 [[Charging]] MUST 为 true，只要至少有一个电池的充电状态为 true；否则 MUST 为 false。

内部槽位 [[ChargingTime]] 可设为各电池并行充电时的最大充电时间，或在串行充电时设为各电池充电时间之和。

内部槽位 [[DischargingTime]] 可设为各电池并行放电时的最大放电时间，或在串行放电时设为各电池放电时间之和。

内部槽位 [[Level]] 可设为同等容量电池的平均电量，或在容量不同的电池之间使用加权平均。

本节是非规范性的。

以下示例在每次电量变化时把电池电量写入控制台：

示例 1

// We get the initial value when the promise resolves ...
navigator.getBattery().then(function(battery) {
  console.log(battery.level);
  // ... and any subsequent updates.
  battery.onlevelchange = function() {
    console.log(this.level);
  };
});

同样的效果也可以使用 addEventListener() 方法实现：

示例 2

navigator.getBattery().then(function(battery) {
  console.log(battery.level);
  battery.addEventListener('levelchange', function() {
    console.log(this.level);
  });
});

下面的示例在指示灯上显示充电状态、电量水平以及剩余时间（单位：分钟）：

示例 3

<!DOCTYPE html>
<html>
<head>
  <title>Battery Status API Example</title>
  <script>
    window.onload = function () {
      function updateBatteryStatus(battery) {
        document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
        document.querySelector('#level').textContent = battery.level;
        document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
      }

      navigator.getBattery().then(function(battery) {
        // Update the battery status initially when the promise resolves ...
        updateBatteryStatus(battery);

        // .. and for any subsequent updates.
        battery.onchargingchange = function () {
          updateBatteryStatus(battery);
        };

        battery.onlevelchange = function () {
          updateBatteryStatus(battery);
        };

        battery.ondischargingtimechange = function () {
          updateBatteryStatus(battery);
        };
      });
    };
  </script>
</head>
<body>
  <div id="charging">(charging state unknown)</div>
  <div id="level">(battery level unknown)</div>
  <div id="dischargingTime">(discharging time unknown)</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] 定义了以下内容
- 允许使用 (allowed to use)
- 关联文档
- current global object (当前全局对象)
- 事件处理程序事件类型
- 事件处理程序
- EventHandler
- Navigator 接口
- 排队一个全局任务
- relevant global object
- relevant realm (相关领域)
- task source (任务源)
- 任务
- Window 接口
[PERMISSIONS-POLICY] 定义了以下内容
- 'self'（用于默认允许列表）
- 默认允许列表（针对策略控制的功能）
- 策略控制的功能 (policy-controlled feature)
[WEBIDL] 定义了以下内容
- a new promise (一个新的 promise)
- boolean 类型
- DOMException 接口
- double 类型
- [Exposed] 扩展属性
- new
- NotAllowedError 异常
- Promise 接口
- reject (拒绝)
- Resolve
- [SecureContext] 扩展属性
- this
- unrestricted double 类型

摘要

本文档状态

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. 权限策略集成

8. 示例

A. 索引

A.1 本规范定义的术语

A.2 通过引用定义的术语

B. IDL 索引

C. 致谢

D. 参考文献

D.1 规范性参考文献