GreaterWMS 中的 cordova-plugin-battery-status 2.0.3:电量事件插件全解析与版本演进脉络

原创2026-10-14 13:32:19263 阅读
文章标签:后端前端企业应用

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);
    }
}

这段代码体现了两个关键语义:

  1. 充电时不触发低电量/临界电量事件(对应 issue CB-4520):只要 isPlugged 为 true,即使电量跌破阈值也不会触发 low/critical 事件,避免充电过程中误报警。
  2. 使用"上一状态 > 阈值 && 当前状态 <= 阈值"的不等式判定(对应 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 架构演进总结

纵观整个版本史,插件演进呈现出三条清晰脉络:

  1. 阈值判定从原生下沉到 JS 桥接层:早期版本在 iOS 原生层判断 10%/25% 阈值(见 CDVBattery.m 中保留的注释代码),后期统一由 www/battery.js 的 STATUS_LOW = 20 / STATUS_CRITICAL = 5 常量统一判定,保证各平台行为一致;
  2. 平台支持从"广撒网"到"收敛":早期覆盖 Tizen、FirefoxOS、Ubuntu、Windows Phone 8/8.1 等大量平台,2.0.0 起移除废弃平台,最终稳定在 iOS / Android / Windows / Browser 四端;
  3. 从功能开发转向工程化与质量治理:后期版本的重心明显转向 CI 配置、类型声明、代码规范(eslint 替换 jshint)、打包体积控制与文档维护。

九、在 GreaterWMS 中集成与注意事项

GreaterWMS 的移动扫码端基于 Quasar + Cordova 构建,前端代码位于 app/src-cordova(另有 templates/src 为模板工程)。集成该插件时应注意以下几点:

  1. 监听器按需注册:利用插件"首个监听器注册时才启动原生监听"的机制,仅在进入需要电量信息的页面时注册事件,离开时用 window.removeEventListener 注销,避免 Android 端长时间驻留广播接收器导致额外耗电。
  2. deviceready 之后注册:所有事件监听必须在 deviceready 之后进行,否则事件通道尚未就绪。
  3. WebView reload 场景:若应用中存在 window.location.reload() 逻辑,2.0.2 之前的版本在 Android 上会出现监听不恢复的问题,2.0.3 已修复;升级到当前版本即可规避。
  4. TypeScript 提示:在 Quasar 的 TS 代码中,可以直接利用 BatteryStatusEvent 类型获得 level / isPlugged 的类型提示。
  5. 充电状态下不要依赖 low/critical 事件:插件约定充电时不会触发低电量/临界电量事件,业务告警逻辑需自行叠加 isPlugged 判断或改用 batterystatus 事件自行计算。

十、结语

cordova-plugin-battery-status 虽然是一个体量不大的 Cordova 插件,但从 RELEASENOTES.md 的版本记录中可以清晰看到它围绕"平台覆盖、阈值语义、生命周期管理、工程化质量"四个维度的持续演进。通过结合 www/battery.js、BatteryListener.java、CDVBattery.m 与 tests/tests.js 的源码级分析,我们不仅理解了 API 用法,更掌握了其"按需启停原生监听 + JS 统一阈值判定"的核心设计——这正是把电量事件安全、省电地集成进 GreaterWMS 移动仓储扫描应用的关键所在。

登录后查看全文
GreaterWMS