HarmonyOS @ohos.batteryInfo（电量信息）使用指南

摘要：本文详细介绍 HarmonyOS 中 @ohos.batteryInfo 模块的使用方法，涵盖 API 说明、权限配置、完整代码示例及在应用卡片中的实战应用，帮助开发者快速掌握设备电量信息的获取与展示。

效果

一、模块概述

@ohos.batteryInfo 是 HarmonyOS 提供的基础服务模块，属于 @kit.BasicServicesKit，用于获取设备电池的实时状态信息。开发者可以通过该模块读取电池电量、充电状态、电池健康度等关键数据，广泛应用于设备信息展示、省电优化、应用卡片等场景。

1.1 适用场景

  • 设备信息类应用展示当前电量
  • 桌面卡片（Widget）实时显示电池状态
  • 低电量预警功能
  • 充电状态监控与通知

1.2 模块归属

属性 值
模块名 @ohos.batteryInfo
Kit @kit.BasicServicesKit
引入方式 import { batteryInfo } from '@kit.BasicServicesKit'

二、核心 API 详解

2.1 属性列表

batteryInfo 模块以属性方式暴露电池信息，无需异步调用，直接读取即可：

属性名 类型 说明 取值范围
batterySOC number 当前电池电量百分比 0 ~ 100
chargingStatus BatteryChargeState 当前充电状态 枚举值
healthStatus BatteryHealthStatus 电池健康状态 枚举值
pluggedType BatteryPluggedType 充电器类型 枚举值
voltage number 电池电压（mV） -
batteryTemperature number 电池温度（0.1℃） -
batteryTechnology string 电池技术 -

2.2 枚举类型说明

BatteryChargeState（充电状态）

enum BatteryChargeState {
  UNKNOWN = 0,     // 未知状态
  ENABLE = 1,      // 充电中
  DISABLE = 2,     // 未充电
  FULL = 4         // 已充满
}

注意：枚举名是 BatteryChargeState（不是 BatteryChargeStatus），枚举值不含 CHARGE_STATE_ 前缀。

BatteryHealthStatus（健康状态）

enum BatteryHealthStatus {
  HEALTH_STATE_UNKNOWN = 0,      // 未知
  HEALTH_STATE_GOOD = 1,         // 良好
  HEALTH_STATE_OVERHEAT = 2,     // 过热
  HEALTH_STATE_OVERVOLTAGE = 3,  // 过压
  HEALTH_STATE_COLD = 4,         // 过冷
  HEALTH_STATE_DEAD = 5          // 故障
}

BatteryPluggedType（充电器类型）

enum BatteryPluggedType {
  PLUGGED_TYPE_NONE = 0,         // 未插入充电器
  PLUGGED_TYPE_AC = 1,           // AC充电器
  PLUGGED_TYPE_USB = 2,          // USB端口
  PLUGGED_TYPE_WIRELESS = 3      // 无线充电
}

三、权限说明

batteryInfo 模块的属性均为系统级只读信息，无需额外申请权限即可使用，是开发中最易用的系统 API 之一。

四、基础示例：获取并展示电量信息

4.1 创建项目

使用 DevEco Studio 新建一个空 ArkTS 项目，选择 Empty Ability 模板。

4.2 编写页面代码

在 entry/src/main/ets/pages/Index.ets 中编写如下代码：

import { batteryInfo } from '@kit.BasicServicesKit';

@Entry
@Component
struct BatteryInfoDemo {
  @State batteryLevel: number = 0;
  @State chargeStatus: string = '';
  @State healthStatus: string = '';
  @State pluggedType: string = '';

  aboutToAppear(): void {
    this.refreshBatteryInfo();
  }

  refreshBatteryInfo(): void {
    // 直接读取电量百分比
    this.batteryLevel = batteryInfo.batterySOC;

    // 读取充电状态并转换为可读文本
    switch (batteryInfo.chargingStatus) {
      case batteryInfo.BatteryChargeState.ENABLE:
        this.chargeStatus = '充电中';
        break;
      case batteryInfo.BatteryChargeState.DISABLE:
        this.chargeStatus = '未充电';
        break;
      case batteryInfo.BatteryChargeState.FULL:
        this.chargeStatus = '已充满';
        break;
      default:
        this.chargeStatus = '未知';
    }

    // 读取健康状态
    switch (batteryInfo.healthStatus) {
      case batteryInfo.BatteryHealthStatus.HEALTH_STATE_GOOD:
        this.healthStatus = '良好';
        break;
      case batteryInfo.BatteryHealthStatus.HEALTH_STATE_OVERHEAT:
        this.healthStatus = '过热';
        break;
      default:
        this.healthStatus = '未知';
    }

    // 读取充电器类型
    switch (batteryInfo.pluggedType) {
      case batteryInfo.BatteryPluggedType.PLUGGED_TYPE_AC:
        this.pluggedType = 'AC充电器';
        break;
      case batteryInfo.BatteryPluggedType.PLUGGED_TYPE_USB:
        this.pluggedType = 'USB';
        break;
      case batteryInfo.BatteryPluggedType.PLUGGED_TYPE_WIRELESS:
        this.pluggedType = '无线充电';
        break;
      default:
        this.pluggedType = '未插入充电器';
    }
  }

