GreaterWMS 中的 cordova-plugin-battery-status 2.0.3:电量事件插件全解析与版本演进脉络
GreaterWMS 中的 cordova-plugin-battery-status 2.0.3:电量事件插件全解析与版本演进脉络
本文以 GreaterWMS 仓库 app/src-cordova/plugins/cordova-plugin-battery-status 目录下的 RELEASENOTES.md 为主线,结合插件的 JavaScript 桥接层、Android/iOS/Windows/Browser 四端原生实现、自动化测试与类型声明,系统讲解 cordova-plugin-battery-status 2.0.3 的 API 用法、跨平台实现原理与历史版本演进脉络。读完本文,你将能够在 Cordova 项目中正确接入电量监听、理解低电量/临界电量的触发边界与已知坑位,并掌握如何把该插件嵌入 GreaterWMS 这样以 Quasar + Cordova 构建的移动仓储扫描应用中。
一、插件定位:一个实现 W3C Battery Status Events API 的 Cordova 插件
cordova-plugin-battery-status 为 Cordova 应用提供了旧版 W3C Battery Status Events API 的跨平台实现。它在 window 对象上暴露三个事件:
batterystatus:电量百分比变化至少 1% 时触发,或设备插入/拔出电源时触发;batterylow:电量到达低电量阈值时触发,该阈值由设备决定;batterycritical:电量到达临界电量阈值时触发,同样由设备决定。
在 GreaterWMS 中,这个插件被安装在 app/src-cordova(Quasar 的 Cordova 工程目录)下,作为扫码终端 App 的依赖之一。从 app/src-cordova/plugins/android.json 可以看到它已随 org.greaterwms.scanner.app 这一包名被打包进 Android 工程,属于顶层插件(app/src-cordova/plugins/fetch.json 中 is_top_level: true),这意味着它并非被其他插件间接引入,而是项目直接依赖的独立插件。
1.1 安装方式
官方推荐的安装命令(在 Cordova 工程根目录执行):
cordova plugin add cordova-plugin-battery-status
GreaterWMS 仓库采用的是插件源码预置方式:插件完整源码位于 app/src-cordova/plugins/cordova-plugin-battery-status,版本锁定为 2.0.3,与 plugin.xml 中 version="2.0.3" 一致。
1.2 状态对象(Status object)
三个事件回调收到的状态对象包含两个属性:
| 属性 | 类型 | 说明 |
|---|---|---|
level |
Number | 电池电量百分比,取值范围 0–100 |
isPlugged |
Boolean | 设备当前是否连接电源 |
1.3 支持的平台
| 平台 | 支持情况 | 底层实现 |
|---|---|---|
| iOS | 支持 | CDVBattery.m |
| Android | 支持 | BatteryListener.java |
| Windows | 支持(Win 10 使用 PowerManager) | BatteryProxy.js + BatteryStatus.winmd |
| Browser | 支持(Chrome、Firefox、Opera) | BatteryProxy.js |
从 package.json 的 cordova.platforms 字段同样可以看到这四个平台:android、ios、browser、windows。
二、事件 API 与实战用法
应用必须在 deviceready 事件触发后,才能通过 window.addEventListener 注册上述三个事件的监听器。以下是基于插件 README.md 的完整示例。
2.1 batterystatus 事件
电量变化至少 1% 或插拔电源时触发:
window.addEventListener("batterystatus", onBatteryStatus, false);
function onBatteryStatus(status) {
console.log("Level: " + status.level + " isPlugged: " + status.isPlugged);
}
2.2 batterylow 事件
电量到达设备定义的低电量阈值时触发:
window.addEventListener("batterylow", onBatteryLow, false);
function onBatteryLow(status) {
alert("Battery Level Low " + status.level + "%");
}
2.3 batterycritical 事件
电量到达设备定义的临界电量阈值时触发:
window.addEventListener("batterycritical", onBatteryCritical, false);
function onBatteryCritical(status) {
alert("Battery Level Critical " + status.level + "%\nRecharge Soon!");
}
2.4 类型声明:TypeScript 项目中的使用方式
该插件从 1.2.3 版本开始引入 DefinitelyTyped 类型声明,2.0.3 版本的声明文件位于 types/index.d.ts。它定义了 batteryEvent 联合类型('batterystatus' | 'batterycritical' | 'batterylow'),并在 Window 接口上扩展了 addEventListener / removeEventListener 的重载,同时定义 BatteryStatusEvent 接口:
interface BatteryStatusEvent extends Event {
level: number; // 电量百分比(0-100)
isPlugged: boolean; // 是否连接电源
}
因此在使用 TypeScript 的 Quasar 项目中,可以直接获得事件回调参数的类型提示与编译期校验。package.json 中 "types": "./types/index.d.ts" 字段也确保 npm 解析类型时能够找到该声明文件。
三、JavaScript 桥接层:事件分发与阈值判定的核心逻辑
插件前端逻辑集中在 www/battery.js,它定义了低电量与临界电量的判定阈值:
var STATUS_CRITICAL = 5;
var STATUS_LOW = 20;
即:电量 ≤ 5% 触发 batterycritical,电量 ≤ 20% 触发 batterylow。插件在加载时通过 cordova.addWindowEventHandler 为三个事件创建 window 级事件通道,并按 plugin.xml 的声明将其 clobbers 到 navigator.battery。
3.1 按需启停原生监听,节省设备电量
Battery.onHasSubscribersChange 是插件最值得关注的省电设计:每当监听器数量发生变化,它会统计三个事件通道上的处理器总数:
- 第一个监听器注册时(
numHandlers === 1 && handlers() === 1),才调用exec(..., 'Battery', 'start', [])启动原生电量监听; - 所有监听器都被移除时(
handlers() === 0),调用exec(..., 'Battery', 'stop', [])停止原生监听。
这一设计在代码注释中明确写到:"Keep track of how many handlers we have so we can start and stop the native battery listener appropriately (and hopefully save on battery life!)"。也就是说,只有业务层真正注册了电量事件监听器,原生广播接收器才会被激活,避免无谓的电量消耗。
3.2 阈值触发的边界语义(CB-4519 / CB-4520)
Battery.prototype._status 负责处理每次原生回调,其判定逻辑对"穿越阈值"这一场景做了专门处理:
if (!info.isPlugged) { // do not fire low/critical if we are charging. issue: CB-4520
if (battery._level > STATUS_CRITICAL && info.level <= STATUS_CRITICAL) {
cordova.fireWindowEvent('batterycritical', info);
} else if (battery._level > STATUS_LOW && info.level <= STATUS_LOW) {
cordova.fireWindowEvent('batterylow', info);
}
}
这段代码体现了两个关键语义:
- 充电时不触发低电量/临界电量事件(对应 issue CB-4520):只要
isPlugged为 true,即使电量跌破阈值也不会触发 low/critical 事件,避免充电过程中误报警。 - 使用"上一状态 > 阈值 && 当前状态 <= 阈值"的不等式判定(对应 issue CB-4519):这可以捕获从阈值上方直接跳到下方的场景(如 21% → 19%),而不是仅仅检查当前值是否恰好等于阈值,从而避免漏报。反向(电量回升,如 19% → 20%)则不会触发。
另外还有一个细节:当 info.level === null 且上一状态非 null 时直接 return,这是"停止原生监听时最后一次回调"的特殊情况处理,防止在卸载监听时误触发事件。
四、Android 实现:BroadcastReceiver 驱动的电量广播
Android 端实现位于 src/android/BatteryListener.java,类名 BatteryListener,包名 org.apache.cordova.batterystatus,通过 plugin.xml 注册到 config.xml 的 Battery feature 中。
4.1 start / stop 生命周期
start:注册一个BroadcastReceiver,通过IntentFilter.addAction(Intent.ACTION_BATTERY_CHANGED)监听系统的电量变化广播;随后返回NO_RESULT+setKeepCallback(true)的 PluginResult,表示回调会持续驻留(不释放),等待后续电量事件推送。代码中特意使用webView.getContext()而非 Activity 的 context 来注册接收器——这正是 RELEASENOTES 中 0.2.12 版本(CB-7976)所修复的问题,可以避免与 Activity 生命周期耦合导致的泄漏风险。stop:注销接收器,并向 JS 侧发送一个空的 JSON 对象(sendUpdate(new JSONObject(), false))释放驻留回调。onDestroy/onReset:均会调用removeBatteryListener()注销接收器,防止 Activity 销毁或 WebView 重置后出现泄漏。
4.2 电量数据的提取
getBatteryInfo(Intent) 从系统广播中读取两个 extra:
obj.put("level", batteryIntent.getIntExtra(android.os.BatteryManager.EXTRA_LEVEL, 0));
obj.put("isPlugged", batteryIntent.getIntExtra(android.os.BatteryManager.EXTRA_PLUGGED, -1) > 0 ? true : false);
EXTRA_LEVEL:当前电量数值;EXTRA_PLUGGED:充电状态,大于 0 视为已连接电源。
4.3 Android 平台的注意事项(Quirk)
插件 README 明确给出警告:Android 实现是"贪婪"的,长时间使用会加速耗电("the Android implementation is greedy and prolonged use will drain the device's battery")。原因是系统会在电量状态变化时频繁发送 ACTION_BATTERY_CHANGED 广播(该广播本身是粘性广播,任何时刻注册都能立即收到最新状态)。因此在扫码枪、手持终端这类以 Android 为主的 GreaterWMS 移动设备上,应谨慎设计监听器的生命周期,尽量在需要时才注册、用完即注销,以利用上文提到的按需启停机制。
五、iOS 实现:UIDevice 电量监控与系统通知
iOS 端实现位于 src/ios/CDVBattery.m,对应 CDVBattery.h。
5.1 start / stop 与系统通知
start:先记录self.callbackId,若batteryMonitoringEnabled尚未开启,则调用[[UIDevice currentDevice] setBatteryMonitoringEnabled:YES]开启系统电量监控,并监听两个系统通知:UIDeviceBatteryStateDidChangeNotification(充电状态变化)UIDeviceBatteryLevelDidChangeNotification(电量变化)
stop:先以keepCallback = NO回传最后一次电量状态以清理 JS 侧驻留回调,随后关闭监控、移除通知观察者。pluginInitialize将初始状态置为UIDeviceBatteryStateUnknown、level = -1.0(未知状态);onReset与dealloc都会调用stop清理资源。
5.2 电平归一化与未知状态处理
getBatteryStatus 中有一个值得注意的换算逻辑:iOS 的 UIDevice.batteryLevel 返回 0.0–1.0 的小数,插件将其乘以 100 转为百分比后传给 JS 侧(currentLevel * 100)。同时遵循 W3C 规范:当状态为 UIDeviceBatteryStateUnknown 或电平为 -1.0 时,level 字段置为 NSNull(对应 JS 侧 null),表示电量未知——这也呼应了 JS 桥接层中"level 为 null 时不触发事件"的特殊分支。
值得注意的是,CDVBattery.m 中保留了被注释掉的旧版 updateBatteryLevel: 实现(注释代码块),其中包含历史上对 10%/25% 阈值的判定逻辑,但在 2.x 版本中事件类型判定已统一收敛到 JS 桥接层完成,原生层只负责上报原始电平与插电状态。这也是插件架构演进的体现:阈值判定从原生层迁移到 JS 层,使各平台行为保持一致。
六、Windows 与 Browser 实现:代理式桥接
6.1 Windows(Win 10)实现
src/windows/BatteryProxy.js 包含两套分支:
- 当存在
Windows.System.Power.PowerManager(Windows 10 桌面/移动)时,注册remainingchargepercentchanged与powersupplystatuschanged两个事件,通过PowerManager.remainingChargePercent与PowerManager.powerSupplyStatus计算level与isPlugged。RELEASENOTES 中 1.2.1 版本(CB-8929)"Use PowerManager to get battery state on Win 10" 指的就是这条路径。 - 当不存在 PowerManager(Windows Phone 8/8.1 等旧平台)时,通过
BatteryStatus.winmd原生组件轮询电量变化事件,并且仅在WinJS.Utilities.isPhone为 true 时工作,桌面/平板设备会直接fail('The operation is not supported on Windows Desktop devices.')。
测试代码 tests/tests.js 中通过 hasPowerManagerAPI 判断是否具备相应 API,不具备时将这些用例标记为 pending。
6.2 Browser 实现
src/browser/BatteryProxy.js 利用浏览器原生 navigator.getBattery()(Battery Status API),订阅 levelchange 与 chargingchange 事件;若浏览器不支持该 API,则回退到旧的 navigator.battery 符号,再不行则 fail('Not supported')。回调中通过 w3cBattery.level * 100 将 0–1 的小数换算为百分比。这对应 RELEASENOTES 中 1.1.0 版本(CB-7953)"Add cordova-plugin-battery-status support for browser platform" 的成果,也是该插件能在 Chrome、Firefox、Opera 中工作的原因。
七、测试验证:阈值边界语义的自动化保障
插件自带的自动化测试位于 tests/tests.js(Jasmine 框架),直接调用 navigator.battery._status(...) 模拟原生上报,精确验证了 JS 桥接层的阈值逻辑:
| 测试用例 | 场景 | 预期 |
|---|---|---|
| battery.spec.2 | 上报 level=30 | batterystatus 触发 |
| battery.spec.3 | 30 → 20 | batterylow 触发 |
| battery.spec.3.1 | 30 → 19 | batterylow 触发(跨阈值下降) |
| battery.spec.3.2 | 5 → 20(电量回升) | batterylow 不触发 |
| battery.spec.3.3 | 21 → 20 但正在充电 | batterylow 不触发(CB-4520) |
| battery.spec.4 | 19 → 5 | batterycritical 触发 |
| battery.spec.4.1 | 19 → 4 | batterycritical 触发 |
| battery.spec.4.2 | 100 → 4 | batterycritical 触发(跨阈值下降) |
| battery.spec.4.3 | 4 → 5(电量回升) | batterycritical 不触发 |
| battery.spec.4.4 | 6 → 5 但正在充电 | batterycritical 不触发(CB-4520) |
这些用例与 RELEASENOTES 中 0.2.9 版本记录的 issue 一一对应:CB-4519/CB-4520 修复了"电量从 21 降到 19 时不触发、从 19 升到 20 时反而触发"的错误行为,以及充电状态下误触发 low/critical 的问题。同时,0.2.9 还新增了"先测 batterycritical 再测 batterylow"的顺序约束(CB-6721),避免两个事件因判定顺序产生干扰。
除此之外,tests/tests.js 还提供了手动测试页面(defineManualTests),展示 Level / Plugged / Low / Critical 四个状态值的实时刷新,方便在真机上人工验证插件的监听、解绑与阈值行为。
八、版本演进脉络:从 0.2.3 到 2.0.3
RELEASENOTES.md 完整记录了从 0.2.3(2013 年)到 2.0.3(2019 年)的演进历史,可以梳理出几条清晰的主线:
8.1 平台支持的时间线
| 版本 | 时间 | 平台相关变更 |
|---|---|---|
| 0.2.3 | 2013-09 | 插件 id 从 org.apache.cordova.core.battery-status 更名为 org.apache.cordova.battery-status |
| 0.2.5 | 2013-12 | 增加 WP8 电量 level 支持、添加 ubuntu 平台、亚马逊平台更名为 amazon-fireos |
| 0.2.7 | 2014-02 | 增加 Tizen 平台 |
| 0.2.9 | 2014-06 | 增加 firefoxos 平台支持 |
| 0.2.10 | 2014-08 | 移植 Battery-status 手动与自动化测试 |
| 0.2.12 | 2014-12 | Android 改用 webView context 注册广播接收器(CB-7976) |
| 1.0.0 | 2015-04 | 主版本号提升;增加 Windows Phone 8.1 支持(CB-7971);iOS 移除 initWithWebView 方法以兼容 4.0.x(CB-8659);增加 Android/FireOS 耗电警告 |
| 1.1.0 | 2015-06 | 增加 Browser 平台支持(CB-7953) |
| 1.2.1 | 2016-12 | Windows 10 改用 PowerManager 获取电量(CB-8929);修复 iOS 失败测试(CB-8929) |
| 1.2.3 | 2017-02 | 从 DefinitelyTyped 引入插件类型声明 |
| 2.0.0 | 2017-12 | 移除废弃平台(CB-13667) |
| 2.0.2 | 2018-04 | Android 修复 window.location.reload() 后电量监听不重新初始化的问题(CB-10645) |
| 2.0.3 | 2019-06 | 更新 typings(CB-72);移除 Node.js v4 支持(CB-73);强制 LF 行尾、清理 npm 包内容、更新 CI 配置 |
8.2 值得关注的几个版本细节
- 1.0.0 的耗电警告:从该版本开始,官方在 Android 平台说明中加入了"长时间使用会耗尽设备电量"的警告,提醒开发者不要常驻监听电量广播。
- 2.0.2 的 reload 修复(CB-10645):Android 上
window.location.reload()之后电量处理器不会重新初始化。修复策略是"不再抛出错误,而是移除旧的状态处理器并重新初始化",保证 H5 页面刷新(如 GreaterWMS 扫描 App 中 SPA 路由重载)后电量监听仍能正常工作。 - 2.0.3 的工程化收尾:新增
.gitattributes强制 LF 行尾(避免 Windows 下 CRLF 引起的差异)、新增.npmignore精简 npm 包、更新 plugin.xml 中的仓库与 issue 链接、更新 typings、并在 CI 中引入新的 paramedic 配置与 android-27 SDK。此外,该版本明确放弃 Node.js v4 支持(CB-73),意味着构建环境需要更新版本的 Node。
8.3 架构演进总结
纵观整个版本史,插件演进呈现出三条清晰脉络:
- 阈值判定从原生下沉到 JS 桥接层:早期版本在 iOS 原生层判断 10%/25% 阈值(见 CDVBattery.m 中保留的注释代码),后期统一由 www/battery.js 的
STATUS_LOW = 20/STATUS_CRITICAL = 5常量统一判定,保证各平台行为一致; - 平台支持从"广撒网"到"收敛":早期覆盖 Tizen、FirefoxOS、Ubuntu、Windows Phone 8/8.1 等大量平台,2.0.0 起移除废弃平台,最终稳定在 iOS / Android / Windows / Browser 四端;
- 从功能开发转向工程化与质量治理:后期版本的重心明显转向 CI 配置、类型声明、代码规范(eslint 替换 jshint)、打包体积控制与文档维护。
九、在 GreaterWMS 中集成与注意事项
GreaterWMS 的移动扫码端基于 Quasar + Cordova 构建,前端代码位于 app/src-cordova(另有 templates/src 为模板工程)。集成该插件时应注意以下几点:
- 监听器按需注册:利用插件"首个监听器注册时才启动原生监听"的机制,仅在进入需要电量信息的页面时注册事件,离开时用
window.removeEventListener注销,避免 Android 端长时间驻留广播接收器导致额外耗电。 - deviceready 之后注册:所有事件监听必须在
deviceready之后进行,否则事件通道尚未就绪。 - WebView reload 场景:若应用中存在
window.location.reload()逻辑,2.0.2 之前的版本在 Android 上会出现监听不恢复的问题,2.0.3 已修复;升级到当前版本即可规避。 - TypeScript 提示:在 Quasar 的 TS 代码中,可以直接利用
BatteryStatusEvent类型获得level/isPlugged的类型提示。 - 充电状态下不要依赖 low/critical 事件:插件约定充电时不会触发低电量/临界电量事件,业务告警逻辑需自行叠加
isPlugged判断或改用batterystatus事件自行计算。
十、结语
cordova-plugin-battery-status 虽然是一个体量不大的 Cordova 插件,但从 RELEASENOTES.md 的版本记录中可以清晰看到它围绕"平台覆盖、阈值语义、生命周期管理、工程化质量"四个维度的持续演进。通过结合 www/battery.js、BatteryListener.java、CDVBattery.m 与 tests/tests.js 的源码级分析,我们不仅理解了 API 用法,更掌握了其"按需启停原生监听 + JS 统一阈值判定"的核心设计——这正是把电量事件安全、省电地集成进 GreaterWMS 移动仓储扫描应用的关键所在。