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