  // 根据电量返回颜色
  getBatteryColor(): string {
    if (this.batteryLevel <= 20) {
      return '#E84026';  // 红色 - 低电量
    } else if (this.batteryLevel <= 30) {
      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 } from '@kit.BasicServicesKit';

@Entry
@Component
struct BatteryMonitorDemo {
  @State batteryLevel: number = 0;
  private subscriber?: commonEventManager.CommonEventSubscriber;

  aboutToAppear(): void {
    this.batteryLevel = batteryInfo.batterySOC;
    this.subscribeBatteryChange();
  }

  aboutToDisappear(): void {
    this.unsubscribeBatteryChange();
  }

  // 订阅电量变化事件
  subscribeBatteryChange(): void {
    let subscribeInfo: 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.subscriber = subscriber;
        commonEventManager.subscribe(this.subscriber,
          (err: BusinessError, data: commonEventManager.CommonEventData) => {
            if (err) {
              console.error(`订阅事件失败: ${err.code}, ${err.message}`);
              return;
            }
            // 电量变化时重新获取最新值
            this.batteryLevel = batteryInfo.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.subscriber = undefined;
        }
      });
    }
  }

  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 卡片端关键代码

// 卡片组件中展示电量
@Component
struct BatteryWidgetCard {
  @LocalStorageProp('batterySOC') batterySOC: number = 0;

  build() {
    Row({ space: 8 }) {
      Text(`电量：`)
        .fontSize(12)

      Progress({ value: this.batterySOC, total: 100, type: ProgressType.Linear })
        .width(60)
        .height(10)
        .color(this.batterySOC <= 20 ? '#E84026' : '#37DF56')

      Text(`${this.batterySOC}%`)
        .fontSize(16)
        .fontWeight(FontWeight.Bold)
        .fontColor(this.batterySOC <= 20 ? '#E84026' : '#37DF56')
    }
  }
}

七、常见问题与注意事项

7.1 获取的电量为 0？

  • 原因：batteryInfo.batterySOC 在模拟器上可能返回默认值 0
  • 解决：使用真机调试，模拟器不保证返回真实电量数据

7.2 充电状态不准确？

  • 原因：充电状态枚举中 UNKNOWN 表示未知状态，并非“未充电”
  • 解决：合理处理所有枚举值，避免遗漏 UNKNOWN

7.3 电量数据不会自动更新

  • 原因：batteryInfo.batterySOC 是即时快照值，不会触发 UI 刷新
  • 解决：结合 commonEventManager 订阅 BATTERY_CHANGED 事件实现实时更新

八、总结

知识点 内容
模块导入 import { batteryInfo } from '@kit.BasicServicesKit'
获取电量 batteryInfo.batterySOC（0~100）
充电状态 batteryInfo.chargingStatus
实时更新 订阅 usual.event.BATTERY_CHANGED 公共事件
权限要求 无需额外权限
卡片场景 通过 Preferences + FormExtensionAbility 传递数据

掌握 @ohos.batteryInfo 模块后，开发者可以轻松实现电量展示、充电监控、低电量预警等功能，为后续开发设备信息类应用卡片打下坚实基础。

# harmonyos # ui # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

【开发者故事】集成 HarmonyOS App Linking 能力，搜觅 App 重塑高效专注搜索新体验

avatar HarmonyOS开发者社区

HarmonyOS应用实战-启示散页-42-收藏导出别混进私密问题：导出前先做字段筛选和用户确认

它可能含来源题库 id、用户自定义题库名称、答案文本、内部时间戳，未来还会添加诊断字段。直接看似方便，却把“存什么”与“允许分享什么”绑死了。

avatar HarmonyOS开发者社区
cover

HarmonyOS UIAbility 启动参数丢失怎么办：Want 和页面路由怎么接住

avatar HarmonyOS开发者社区