企业官网建设流程全解析

• 文档
• 知识库
• 教程
• OpenHarmony

本篇技术指南围绕 OpenHarmony 仓颉 SDK 中 BasicServicesKit（基础服务套件）的ohos.battery_info模块展开，完整讲解BatteryInfo类的全部静态属性以及BatteryCapacityLevel、BatteryChargeState、BatteryHealthState、BatteryPluggedType四个电量状态枚举的定义与用法。读完后，你将能够直接以仓颉代码查询设备的剩余电量、温度、电压电流、充电状态、健康状态与充电器类型，并掌握该模块的系统能力要求、版本前提及常见错误码（如 4900101）的排查手段。

该模块在 Basic Services Kit 的"设备管理"能力分类中承担电量信息查询职责。从 BasicServicesKit 目录索引 可以看到，ohos.battery_info与ohos.device_info（设备信息）同属设备管理子域；Basic Services Kit 简介 也明确将其定位为"提供查询电量信息的能力"。

模块定位与导入方式

battery_info模块主要提供电池状态和充放电状态的查询接口。所有接口均以BatteryInfo类的静态属性形式暴露，开发者无需实例化对象即可读取当前设备的电量信息。

导入模块使用仓颉的 Kit 级导入方式：

import kit.BasicServicesKit.*

示例代码使用说明（引自原文档）：

• 若示例代码首行有// index.cj注释，表示该示例可在仓颉模板工程的index.cj文件中编译运行；
• 若示例需获取 Context 应用上下文，需在仓颉模板工程中的main_ability.cj文件中进行配置；
• 上述示例工程及配置模板详见 仓颉示例代码说明。

需要说明的是，各 Kit 中的仓颉示例并非完整程序，而是对应 API 的主要代码，仅供开发者参考；如需编译运行，需将示例拷贝到仓颉模板工程中。模板工程创建后会自动生成index.cj、main_ability.cj、ability_stage.cj三个模板文件，在index.cj对应位置添加示例代码即可。详见 仓颉示例代码说明 中的步骤。

系统能力与版本前提

模块内所有接口（BatteryInfo类、全部静态属性、四个枚举及其方法）均标注了相同的前提：

• 系统能力：SystemCapability.PowerManager.BatteryManager.Core
• 起始版本：22

这意味着应用运行设备必须支持PowerManager.BatteryManager.Core系统能力，且使用 OpenHarmony API 12（起始版本 22）及以上版本的仓颉 SDK 才能调用这些接口。在跨设备部署或条件编译场景中，应以该系统能力标识作为能力检测依据。

class BatteryInfo：电池信息查询类

public class BatteryInfo {}

BatteryInfo是描述电池信息的类，其全部成员均为静态只读属性，覆盖电量、温度、电压电流、充电状态、健康状态、充电器类型与电池技术型号七个维度。

电量类属性

public static prop batterySoc: Int32 public static prop batteryCapacityLevel: BatteryCapacityLevel

• batterySoc以百分比数值形式给出剩余电量，适合做精确展示（如"电量 78%"）；
• batteryCapacityLevel则将电量抽象为离散等级（满电、高电量、正常、低电量、告警、极低、关电），更适合做业务分支判断（如低电量省电策略、关电前数据保存），避免在应用侧自行维护阈值切分逻辑。

注：原文档中第一个属性小节的标题写作batteryCapacityLevel，但其代码与功能描述实际对应的是batterySoc（电池充电状态 SoC，单位为百分比）。两者均为只读Int32属性，本文按代码声明整理，特此说明，便于读者与官方文档对照。

温度、电压、电流类属性

public static prop batteryTemperature: Int32 public static prop voltage: Int32 public static prop nowCurrent: Int32

使用这三个属性时务必注意单位换算：

• batteryTemperature返回值为实际温度的 10 倍，例如读取到350表示电池温度 35.0 摄氏度；
• voltage以微伏（µV）为单位，例如4150000对应 4.15 V，展示为伏特需除以 1 000 000；
• nowCurrent表示电池当前电流，可结合pluggedType与chargingStatus判断设备正处于充电还是放电过程。

温度、电压、电流数据在电池热管理、充电功耗统计、设备健康度监测等场景下尤为常用。

