1# @ohos.batteryStatistics (Battery Statistics) 2 3The **batteryStatistics** module provides APIs for querying software and hardware power consumption statistics. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> - The APIs provided by this module are system APIs. 10 11## Modules to Import 12 13```js 14import batteryStats from '@ohos.batteryStatistics'; 15``` 16 17## batteryStats.getBatteryStats 18 19getBatteryStats(): Promise<Array<BatteryStatsInfo>> 20 21Obtains the power consumption information list. This API uses a promise to return the result. 22 23**System API**: This is a system API. 24 25**System capability**: SystemCapability.PowerManager.BatteryStatistics 26 27**Return value** 28 29| Type | Description | 30| ----------------------------------------------------- | ------------------------------- | 31| Promise<Array<[BatteryStatsInfo](#batterystatsinfo)>> | Promise used to return the power consumption information list.| 32 33**Error codes** 34 35For details about the error codes, see [Thermal Manager Error Codes](../errorcodes/errorcode-batteryStatistics.md). 36 37| Code | Error Message | 38|---------|---------| 39| 4600101 | If connecting to the service failed. | 40 41**Example** 42 43```js 44batteryStats.getBatteryStats() 45.then((data: batteryStats.BatteryStatsInfo[]) => { 46 console.info('battery statistics info: ' + data); 47}) 48.catch((err: Error) => { 49 console.error('get battery statistics failed, err: ' + err); 50}); 51``` 52 53## batteryStats.getBatteryStats 54 55getBatteryStats(callback: AsyncCallback<Array<BatteryStatsInfo>>): void 56 57Obtains the power consumption information list. This API uses an asynchronous callback to return the result. 58 59**System API**: This is a system API. 60 61**System capability**: SystemCapability.PowerManager.BatteryStatistics 62 63**Parameters** 64 65| Name | Type | Mandatory| Description | 66| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 67| callback | AsyncCallback<Array<[BatteryStatsInfo](#batterystatsinfo)>> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the array of power consumption information obtained (that is, **Array<[BatteryStatsInfo](#batterystatsinfo)>>**). If the operation failed, **err** is an error object.| 68 69**Error codes** 70 71For details about the error codes, see [Thermal Manager Error Codes](../errorcodes/errorcode-batteryStatistics.md). 72 73| Code | Error Message | 74|---------|---------| 75| 4600101 | If connecting to the service failed. | 76 77**Example** 78 79```js 80batteryStats.getBatteryStats((err: Error, data : batteryStats.BatteryStatsInfo[]) => { 81 if (typeof err === 'undefined') { 82 console.info('battery statistics info: ' + data); 83 } else { 84 console.error('get battery statistics failed, err: ' + err); 85 } 86}); 87``` 88 89## batteryStats.getAppPowerValue 90 91getAppPowerValue(uid: number): number 92 93Obtains the power consumption of an application. 94 95**System API**: This is a system API. 96 97**System capability**: SystemCapability.PowerManager.BatteryStatistics 98 99**Parameters** 100 101| Name| Type | Mandatory| Description | 102| ------ | ------ | ---- | ----------- | 103| uid | number | Yes | Application UID.| 104 105**Return value** 106 107| Type | Description | 108| ------ | --------------------------------- | 109| number | Power consumption of the application with this UID, in unit of mAh.| 110 111**Error codes** 112 113For details about the error codes, see [Thermal Manager Error Codes](../errorcodes/errorcode-batteryStatistics.md). 114 115| Code | Error Message | 116|---------|---------| 117| 4600101 | If connecting to the service failed. | 118 119**Example** 120 121```js 122try { 123 let value = batteryStats.getAppPowerValue(10021); 124 console.info('battery statistics value of app is: ' + value); 125} catch(err) { 126 console.error('get battery statistics value of app failed, err: ' + err); 127} 128``` 129 130## batteryStats.getAppPowerPercent 131 132getAppPowerPercent(uid: number): number 133 134Obtains the proportion of the power consumption of an application. 135 136**System API**: This is a system API. 137 138**System capability**: SystemCapability.PowerManager.BatteryStatistics 139 140**Parameters** 141 142| Name| Type | Mandatory| Description | 143| ------ | ------ | ---- | ----------- | 144| uid | number | Yes | Application UID.| 145 146**Return value** 147 148| Type | Description | 149| ------ | ------------------------- | 150| number | Proportion of the power consumption of an application with this UID.| 151 152**Error codes** 153 154For details about the error codes, see [Thermal Manager Error Codes](../errorcodes/errorcode-batteryStatistics.md). 155 156| Code | Error Message | 157|---------|---------| 158| 4600101 | If connecting to the service failed. | 159 160**Example** 161 162```js 163try { 164 let percent = batteryStats.getAppPowerPercent(10021); 165 console.info('battery statistics percent of app is: ' + percent); 166} catch(err) { 167 console.error('get battery statistics percent of app failed, err: ' + err); 168} 169``` 170 171## batteryStats.getHardwareUnitPowerValue 172 173getHardwareUnitPowerValue(type: ConsumptionType): number 174 175Obtains the power consumption of a hardware unit according to the consumption type. 176 177**System API**: This is a system API. 178 179**System capability**: SystemCapability.PowerManager.BatteryStatistics 180 181**Parameters** 182 183| Name| Type | Mandatory| Description | 184| ------ | ----------------------------------- | ---- | -------------- | 185| type | [ConsumptionType](#consumptiontype) | Yes | Power consumption type.| 186 187**Return value** 188 189| Type | Description | 190| ------ | ------------------------------------------ | 191| number | Power consumption of the hardware unit corresponding to the power consumption type, in unit of mAh.| 192 193**Error codes** 194 195For details about the error codes, see [Thermal Manager Error Codes](../errorcodes/errorcode-batteryStatistics.md). 196 197| Code | Error Message | 198|---------|---------| 199| 4600101 | If connecting to the service failed. | 200 201**Example** 202 203```js 204try { 205 let value = batteryStats.getHardwareUnitPowerValue(batteryStats.ConsumptionType.CONSUMPTION_TYPE_SCREEN); 206 console.info('battery statistics value of hardware is: ' + value); 207} catch(err) { 208 console.error('get battery statistics percent of hardware failed, err: ' + err); 209} 210``` 211 212## batteryStats.getHardwareUnitPowerPercent 213 214getHardwareUnitPowerPercent(type: ConsumptionType): number 215 216Obtains the proportion of the power consumption of a hardware unit according to the power consumption type. 217 218**System API**: This is a system API. 219 220**System capability**: SystemCapability.PowerManager.BatteryStatistics 221 222**Parameters** 223 224| Name| Type | Mandatory| Description | 225| ------ | ----------------------------------- | ---- | -------------- | 226| type | [ConsumptionType](#consumptiontype) | Yes | Power consumption type.| 227 228**Return value** 229 230| Type | Description | 231| ------ | ---------------------------------- | 232| number | Proportion of the power consumption of the hardware unit corresponding to the power consumption type.| 233 234**Error codes** 235 236For details about the error codes, see [Thermal Manager Error Codes](../errorcodes/errorcode-batteryStatistics.md). 237 238| Code | Error Message | 239|---------|---------| 240| 4600101 | If connecting to the service failed. | 241 242**Example** 243 244```js 245try { 246 let percent = batteryStats.getHardwareUnitPowerPercent(batteryStats.ConsumptionType.CONSUMPTION_TYPE_SCREEN); 247 console.info('battery statistics percent of hardware is: ' + percent); 248} catch(err) { 249 console.error('get battery statistics percent of hardware failed, err: ' + err); 250} 251``` 252 253## BatteryStatsInfo 254 255Describes the device power consumption information. 256 257**System API**: This is a system API. 258 259**System capability**: SystemCapability.PowerManager.BatteryStatistics 260 261### Attributes 262 263| Name | Type | Readable| Writable| Description | 264| ----- | ----------------------------------- | ---- | ---- | ---------------------- | 265| uid | number | Yes | No | UID related to power consumption information. | 266| type | [ConsumptionType](#consumptiontype) | Yes | No | Power consumption type. | 267| power | number | Yes | No | Power consumption, in unit of mAh.| 268 269## ConsumptionType 270 271Enumerates power consumption types. 272 273**System API**: This is a system API. 274 275**System capability**: SystemCapability.PowerManager.BatteryStatistics 276 277| Name | Value | Description | 278| -------------------------- | ---- | ----------------------------- | 279| CONSUMPTION_TYPE_INVALID | -17 | Unknown type. | 280| CONSUMPTION_TYPE_APP | -16 | Power consumption of an application. | 281| CONSUMPTION_TYPE_BLUETOOTH | -15 | Power consumption of Bluetooth. | 282| CONSUMPTION_TYPE_IDLE | -14 | Power consumption when the CPU is idle.| 283| CONSUMPTION_TYPE_PHONE | -13 | Power consumption of a phone call. | 284| CONSUMPTION_TYPE_RADIO | -12 | Power consumption of wireless communication. | 285| CONSUMPTION_TYPE_SCREEN | -11 | Power consumption of the screen. | 286| CONSUMPTION_TYPE_USER | -10 | Power consumption of the user. | 287| CONSUMPTION_TYPE_WIFI | -9 | Power consumption of Wi-Fi. | 288