《卡片添加至桌面》一、@ohos.batteryInfo使用指南

HarmonyOS ohos.batteryInfo电量信息使用指南摘要本文详细介绍 HarmonyOS 中ohos.batteryInfo模块的使用方法涵盖 API 说明、权限配置、完整代码示例及在应用卡片中的实战应用帮助开发者快速掌握设备电量信息的获取与展示。效果一、模块概述ohos.batteryInfo是 HarmonyOS 提供的基础服务模块属于kit.BasicServicesKit用于获取设备电池的实时状态信息。开发者可以通过该模块读取电池电量、充电状态、电池健康度等关键数据广泛应用于设备信息展示、省电优化、应用卡片等场景。1.1 适用场景设备信息类应用展示当前电量桌面卡片Widget实时显示电池状态低电量预警功能充电状态监控与通知1.2 模块归属属性值模块名ohos.batteryInfoKitkit.BasicServicesKit引入方式import { batteryInfo } from kit.BasicServicesKit二、核心 API 详解2.1 属性列表batteryInfo模块以属性方式暴露电池信息无需异步调用直接读取即可属性名类型说明取值范围batterySOCnumber当前电池电量百分比0 ~ 100chargingStatusBatteryChargeState当前充电状态枚举值healthStatusBatteryHealthStatus电池健康状态枚举值pluggedTypeBatteryPluggedType充电器类型枚举值voltagenumber电池电压mV-batteryTemperaturenumber电池温度0.1℃-batteryTechnologystring电池技术-2.2 枚举类型说明BatteryChargeState充电状态enumBatteryChargeState{UNKNOWN0,// 未知状态ENABLE1,// 充电中DISABLE2,// 未充电FULL4// 已充满}注意枚举名是BatteryChargeState不是BatteryChargeStatus枚举值不含CHARGE_STATE_前缀。BatteryHealthStatus健康状态enumBatteryHealthStatus{HEALTH_STATE_UNKNOWN0,// 未知HEALTH_STATE_GOOD1,// 良好HEALTH_STATE_OVERHEAT2,// 过热HEALTH_STATE_OVERVOLTAGE3,// 过压HEALTH_STATE_COLD4,// 过冷HEALTH_STATE_DEAD5// 故障}BatteryPluggedType充电器类型enumBatteryPluggedType{PLUGGED_TYPE_NONE0,// 未插入充电器PLUGGED_TYPE_AC1,// AC充电器PLUGGED_TYPE_USB2,// USB端口PLUGGED_TYPE_WIRELESS3// 无线充电}三、权限说明batteryInfo模块的属性均为系统级只读信息无需额外申请权限即可使用是开发中最易用的系统 API 之一。四、基础示例获取并展示电量信息4.1 创建项目使用 DevEco Studio 新建一个空 ArkTS 项目选择Empty Ability模板。4.2 编写页面代码在entry/src/main/ets/pages/Index.ets中编写如下代码import{batteryInfo}fromkit.BasicServicesKit;EntryComponentstruct BatteryInfoDemo{StatebatteryLevel:number0;StatechargeStatus:string;StatehealthStatus:string;StatepluggedType:string;aboutToAppear():void{this.refreshBatteryInfo();}refreshBatteryInfo():void{// 直接读取电量百分比this.batteryLevelbatteryInfo.batterySOC;// 读取充电状态并转换为可读文本switch(batteryInfo.chargingStatus){casebatteryInfo.BatteryChargeState.ENABLE:this.chargeStatus充电中;break;casebatteryInfo.BatteryChargeState.DISABLE:this.chargeStatus未充电;break;casebatteryInfo.BatteryChargeState.FULL:this.chargeStatus已充满;break;default:this.chargeStatus未知;}// 读取健康状态switch(batteryInfo.healthStatus){casebatteryInfo.BatteryHealthStatus.HEALTH_STATE_GOOD:this.healthStatus良好;break;casebatteryInfo.BatteryHealthStatus.HEALTH_STATE_OVERHEAT:this.healthStatus过热;break;default:this.healthStatus未知;}// 读取充电器类型switch(batteryInfo.pluggedType){casebatteryInfo.BatteryPluggedType.PLUGGED_TYPE_AC:this.pluggedTypeAC充电器;break;casebatteryInfo.BatteryPluggedType.PLUGGED_TYPE_USB:this.pluggedTypeUSB;break;casebatteryInfo.BatteryPluggedType.PLUGGED_TYPE_WIRELESS:this.pluggedType无线充电;break;default:this.pluggedType未插入充电器;}}// 根据电量返回颜色getBatteryColor():string{if(this.batteryLevel20){return#E84026;// 红色 - 低电量}elseif(this.batteryLevel30){return#FFE229;// 黄色 - 中等电量}return#37DF56;// 绿色 - 充足电量}build(){Column({space:16}){Text(电池信息示例).fontSize(22).fontWeight(FontWeight.Bold)// 电量展示卡片Column({space:12}){Text(当前电量${this.batteryLevel}%).fontSize(28).fontWeight(FontWeight.Bold).fontColor(this.getBatteryColor())Progress({value:this.batteryLevel,total:100,type:ProgressType.Linear}).width(80%).height(16).color(this.getBatteryColor()).backgroundColor(#F0F0F0)Text(充电状态${this.chargeStatus}).fontSize(16).fontColor(#666666)Text(电池健康${this.healthStatus}).fontSize(16).fontColor(#666666)Text(充电器类型${this.pluggedType}).fontSize(16).fontColor(#666666)}.width(90%).padding(24).backgroundColor(Color.White).borderRadius(16).shadow({radius:8,color:#1A000000,offsetY:4})Button(刷新).fontSize(16).width(60%).onClick((){this.refreshBatteryInfo();})}.width(100%).height(100%).justifyContent(FlexAlign.Center).backgroundColor(#F5F5F5)}}4.3 运行效果运行后页面将展示当前电量百分比带颜色区分电量进度条充电状态、电池健康度、充电器类型五、进阶订阅电量变化事件batteryInfo.batterySOC是一个快照值不会自动更新。如果需要实时监听电量变化需要结合commonEventManager订阅BATTERY_CHANGED公共事件。5.1 完整示例import{batteryInfo,BusinessError,commonEventManager}fromkit.BasicServicesKit;EntryComponentstruct BatteryMonitorDemo{StatebatteryLevel:number0;privatesubscriber?:commonEventManager.CommonEventSubscriber;aboutToAppear():void{this.batteryLevelbatteryInfo.batterySOC;this.subscribeBatteryChange();}aboutToDisappear():void{this.unsubscribeBatteryChange();}// 订阅电量变化事件subscribeBatteryChange():void{letsubscribeInfo:commonEventManager.CommonEventSubscribeInfo{events:[usual.event.BATTERY_CHANGED]};commonEventManager.createSubscriber(subscribeInfo,(err:BusinessError,subscriber:commonEventManager.CommonEventSubscriber){if(err){console.error(创建订阅者失败:${err.code},${err.message});return;}this.subscribersubscriber;commonEventManager.subscribe(this.subscriber,(err:BusinessError,data:commonEventManager.CommonEventData){if(err){console.error(订阅事件失败:${err.code},${err.message});return;}// 电量变化时重新获取最新值this.batteryLevelbatteryInfo.batterySOC;console.info(电量已更新:${this.batteryLevel}%);});});}// 取消订阅unsubscribeBatteryChange():void{if(this.subscriber){commonEventManager.unsubscribe(this.subscriber,(err:BusinessError){if(err){console.error(取消订阅失败:${err.code},${err.message});}else{this.subscriberundefined;}});}}build(){Column(){Text(实时电量${this.batteryLevel}%).fontSize(32).fontWeight(FontWeight.Bold)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}5.2 关键要点要点说明事件名usual.event.BATTERY_CHANGED生命周期在aboutToAppear中订阅aboutToDisappear中取消内存管理页面销毁时务必调用unsubscribe释放资源六、在应用卡片中使用电量信息在桌面卡片Widget中展示电量信息时需要注意卡片运行在独立进程中数据通常由主应用通过Preferences传递给FormExtensionAbility再更新到卡片 UI。6.1 数据流示意主应用获取 batteryInfo.batterySOC ↓ 写入 Preferences 持久化存储 ↓ FormExtensionAbility.onAddForm 读取 Preferences ↓ 通过 formBindingData 传递给卡片 UI ↓ 卡片组件通过 LocalStorageProp 展示数据6.2 卡片端关键代码// 卡片组件中展示电量Componentstruct BatteryWidgetCard{LocalStorageProp(batterySOC)batterySOC:number0;build(){Row({space:8}){Text(电量).fontSize(12)Progress({value:this.batterySOC,total:100,type:ProgressType.Linear}).width(60).height(10).color(this.batterySOC20?#E84026:#37DF56)Text(${this.batterySOC}%).fontSize(16).fontWeight(FontWeight.Bold).fontColor(this.batterySOC20?#E84026:#37DF56)}}}七、常见问题与注意事项7.1 获取的电量为 0原因batteryInfo.batterySOC在模拟器上可能返回默认值 0解决使用真机调试模拟器不保证返回真实电量数据7.2 充电状态不准确原因充电状态枚举中UNKNOWN表示未知状态并非“未充电”解决合理处理所有枚举值避免遗漏UNKNOWN7.3 电量数据不会自动更新原因batteryInfo.batterySOC是即时快照值不会触发 UI 刷新解决结合commonEventManager订阅BATTERY_CHANGED事件实现实时更新八、总结知识点内容模块导入import { batteryInfo } from kit.BasicServicesKit获取电量batteryInfo.batterySOC0~100充电状态batteryInfo.chargingStatus实时更新订阅usual.event.BATTERY_CHANGED公共事件权限要求无需额外权限卡片场景通过 Preferences FormExtensionAbility 传递数据掌握ohos.batteryInfo模块后开发者可以轻松实现电量展示、充电监控、低电量预警等功能为后续开发设备信息类应用卡片打下坚实基础。