状态类属性

public static prop chargingStatus: BatteryChargeState public static prop healthStatus: BatteryHealthState public static prop isBatteryPresent: Bool public static prop pluggedType: BatteryPluggedType public static prop technology: String

其中isBatteryPresent返回true表示设备支持电池或电池在位，返回false表示不支持电池或电池不在位，默认值为false。从文档语义看，在桌面类、固定供电类等无电池设备上读取其他电量属性之前，建议先检查该属性，对返回false的情况做降级处理（如隐藏电量 UI 或跳过相关逻辑）。

healthStatus除"正常"外还定义了低温、过热、过压、僵死等异常状态，是构建电池保护逻辑（如高温暂停充电提示、低温禁用快充提示）的关键依据。

enum BatteryCapacityLevel：电池电量等级

public enum BatteryCapacityLevel <: Equatable<BatteryCapacityLevel> & ToString { | LevelFull | LevelHigh | LevelNormal | LevelLow | LevelWarning | LevelCritical | LevelShutdown | ... }

功能：表示电池电量等级的枚举。父类型：Equatable<BatteryCapacityLevel>与ToString。

从枚举定义的结构看，电量等级按"满电 → 高 → 正常 → 低 → 告警 → 极低 → 关电"从高到低递进，开发者可以据此实现逐级加强的省电策略或告警提示。

该枚举提供三个成员方法：

public operator func !=(other: BatteryCapacityLevel): Bool public operator func ==(other: BatteryCapacityLevel): Bool public func toString(): String

• ==：对电池电量等级进行判等，如果两个电量等级相同返回true，否则返回false；
• !=：对电池电量等级进行判不等，如果两个电量等级不同返回true，否则返回false；
• toString()：返回电池电量等级值对应的字符串表示，可直接用于日志打印或界面展示。

==/!=为仓颉的重载运算符（operator func），参数other为BatteryCapacityLevel类型，必填，无默认值，返回值均为Bool。

enum BatteryChargeState：电池充电状态

public enum BatteryChargeState <: Equatable<BatteryChargeState> & ToString { | UnknownChargeState | Enabled | Disabled | Full | ... }

功能：表示电池充电状态的枚举。父类型：Equatable<BatteryChargeState>与ToString。

成员方法与BatteryCapacityLevel一致：

public operator func !=(other: BatteryChargeState): Bool public operator func ==(other: BatteryChargeState): Bool public func toString(): String

• ==：对电池充电状态进行判等，如果充电状态相同返回true，否则返回false；
• !=：对电池充电状态进行判不等，如果充电状态不同返回true，否则返回false；
• toString()：返回电池充电状态值对应的字符串表示。

典型业务用法：判断chargingStatus == BatteryChargeState.Full展示"已充满"图标；判断chargingStatus == BatteryChargeState.Enabled时提示"充电中"；UnknownChargeState则提示读取充电状态失败，需做容错处理。

enum BatteryHealthState：电池健康状态

public enum BatteryHealthState <: Equatable<BatteryHealthState> & ToString { | UnknownHealthState | Good | Overheat | Overvoltage | Cold | Dead | ... }

功能：表示电池健康状态的枚举。父类型：Equatable<BatteryHealthState>与ToString。

成员方法同样为==、!=两个判等运算符与toString()：

public operator func !=(other: BatteryHealthState): Bool public operator func ==(other: BatteryHealthState): Bool public func toString(): String

• ==：对电池健康状态进行判等，如果健康状态相同返回true，否则返回false；
• !=：对电池健康状态进行判不等，如果健康状态不同返回true，否则返回false；
• toString()：返回电池健康状态值对应的字符串表示。

健康状态枚举中Good之外的四个异常值覆盖了温度、电压与电池本身三类故障维度，应用侧可针对Overheat（过热）与Cold（低温）提示用户调整使用环境，对Dead（僵死）等严重状态触发数据保存与退出流程。

enum BatteryPluggedType：充电器类型

public enum BatteryPluggedType <: Equatable<BatteryPluggedType> & ToString { | UnknownType | Ac | Usb | Wireless | ... }

功能：表示连接的充电器类型的枚举。父类型：Equatable<BatteryPluggedType>与ToString。

