• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.batteryInfo (Battery Information) (System API)
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
10The **batteryInfo** module provides APIs for querying the charger type, battery health status, and battery charging status.
11
12> **NOTE**
13>
14> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
15>
16>This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.batteryInfo (Battery Information)](js-apis-battery-info.md).
17
18
19## Modules to Import
20
21```js
22import {batteryInfo} from '@kit.BasicServicesKit';
23```
24
25## batteryInfo.setBatteryConfig<sup>11+</sup>
26
27setBatteryConfig(sceneName: string, sceneValue: string): number
28
29Sets the battery configuration based on the specified scenario.
30
31**System API**: This is a system API.
32
33**System capability**: SystemCapability.PowerManager.BatteryManager.Core
34
35**Parameters**
36
37| Name    | Type  | Mandatory| Description        |
38| ---------- | ------ | ---- | ------------ |
39| sceneName  | string | Yes  | Scenario name. The value must be a string.|
40| sceneValue | string | Yes  | Scenario value. The value must be a string.|
41
42**Return value**
43
44| Type  | Description                                                      |
45| ------ | ---------------------------------------------------------- |
46| number | Operation result. The value **0** indicates that the operation is successful, and a non-zero value indicates the opposite.|
47
48**Error codes**
49
50For details about the error codes, see [Battery Info Error Codes](errorcode-battery-info.md) and [Universal Error Codes](../errorcode-universal.md).
51
52| ID  | Error Message   |
53|---------|---------|
54| 5100101 | Failed to connect to the service. |
55| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
56| 202     | Permission verification failed. A non-system application calls a system API. |
57
58**Example**
59
60  ```ts
61  import {batteryInfo} from '@kit.BasicServicesKit';
62
63  let sceneName = 'xxx';
64  let sceneValue = '0';
65  let result = batteryInfo.setBatteryConfig(sceneName, sceneValue);
66
67  console.info("The result is: " + result);
68  ```
69
70## batteryInfo.getBatteryConfig<sup>11+</sup>
71
72getBatteryConfig(sceneName: string): string
73
74Obtains the battery configuration based on the specified scenario.
75
76**System API**: This is a system API.
77
78**System capability**: SystemCapability.PowerManager.BatteryManager.Core
79
80**Parameters**
81
82| Name   | Type  | Mandatory| Description        |
83| --------- | ------ | ---- | ------------ |
84| sceneName | string | Yes  | Scenario name. The value must be a string.|
85
86**Return value**
87
88| Type  | Description                          |
89| ------ | ------------------------------ |
90| string | Operation result. The battery configuration is returned if the operation is successful. Otherwise, **""** is returned.|
91
92**Error codes**
93
94For details about the error codes, see [Battery Info Error Codes](errorcode-battery-info.md) and [Universal Error Codes](../errorcode-universal.md).
95
96| ID  | Error Message   |
97|---------|---------|
98| 5100101 | Failed to connect to the service. |
99| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
100| 202     | Permission verification failed. A non-system application calls a system API. |
101
102**Example**
103
104  ```ts
105  import {batteryInfo} from '@kit.BasicServicesKit';
106
107  let sceneName = 'xxx';
108  let result = batteryInfo.getBatteryConfig(sceneName);
109
110  console.info("The result is: " + result);
111  ```
112
113## batteryInfo.isBatteryConfigSupported<sup>11+</sup>
114
115isBatteryConfigSupported(sceneName: string): boolean
116
117Checks whether the battery configuration is enabled based on the specified scenario.
118
119**System API**: This is a system API.
120
121**System capability**: SystemCapability.PowerManager.BatteryManager.Core
122
123**Parameters**
124
125| Name   | Type  | Mandatory| Description        |
126| --------- | ------ | ---- | ------------ |
127| sceneName | string | Yes  | Scenario name. The value must be a string.|
128
129**Return value**
130
131| Type   | Description                                             |
132| ------- | ------------------------------------------------- |
133| boolean | Operation result. The value **true** indicates that the charging scenario is supported, and the value **false** indicates the opposite.|
134
135**Error codes**
136
137For details about the error codes, see [Battery Info Error Codes](errorcode-battery-info.md) and [Universal Error Codes](../errorcode-universal.md).
138
139| ID  | Error Message   |
140|---------|---------|
141| 5100101 | Failed to connect to the service. |
142| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
143| 202     | Permission verification failed. A non-system application calls a system API. |
144
145**Example**
146
147  ```ts
148  import {batteryInfo} from '@kit.BasicServicesKit';
149
150  let sceneName = 'xxx';
151  let result = batteryInfo.isBatteryConfigSupported(sceneName);
152
153  console.info("The result is: " + result);
154  ```
155
156## Properties
157
158Describes battery information.
159
160**System capability**: SystemCapability.PowerManager.BatteryManager.Core
161
162| Name     | Type       | Read-Only| Optional|  Description    |
163| --------------- | ------------------- | ---- | ---- | ---------------------|
164| estimatedRemainingChargeTime<sup>9+</sup> | number                                         | Yes  | No  | Estimated time for fully charging the current device, in unit of milliseconds. This is a system API.         |
165| totalEnergy<sup>9+</sup>                  | number                                         | Yes  | No  | Total battery capacity of the device, in unit of mAh. This is a system API.  |
166| remainingEnergy<sup>9+</sup>              | number                                         | Yes  | No  | Remaining battery capacity of the device, in unit of mAh. This is a system API.|
167
168**Example**
169  ```ts
170  import {batteryInfo} from '@kit.BasicServicesKit';
171
172  let estimatedRemainingChargeTimeInfo: number = batteryInfo.estimatedRemainingChargeTime;
173  console.info("The estimatedRemainingChargeTimeInfo is: " + estimatedRemainingChargeTimeInfo);
174
175  let totalEnergyInfo: number = batteryInfo.totalEnergy;
176  console.info("The totalEnergyInfo is: " + totalEnergyInfo);
177
178  let remainingEnergyInfo: number = batteryInfo.remainingEnergy;
179  console.info("The remainingEnergyInfo is: " + remainingEnergyInfo);
180  ```
181