• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.power (系统电源管理)(系统接口)
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 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
15>
16> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.power (系统电源管理)](js-apis-power.md)。
17
18## 导入模块
19
20```js
21import {power} from '@kit.BasicServicesKit';
22```
23
24## power.shutdown
25
26shutdown(reason: string): void
27
28系统关机。
29
30**系统接口：** 此接口为系统接口。
31
32**需要权限：** ohos.permission.REBOOT
33
34**系统能力：** SystemCapability.PowerManager.PowerManager.Core
35
36**参数：**
37
38| 参数名    | 类型     | 必填   | 说明    |
39| ------ | ------ | ---- | ----- |
40| reason | string | 是    | 关机原因；该参数必须为字符串类型。 |
41
42**错误码：**
43
44以下错误码的详细介绍请参见[系统电源管理错误码](errorcode-power.md)和[通用错误码](../errorcode-universal.md)。
45
46| 错误码ID   | 错误信息    |
47|---------|---------|
48| 4900101 | Failed to connect to the service. |
49| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
50| 201     | Permission verification failed. The application does not have the permission required to call the API. |
51| 202     | Permission verification failed. A non-system application calls a system API.  |
52
53
54**示例：**
55
56```js
57try {
58    power.shutdown('shutdown_test');
59} catch(err) {
60    console.error('shutdown failed, err: ' + err);
61}
62```
63
64## power.reboot<sup>9+</sup>
65
66reboot(reason: string): void
67
68重启设备。
69
70**系统接口：** 此接口为系统接口。
71
72**需要权限：** ohos.permission.REBOOT
73
74**系统能力：** SystemCapability.PowerManager.PowerManager.Core
75
76**参数：**
77
78| 参数名 | 类型   | 必填 | 说明       |
79| ------ | ------ | ---- | ---------- |
80| reason | string | 是   | 重启原因；该参数必须为字符串类型。 |
81
82**错误码：**
83
84以下错误码的详细介绍请参见[系统电源管理错误码](errorcode-power.md)和[通用错误码](../errorcode-universal.md)。
85
86| 错误码ID   | 错误信息    |
87|---------|---------|
88| 4900101 | Failed to connect to the service. |
89| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
90| 201     | Permission verification failed. The application does not have the permission required to call the API. |
91| 202     | Permission verification failed. A non-system application calls a system API.  |
92
93**示例：**
94
95```js
96try {
97    power.reboot('reboot_test');
98} catch(err) {
99    console.error('reboot failed, err: ' + err);
100}
101```
102
103## power.wakeup<sup>9+</sup>
104
105wakeup(detail: string): void
106
107唤醒设备。
108
109**系统接口：** 此接口为系统接口。
110
111**需要权限：** ohos.permission.POWER_MANAGER
112
113API version 9-18，使用该接口无需权限；从API version 19开始，需要申请“ohos.permission.POWER_MANAGER”权限。
114
115**系统能力：** SystemCapability.PowerManager.PowerManager.Core
116
117**参数：**
118
119| 参数名 | 类型   | 必填 | 说明       |
120| ------ | ------ | ---- | ---------- |
121| detail | string | 是   | 唤醒原因；该参数必须为字符串类型。 |
122
123**错误码：**
124
125以下错误码的详细介绍请参见[系统电源管理错误码](errorcode-power.md)和[通用错误码](../errorcode-universal.md)。
126
127| 错误码ID   | 错误信息    |
128|---------|---------|
129| 4900101 | Failed to connect to the service. |
130| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
131| 201     | Permission verification failed. The application does not have the permission required to call the API. |
132| 202     | Permission verification failed. A non-system application calls a system API.  |
133
134**示例：**
135
136```js
137try {
138    power.wakeup('wakeup_test');
139} catch(err) {
140    console.error('wakeup failed, err: ' + err);
141}
142```
143
144## power.suspend<sup>9+</sup>
145
146suspend(isImmediate?: boolean): void
147
148休眠设备。
149
150**系统接口：** 此接口为系统接口。
151
152**需要权限：** ohos.permission.POWER_MANAGER
153
154API version 9-18，使用该接口无需权限；从API version 19开始，需要申请“ohos.permission.POWER_MANAGER”权限。
155
156**系统能力：** SystemCapability.PowerManager.PowerManager.Core
157
158**参数：**
159
160| 参数名 | 类型   | 必填 | 说明       |
161| ------ | ------ | ---- | ---------- |
162| isImmediate<sup>10+</sup> | boolean |  否  | 是否直接休眠设备。true表示灭屏后立即进入休眠，不填该参数则默认为false，表示灭屏后由系统自动检测何时进入休眠。如果只想做灭屏操作，建议不填参数。<br>**说明：** 从API version 10开始，支持该参数。|
163
164
165**错误码：**
166
167以下错误码的详细介绍请参见[系统电源管理错误码](errorcode-power.md)和[通用错误码](../errorcode-universal.md)。
168
169| 错误码ID   | 错误信息    |
170|---------|---------|
171| 4900101 | Failed to connect to the service. |
172| 201     | Permission verification failed. The application does not have the permission required to call the API. |
173| 202     | Permission verification failed. A non-system application calls a system API.  |
174| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
175
176**示例：**
177
178```js
179try {
180    power.suspend();
181} catch(err) {
182    console.error('suspend failed, err: ' + err);
183}
184```
185
186## power.setPowerMode<sup>9+</sup>
187
188setPowerMode(mode: DevicePowerMode, callback: AsyncCallback&lt;void&gt;): void
189
190设置当前设备的电源模式。使用callback异步回调。
191
192**系统接口：** 此接口为系统接口。
193
194**需要权限：** ohos.permission.POWER_OPTIMIZATION
195
196**系统能力：** SystemCapability.PowerManager.PowerManager.Core
197
198**参数：**
199
200| 参数名   | 类型                                 | 必填 | 说明                                                         |
201| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
202| mode     | DevicePowerMode | 是   | 电源模式；该参数类型是一个枚举类。                                                   |
203| callback | AsyncCallback&lt;void&gt;            | 是   | 回调函数。当设置电源模式成功，err为undefined，否则为错误对象。 |
204
205**错误码：**
206
207以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
208
209| 错误码ID   | 错误信息    |
210|---------|---------|
211| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
212| 201     | Permission verification failed. The application does not have the permission required to call the API. |
213| 202     | Permission verification failed. A non-system application calls a system API.  |
214
215**示例：**
216
217```js
218power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, (err: Error) => {
219    if (typeof err === 'undefined') {
220        console.info('set power mode to MODE_PERFORMANCE');
221    } else {
222        console.error('set power mode failed, err: ' + err);
223    }
224});
225```
226
227## power.setPowerMode<sup>9+</sup>
228
229setPowerMode(mode: DevicePowerMode): Promise&lt;void&gt;
230
231设置当前设备的电源模式。使用Promise异步回调。
232
233**系统接口：** 此接口为系统接口。
234
235**需要权限：** ohos.permission.POWER_OPTIMIZATION
236
237**系统能力：** SystemCapability.PowerManager.PowerManager.Core
238
239**参数：**
240
241| 参数名 | 类型                                 | 必填 | 说明       |
242| ------ | ------------------------------------ | ---- | ---------- |
243| mode   | DevicePowerMode | 是   | 电源模式；该参数类型是一个枚举类。 |
244
245**返回值：**
246
247| 类型                | 说明                                   |
248| ------------------- | -------------------------------------- |
249| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
250
251**错误码：**
252
253以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
254
255| 错误码ID   | 错误信息    |
256|---------|---------|
257| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
258| 201     | Permission verification failed. The application does not have the permission required to call the API. |
259| 202     | Permission verification failed. A non-system application calls a system API.  |
260
261**示例：**
262
263```js
264power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE)
265.then(() => {
266    console.info('set power mode to MODE_PERFORMANCE');
267})
268.catch((err : Error)=> {
269    console.error('set power mode failed, err: ' + err);
270});
271```
272
273## power.setScreenOffTime<sup>12+</sup>
274
275setScreenOffTime(timeout: number): void
276
277设置熄屏超时时间。
278
279**系统接口：** 此接口为系统接口。
280
281**需要权限：** ohos.permission.POWER_MANAGER
282
283API version 12-18，使用该接口无需权限；从API version 19开始，需要申请“ohos.permission.POWER_MANAGER”权限。
284
285**系统能力：** SystemCapability.PowerManager.PowerManager.Core
286
287**参数：**
288
289| 参数名    | 类型     | 必填   | 说明    |
290| ------ | ------ | ---- | ----- |
291| timeout | number | 是    | 熄屏超时时间，单位是毫秒，大于0代表熄屏超时时间，-1代表恢复默认超时时间，其它是无效值。 |
292
293**错误码：**
294
295以下错误码的详细介绍请参见[系统电源管理错误码](errorcode-power.md)和[通用错误码](../errorcode-universal.md)。
296
297| 错误码ID   | 错误信息    |
298|---------|---------|
299| 4900101 | Failed to connect to the service. |
300| 401     | Parameter error. Possible causes: 1. Parameter verification failed. |
301| 201     | Permission verification failed. The application does not have the permission required to call the API. |
302| 202     | Permission verification failed. A non-system application calls a system API.  |
303
304**示例：**
305
306```js
307try {
308    power.setScreenOffTime(30000);
309} catch(err) {
310    console.error('set screen off time failed, err: ' + err);
311}
312```
313
314## power.hibernate<sup>12+</sup>
315
316hibernate(clearMemory: boolean): void
317
318休眠设备。
319
320**系统接口：** 此接口为系统接口。
321
322**需要权限：** ohos.permission.POWER_MANAGER
323
324API version 12-18，使用该接口无需权限；从API version 19开始，需要申请“ohos.permission.POWER_MANAGER”权限。
325
326**系统能力：** SystemCapability.PowerManager.PowerManager.Core
327
328**参数：**
329
330| 参数名    | 类型     | 必填   | 说明    |
331| ------ | ------ | ---- | ----- |
332| clearMemory | boolean | 是    | true 代表在进入休眠之前清理内存，否则为false。 |
333
334**错误码：**
335
336以下错误码的详细介绍请参见[系统电源管理错误码](errorcode-power.md)和[通用错误码](../errorcode-universal.md)。
337
338| 错误码ID   | 错误信息    |
339|---------|---------|
340| 4900101 | Failed to connect to the service. |
341| 201     | Permission verification failed. The application does not have the permission required to call the API. |
342| 202     | Permission verification failed. A non-system application calls a system API.  |
343| 401     | Parameter error. Possible causes: 1.Incorrect parameter types. |
344
345**示例：**
346
347```js
348try {
349    power.hibernate(true);
350} catch(err) {
351    console.error('hibernate failed, err: ' + err);
352}
353```
354
355## power.refreshActivity<sup>20+</sup>
356
357refreshActivity(reason: string): void
358
359刷新设备活动状态（如：重设屏幕超时息屏时间等）。
360只有设备在活动状态下生效，设备活动状态见[power.isActive](js-apis-power.md#powerisactive9)接口。
361
362**系统接口：** 此接口为系统接口。
363
364**需要权限：** ohos.permission.REFRESH_USER_ACTION
365
366**系统能力：** SystemCapability.PowerManager.PowerManager.Core
367
368**参数：**
369
370| 参数名    | 类型     | 必填   | 说明    |
371| ------ | ------ | ---- | ----- |
372| reason | string | 是    | 刷新设备活动状态的原因。该参数必须为字符串类型。 |
373
374**错误码：**
375
376以下错误码的详细介绍请参见[系统电源管理错误码](errorcode-power.md)和[通用错误码](../errorcode-universal.md)。
377
378| 错误码ID   | 错误信息    |
379|---------|---------|
380| 4900101 | Failed to connect to the service. |
381| 4900201 |The device activity is being refreshed too frequently; the minimum time interval is 100 ms. |
382| 201     | Permission verification failed. The application does not have the permission required to call the API. |
383| 202     | Permission verification failed. A non-system application calls a system API.  |
384
385**示例：**
386
387```js
388try {
389    power.refreshActivity('refreshActivity_test');
390} catch(err) {
391    console.error('refreshActivity failed, err: ' + err);
392}
393```