成员方法与其他三个枚举保持同一模式：

public operator func !=(other: BatteryPluggedType): Bool public operator func ==(other: BatteryPluggedType): Bool public func toString(): String

• ==：对充电器类型进行判等，如果充电器类型相同返回true，否则返回false；
• !=：对充电器类型进行判不等，如果充电器类型不同返回true，否则返回false；
• toString()：返回充电器类型值对应的字符串表示。

充电器类型与chargingStatus组合使用价值更高，例如"接 USB 且Enabled（USB 充电中）""接Wireless且Full（无线充电已充满）"等组合判断，可驱动不同的 UI 提示与充电策略。

组合使用示例：查询并展示完整电量状态

以下示例综合使用BatteryInfo的各静态属性，演示一次完整的电量信息读取。示例代码需在仓颉模板工程的index.cj文件中编译运行（参见 仓颉示例代码说明）：

// index.cj import kit.BasicServicesKit.* func printBatteryInfo() { // 设备不支持电池或电池不在位时，电量相关属性无意义，直接返回 if (!BatteryInfo.isBatteryPresent) { print("设备不支持电池或电池不在位") return } // 剩余电量百分比与电量等级 print("剩余电量: " + BatteryInfo.batterySoc.toString() + "%") print("电量等级: " + BatteryInfo.batteryCapacityLevel.toString()) // 温度（0.1 摄氏度）换算为摄氏度 print("电池温度: " + (BatteryInfo.batteryTemperature / 10.0).toString() + " ℃") // 电压（微伏）换算为伏特 print("电池电压: " + (BatteryInfo.voltage / 1000000.0).toString() + " V") print("电池电流: " + BatteryInfo.nowCurrent.toString()) // 充电状态、健康状态与充电器类型 print("充电状态: " + BatteryInfo.chargingStatus.toString()) print("健康状态: " + BatteryInfo.healthStatus.toString()) print("充电器类型: " + BatteryInfo.pluggedType.toString()) // 业务分支示例：低电量 + 未充电时提示用户 if (BatteryInfo.batteryCapacityLevel == BatteryCapacityLevel.LevelWarning || BatteryInfo.batteryCapacityLevel == BatteryCapacityLevel.LevelCritical) { if (BatteryInfo.chargingStatus != BatteryChargeState.Enabled) { print("电量较低，请尽快充电") } } }

示例体现了三个要点：

1. 所有接口均为BatteryInfo的静态只读属性，直接以类名访问，无需构造对象；
2. 利用枚举的toString()输出可读文本，利用重载的==/!=运算符做状态判断；
3. 在读取前先检查isBatteryPresent，并对温度、电压做单位换算，保证展示值正确。

常见问题与错误排查

电量信息接口依赖系统电源管理服务，当系统服务不可用或连接异常时，可能返回模块特有的电源管理错误码。系统电源管理错误码 文档定义了如下典型错误码：

可能原因：

1. 系统服务停止运行；
2. 系统服务内部通讯发生异常。

处理步骤（引自 系统电源管理错误码）：检查系统服务是否正常运行：

1. 在控制台中输入如下命令，查看当前的系统服务列表：

   > hdc shell hidumper -ls

2. 查看系统服务列表中是否包含PowerManagerService系统服务。

通用错误码的说明可进一步参考 通用错误码说明文档。

小结

ohos.battery_info模块以BatteryInfo类的静态只读属性为核心，提供了从"精确数值"（batterySoc、batteryTemperature、voltage、nowCurrent）到"语义状态"（batteryCapacityLevel、chargingStatus、healthStatus、pluggedType、technology）的完整电量信息视图，四个枚举均实现Equatable与ToString，天然适配仓颉的模式匹配与字符串输出。结合SystemCapability.PowerManager.BatteryManager.Core系统能力声明、API 12（起始版本 22）的版本前提与4900101错误码排查方法，即可在仓颉应用内实现健壮、完整的电量监测能力。

相关文档：

• ohos.battery_info（电量信息）原文档
• Basic ServicesKit 接口目录索引
• ohos.device_info（设备信息）
• 系统电源管理错误码
• 仓颉示例代码说明

• 文档
• 知识库
• 教程
• OpenHarmony