Flutter 鸿蒙实战用 battery_plus 三方库给应用加上电池状态监测与充电动效Flutter 社区地址: https://atomgit.com/CPF-Flutter/flutter_fluttergithub三方库地址https://github.com/fluttercommunity/plus_plugins/tree/main/packages/battery_plus/battery_pluspub地址https://pub.dev/packages/battery_plus鸿蒙适配版https://atomgit.com/CPF-Flutter/flutter_plus_plugins我的工程适配地址https://atomgit.com/weixin_52908342/battery_demo库版本battery_plus 4.1.0CPF-Flutter 鸿蒙适配版commit9571de2验证环境Flutter 鸿蒙 SDK 3.44.9oh-3.44.9-devDevEco Studio 26.0.0.821 设备DevEco 模拟器 Pura X View HarmonyOS 7.0.0.106API 26应用里的电池状态提示、电量告警、充电动效几乎是移动 App 标配。battery_plus是 Flutter 生态里用得最多的电池状态插件pub.dev 月下载百万级CPF-Flutter 社区已在flutter_plus_pluginsmonorepo 里完成鸿蒙适配。本文介绍它在 OpenHarmony 上的引入方式、4 个接口的逐个调用与真实运行效果并附 FAQ 与问题反馈流程。一、环境搭建本章不重复展开直接引用官方文档Flutter OH 开发环境搭建指导。完成后用flutter doctor -v验证Flutter与HarmonyOS toolchain两项均为[√]即可。本文实际使用的版本Flutter OHoh-3.44.9-devcommit77e0c8d13b、DevEco Studio26.0.0.821、HarmonyOS SDK API 26。二、应用背景2.1 当前的应用场景与痛点儿童手表 / 老人手环类 App需要根据电池余量动态降低刷新率、上传频率导航 / 出行类电量不足时提示用户充电自动降级 UI 亮度共享设备类实时上报设备电量给云端视频 / 游戏类低电量时关闭高耗电特效痛点在于Flutter 官方battery_plus只覆盖 Android/iOS/Web/Windows/macOS/Linux鸿蒙侧此前一片空白——应用迁到 OpenHarmony 后电池相关功能直接失效。2.2 为什么需要这个库自己写插件需要处理 ArkTS 通道、系统 API 差异、事件流生命周期成本高battery_plus的鸿蒙适配版由 CPF-Flutter 社区维护一行 git 依赖即可获得跨端一致的 API。2.3 解决什么问题一句话总结让 Flutter 应用在鸿蒙上以与 Android/iOS 完全相同的 API 读取电池状态。具体提供当前电量百分比0-100电池状态充电中 / 放电中 / 已充满 / 未知省电模式查询电池状态变化事件流免轮询、自动推送三、功能介绍功能API说明适用场景电量查询batteryLevel返回Futureint0-100电量展示、低电告警状态查询batteryState返回FutureBatteryState枚举充电动效、充电提示音省电模式isInBatterySaveMode返回Futurebool省电模式下降低刷新率状态变化流onBatteryStateChangedStreamBatteryState订阅后自动推送实时监听插拔充电线四、使用方法4.1 在应用中引入三方库AtomGit 链接方式dependencies:flutter:sdk:flutterbattery_plus:git:url:https://atomgit.com/CPF-Flutter/flutter_plus_plugins.gitref:9571de239933ab2893dbd49037e128135b050a7cpath:packages/battery_plus/battery_plus三个注意点path必须写到双层目录packages/battery_plus/battery_plusmonorepo 里插件在嵌套子目录写成packages/battery_plus会 404ref建议写 commit hash本文用9571de2tag/分支名可能漂移URL 用 AtomGit 而非 pub.dev——pub 上的battery_plus没有 ohos 平台实现必须走 CPF-Flutter 的适配仓库执行flutter pub get后即可import package:battery_plus/battery_plus.dart;。4.2 调用接口实现功能4.2.1 Battery()获取单例finalbatteryBattery();Battery是单例工厂第二次Battery()会复用同一实例。不要重复创建否则事件流订阅会被覆盖。4.2.2 batteryLevel电量查询功能说明异步 getter返回当前电量百分比0-100 的整数。finallevelawaitbattery.batteryLevel;print(当前电量$level%);运行效果demo 首屏大字 100% 即batteryLevel返回值电量充足时显示绿色。下方副标题标注了对应的 API 名。4.2.3 batteryState状态查询功能说明异步 getter返回BatteryState枚举charging/discharging/full/unknown。finalstateawaitbattery.batteryState;switch(state){caseBatteryState.charging:print(充电中);caseBatteryState.discharging:print(放电中);caseBatteryState.full:print(已充满);default:print(未知);}运行效果通过 DevEco 模拟器命令Emulator -instance Pura X View -battery 65改变电量后刷新大字变为 65%事件流日志累积了多次调用记录。模拟器无真实电池硬件batteryState显示unknown属正常行为。4.2.4 isInBatterySaveMode省电模式查询功能说明异步 getter返回设备是否处于省电模式。注意方法名是isInBatterySaveMode不是isInPowerSaveMode早期文档有此拼写错误。finalpowerSaveawaitbattery.isInBatterySaveMode;if(powerSave){// 降级关闭高刷、减少上报频率}运行效果右侧卡片isInBatterySaveMode()返回false省电模式未开启。鸿蒙适配版当前固定返回 false见 5.1 Q5。4.2.5 onBatteryStateChanged状态变化事件流功能说明StreamBatteryState订阅一次持续推送免去手动轮询。必须在dispose()里 cancel防止泄漏。StreamSubscriptionBatteryState?_sub;overridevoidinitState(){super.initState();_subbattery.onBatteryStateChanged.listen((s){print(电池状态变化${s.name});});}overridevoiddispose(){_sub?.cancel();super.dispose();}运行效果通过模拟器命令Emulator -batteryStatus 1切换到充电态触发真实事件底部暗色事件流卡新增一行[00:54:45] onBatteryStateChanged → charging——无需任何手动刷新事件自动推送到 Dart 层顶部状态栏电池图标同步出现闪电符号。补充battery_plus 4.x没有onBatteryLevelChanged电量百分比变化流如需细粒度电量监控请自行Timer.periodic轮询batteryLevel。4.3 完整示例代码可直接复制运行的main.dart含 4 个接口的全调用 事件流日志 UIimportdart:async;importpackage:battery_plus/battery_plus.dart;importpackage:flutter/material.dart;voidmain()runApp(constBatteryApp());classBatteryAppextendsStatelessWidget{constBatteryApp({super.key});overrideWidgetbuild(BuildContextcontext){returnMaterialApp(title:battery_plus · OpenHarmony,theme:ThemeData(colorSchemeSeed:constColor(0xFF2EA043)),home:constBatteryPage(),);}}classBatteryPageextendsStatefulWidget{constBatteryPage({super.key});overrideStateBatteryPagecreateState()_BatteryPageState();}class_BatteryPageStateextendsStateBatteryPage{final_batteryBattery();int _level-1;BatteryState_stateBatteryState.unknown;bool _powerSavefalse;finalListString_events[];StreamSubscriptionBatteryState?_stateSub;overridevoidinitState(){super.initState();_refresh();_stateSub_battery.onBatteryStateChanged.listen((s){_log(onBatteryStateChanged →${s.name});});}overridevoiddispose(){_stateSub?.cancel();super.dispose();}void_log(Stringmsg){finalnowDateTime.now();setState((){_events.insert(0,[${now.hour.toString().padLeft(2, 0)}:${now.minute.toString().padLeft(2, 0)}:${now.second.toString().padLeft(2, 0)}]$msg);if(_events.length30)_events.removeLast();});}Futurevoid_refresh()async{finallevelawait_battery.batteryLevel;finalstateawait_battery.batteryState;bool powerSavefalse;try{powerSaveawait_battery.isInBatterySaveMode;}catch(_){powerSavefalse;}if(!mounted)return;setState((){_levellevel;_statestate;_powerSavepowerSave;});_log(手动刷新电量$level%状态${state.name});}overrideWidgetbuild(BuildContextcontext){returnScaffold(appBar:AppBar(title:constText(battery_plus · OpenHarmony)),body:ListView(padding:constEdgeInsets.all(16),children:[Text($_level%,style:constTextStyle(fontSize:64)),Text(状态${_state.name}| 省电$_powerSave),FilledButton(onPressed:_refresh,child:constText(手动刷新)),..._events.map(Text.new),],),);}}签名与构建活动要求示例工程含signingConfig: defaultflutter create--platformsohos.# 生成 ohos 工程目录# 在 ohos/build-profile.json5 填入签名材料DevEco 自动生成于 ~/.ohos/config/flutter build hap--debughdcinstallbuild/ohos/hap/entry-default-signed.hap无真机时DevEco 模拟器可用命令脚本化触发电池状态验证全部接口Emulator-instance模拟器名-battery18# 低电量demo 变红Emulator-instance模拟器名-battery65# 中等电量绿色Emulator-instance模拟器名-batteryStatus1# 触发 charging 事件流五、FAQ5.1 常见问题Q1编译报The getter onBatteryLevelChanged isnt definedbattery_plus 4.x 只有onBatteryStateChanged状态流没有电量百分比流。用Timer.periodic轮询batteryLevel替代。Q2编译报The getter isInPowerSaveMode isnt defined拼写错误正确方法是isInBatterySaveMode。Q3batteryState在模拟器上一直返回unknown正常现象——模拟器无真实电池硬件。用Emulator -batteryStatus 0|1强制切换状态可触发事件流真机上会返回真实状态。Q4flutter pub get解析失败/找不到包检查path: packages/battery_plus/battery_plus是否写完整双层目录镜像用export PUB_HOSTED_URLhttps://pub.flutter-io.cn。Q5isInBatterySaveMode始终返回 false鸿蒙适配版当前实现固定返回 false省电模式真实监听尚未实现属于已知限制。可关注上游仓库 issue 跟踪进度。5.2 库本身存在问题如何提交 Issue仓库地址https://atomgit.com/CPF-Flutter/flutter_plus_plugins打开仓库 → Issues → 新建 Issue标题[Bug] 现象简述如[Bug] isInBatterySaveMode always returns false on OHOS正文必备复现步骤、期望行为、实际行为、设备与 SDK 版本flutter --versionhdc shell param get const.product.software.version、最小复现代码附上 demo 截图 / hilog 日志hdc shell hilog -t OHOSAbility -x5.3 能自己解决如何提交 PRFork仓库到自己账号AtomGit 仓库页右上角 Fork建分支git checkout -b fix/battery-save-mode修改并提交gitaddpackages/battery_plus/gitcommit-mfix(battery_plus): read isInBatterySaveMode from PowerManager on OHOSgitpush-uorigin fix/battery-save-mode发 PRAtomGit 上 从你的账号:fix/battery-save-mode→CPF-Flutter:master描述中附鸿蒙设备验证截图修改后isInBatterySaveMode正确返回 true 的效果六、其他内容battery_plus4.1.0 鸿蒙适配版开箱即用一行 git 依赖 四个 API 即可覆盖电量查询、状态查询、省电模式、状态监听全部场景。配合 DevEco 模拟器的电池模拟命令无需真机也能完整验证每个接口。已知限制是isInBatterySaveMode固定返回 false可通过社区 Issue/PR 推动。相比自己从零写 ArkTS 插件直接复用 CPF-Flutter 适配成果是明显更优的选择。