电池状态 API

本文档状态

本节描述了本文档在发布时的状态。当前 W3C 发布的文档列表以及本技术报告的最新修订版可在 W3C 技术报告索引中找到：https://www.w3.org/TR/。

设备与传感器工作组将在请求水平审查之前对本规范进行编辑现代化、自我审查，并对 API 的安全和隐私方面进行修订。现有的安全和隐私问题可供查看。

作为工作草案发布并不意味着 W3C 及其成员的认可。

本文档是草稿，可能会随时更新、替换或被其他文档废弃。将本文档作为除工作进展之外的其他用途引用是不适当的。

本文档由一个根据 W3C 专利政策运行的工作组制作。 W3C 维护了一个公开的专利披露列表，与工作组的交付物相关；该页面还包括披露专利的说明。任何个人如果实际知道某项专利，并认为该专利包含必要声明，必须根据 W3C 专利政策第 6 节披露相关信息。

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

注意

此方法在 PR #51 之前曾暴露于非安全上下文。

内部槽	初始值	描述
[[BatteryPromise]]	`null`	由调用 `getBattery()` 返回的 `Promise`。
[[BatteryManager]]	`null`	通过调用 `getBattery()` 创建的与给定 `Navigator` 关联的 `BatteryManager` 实例。

getBattery() 方法的步骤如下：

如果 this.[[BatteryPromise]] 为 null，则将其设置为一个新的 Promise，位于 this 的相关领域。
如果 this 的相关全局对象的关联的 Document 不允许使用 "battery" 策略控制功能，则拒绝 this.[[BatteryPromise]]，并抛出 "NotAllowedError" DOMException。
否则：
1. 如果 this.[[BatteryManager]] 为 null，则将其设置为在 this 的相关领域中创建的一个新的 BatteryManager。
2. 解析 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，则中止这些步骤。
在全局任务队列中排队一个任务，使用电池状态任务源给定 global 运行以下步骤：
1. 将 batteryManager.slot 设置为 value。
2. 触发一个事件，事件名称为 eventName，目标为 batteryManager。

如果托管设备包含多个电池， BatteryManager 应该暴露电池的统一视图。

[[Charging]] 内部槽必须设置为 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 ? 'charging' : 'not charging'; document.querySelector('#level').textContent = battery.level; document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60; } navigator.getBattery().then(function(battery) { // 初始更新电池状态... 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>

电池状态任务源 §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
当前电池状态信息 §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
无法报告电池状态信息 §6.
更新电池状态并通知 §6.7
用户代理 §2.

[DOM] 定义了以下内容：
- EventTarget 接口
- 触发事件
[ECMASCRIPT] 定义了以下内容：
- 内部槽
[HTML] 定义了以下内容：
- 允许使用
- 关联的文档
- 当前全局对象
- 事件处理程序事件类型
- 事件处理程序
- EventHandler
- Navigator 接口
- 排队全局任务
- 相关全局对象
- 相关领域
- 任务源
- 任务
- Window 接口
[PERMISSIONS-POLICY] 定义了以下内容：
- 'self' （用于默认允许列表）
- 默认允许列表（用于策略控制功能）
- 策略控制功能
[WEBIDL] 定义了以下内容：
- 一个新的 promise
- boolean 类型
- DOMException 接口
- double 类型
- [Exposed] 扩展属性
- new
- NotAllowedError 异常
- Promise 接口
- 拒绝
- 解析
- [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. 权限策略集成

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

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` 属性