1# @ohos.batteryStatistics (耗电统计)(系统接口)
2
3该模块提供软硬件耗电统计信息的查询接口。
4
5> **说明：**
6>
7> - 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> - 本模块接口为系统接口。
10
11## 导入模块
12
13```js
14import {batteryStats} from '@kit.BasicServicesKit';
15```
16
17## batteryStats.getBatteryStats
18
19getBatteryStats(): Promise<Array&lt;BatteryStatsInfo&gt;>
20
21获取耗电信息列表。使用Promise异步回调。
22
23**系统接口：** 此接口为系统接口。
24
25**系统能力：** SystemCapability.PowerManager.BatteryStatistics
26
27**返回值：**
28
29| 类型                                                  | 说明                            |
30| ----------------------------------------------------- | ------------------------------- |
31| Promise<Array<[BatteryStatsInfo](#batterystatsinfo)>> | Promise对象，返回耗电信息列表。 |
32
33**错误码：**
34
35以下错误码的详细介绍请参见[耗电统计错误码](errorcode-batteryStatistics.md)。
36
37| 错误码ID   | 错误信息    |
38|---------|---------|
39| 4600101 | Failed to connect to the service. |
40| 202     | Permission verification failed. A non-system application calls a system API.  |
41
42**示例：**
43
44```js
45batteryStats.getBatteryStats()
46.then((data: batteryStats.BatteryStatsInfo[]) => {
47    console.info('battery statistics info: ' + data);
48})
49.catch((err: Error) => {
50    console.error('get battery statistics failed, err: ' + err);
51});
52```
53
54## batteryStats.getBatteryStats
55
56getBatteryStats(callback: AsyncCallback<Array&lt;BatteryStatsInfo&gt;>): void
57
58获取耗电信息列表。使用callback异步回调。
59
60**系统接口：** 此接口为系统接口。
61
62**系统能力：** SystemCapability.PowerManager.BatteryStatistics
63
64**参数：**
65
66| 参数名   | 类型                                                        | 必填 | 说明                                                         |
67| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
68| callback | AsyncCallback<Array<[BatteryStatsInfo](#batterystatsinfo)>> | 是   | 回调函数。当获取耗电信息列表成功，err为undefined，data为获取到的Array<[BatteryStatsInfo](#batterystatsinfo)>>；否则为错误对象；AsyncCallback封装了一个BatteryStatsInfo类型的接口。 |
69
70**错误码：**
71
72以下错误码的详细介绍请参见[耗电统计错误码](errorcode-batteryStatistics.md)。
73
74| 错误码ID   | 错误信息    |
75|---------|---------|
76| 4600101 | Failed to connect to the service. |
77| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
78| 202     | Permission verification failed. A non-system application calls a system API.  |
79
80**示例：**
81
82```js
83batteryStats.getBatteryStats((err: Error, data : batteryStats.BatteryStatsInfo[]) => {
84    if (typeof err === 'undefined') {
85        console.info('battery statistics info: ' + data);
86    } else {
87        console.error('get battery statistics failed, err: ' + err);
88    }
89});
90```
91
92## batteryStats.getAppPowerValue
93
94getAppPowerValue(uid: number): number
95
96获取应用的耗电量。
97
98**系统接口：** 此接口为系统接口。
99
100**系统能力：** SystemCapability.PowerManager.BatteryStatistics
101
102**参数：**
103
104| 参数名 | 类型   | 必填 | 说明        |
105| ------ | ------ | ---- | ----------- |
106| uid    | number | 是   | 应用的UID。 |
107
108**返回值：**
109
110| 类型   | 说明                              |
111| ------ | --------------------------------- |
112| number | UID对应应用的耗电量，单位毫安时。 |
113
114**错误码：**
115
116以下错误码的详细介绍请参见[耗电统计错误码](errorcode-batteryStatistics.md)。
117
118| 错误码ID   | 错误信息    |
119|---------|---------|
120| 4600101 | Failed to connect to the service. |
121| 202     | Permission verification failed. A non-system application calls a system API.  |
122| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
123
124**示例：**
125
126```js
127try {
128    let value = batteryStats.getAppPowerValue(10021);
129    console.info('battery statistics value of app is: ' + value);
130} catch(err) {
131    console.error('get battery statistics value of app failed, err: ' + err);
132}
133```
134
135## batteryStats.getAppPowerPercent
136
137getAppPowerPercent(uid: number): number
138
139获取应用的耗电百分比。
140
141**系统接口：** 此接口为系统接口。
142
143**系统能力：** SystemCapability.PowerManager.BatteryStatistics
144
145**参数：**
146
147| 参数名 | 类型   | 必填 | 说明        |
148| ------ | ------ | ---- | ----------- |
149| uid    | number | 是   | 应用的UID。 |
150
151**返回值：**
152
153| 类型   | 说明                      |
154| ------ | ------------------------- |
155| number | UID对应应用的耗电百分比。 |
156
157**错误码：**
158
159以下错误码的详细介绍请参见[耗电统计错误码](errorcode-batteryStatistics.md)。
160
161| 错误码ID   | 错误信息    |
162|---------|---------|
163| 4600101 | Failed to connect to the service. |
164| 202     | Permission verification failed. A non-system application calls a system API.  |
165| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
166
167**示例：**
168
169```js
170try {
171    let percent = batteryStats.getAppPowerPercent(10021);
172    console.info('battery statistics percent of app is: ' + percent);
173} catch(err) {
174    console.error('get battery statistics percent of app failed, err: ' + err);
175}
176```
177
178## batteryStats.getHardwareUnitPowerValue
179
180getHardwareUnitPowerValue(type: ConsumptionType): number
181
182根据耗电类型获取硬件单元的耗电量。
183
184**系统接口：** 此接口为系统接口。
185
186**系统能力：** SystemCapability.PowerManager.BatteryStatistics
187
188**参数：**
189
190| 参数名 | 类型                                | 必填 | 说明           |
191| ------ | ----------------------------------- | ---- | -------------- |
192| type   | [ConsumptionType](#consumptiontype) | 是   | 电量消耗类型；该参数类型是枚举类。 |
193
194**返回值：**
195
196| 类型   | 说明                                       |
197| ------ | ------------------------------------------ |
198| number | 电量消耗类型对应硬件的耗电量，单位毫安时。 |
199
200**错误码：**
201
202以下错误码的详细介绍请参见[耗电统计错误码](errorcode-batteryStatistics.md)。
203
204| 错误码ID   | 错误信息    |
205|---------|---------|
206| 4600101 | Failed to connect to the service. |
207| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
208| 202     | Permission verification failed. A non-system application calls a system API.  |
209
210**示例：**
211
212```js
213try {
214    let value = batteryStats.getHardwareUnitPowerValue(batteryStats.ConsumptionType.CONSUMPTION_TYPE_SCREEN);
215    console.info('battery statistics value of hardware is: ' + value);
216} catch(err) {
217    console.error('get battery statistics percent of hardware failed, err: ' + err);
218}
219```
220
221## batteryStats.getHardwareUnitPowerPercent
222
223getHardwareUnitPowerPercent(type: ConsumptionType): number
224
225根据耗电类型获取硬件单元的耗电百分比。
226
227**系统接口：** 此接口为系统接口。
228
229**系统能力：** SystemCapability.PowerManager.BatteryStatistics
230
231**参数：**
232
233| 参数名 | 类型                                | 必填 | 说明           |
234| ------ | ----------------------------------- | ---- | -------------- |
235| type   | [ConsumptionType](#consumptiontype) | 是   | 电量消耗类型；该参数类型是枚举类。 |
236
237**返回值：**
238
239| 类型   | 说明                               |
240| ------ | ---------------------------------- |
241| number | 电量消耗类型对应硬件的耗电百分比。 |
242
243**错误码：**
244
245以下错误码的详细介绍请参见[耗电统计错误码](errorcode-batteryStatistics.md)。
246
247| 错误码ID   | 错误信息    |
248|---------|---------|
249| 4600101 | Failed to connect to the service. |
250| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
251| 202     | Permission verification failed. A non-system application calls a system API. |
252
253**示例：**
254
255```js
256try {
257    let percent = batteryStats.getHardwareUnitPowerPercent(batteryStats.ConsumptionType.CONSUMPTION_TYPE_SCREEN);
258    console.info('battery statistics percent of hardware is: ' + percent);
259} catch(err) {
260    console.error('get battery statistics percent of hardware failed, err: ' + err);
261}
262```
263
264## BatteryStatsInfo
265
266设备的耗电信息。
267
268**系统接口：** 此接口为系统接口。
269
270**系统能力：** SystemCapability.PowerManager.BatteryStatistics
271
272### 属性
273
274| 名称  | 类型                                | 可读 | 可写 | 说明                   |
275| ----- | ----------------------------------- | ---- | ---- | ---------------------- |
276| uid   | number                              | 是   | 否   | 耗电信息相关的UID。    |
277| type  | [ConsumptionType](#consumptiontype) | 是   | 否   | 耗电信息相关的类型。   |
278| power | number                              | 是   | 否   | 耗电的值，单位毫安时。 |
279
280## ConsumptionType
281
282表示电量消耗类型的枚举值。
283
284**系统接口：** 此接口为系统接口。
285
286**系统能力：** SystemCapability.PowerManager.BatteryStatistics
287
288| 名称                       | 值   | 说明                          |
289| -------------------------- | ---- | ----------------------------- |
290| CONSUMPTION_TYPE_INVALID   | -17  | 表示电量消耗类型未知。        |
291| CONSUMPTION_TYPE_APP       | -16  | 表示应用消耗的电量类型。      |
292| CONSUMPTION_TYPE_BLUETOOTH | -15  | 表示蓝牙消耗的电量类型。      |
293| CONSUMPTION_TYPE_IDLE      | -14  | 表示CPU空闲时消耗的电量类型。 |
294| CONSUMPTION_TYPE_PHONE     | -13  | 表示通话来电消耗的电量类型。  |
295| CONSUMPTION_TYPE_RADIO     | -12  | 表示无线通讯消耗的电量类型。  |
296| CONSUMPTION_TYPE_SCREEN    | -11  | 表示屏幕消耗的电量类型。      |
297| CONSUMPTION_TYPE_USER      | -10  | 表示用户消耗的电量类型。      |
298| CONSUMPTION_TYPE_WIFI      | -9   | 表示无线网消耗的电量类型。    |
299