js-apis-power.md 10.2 KB
Newer Older
1
# @ohos.power (系统电源管理)
Z
zengyawen 已提交
2

3 4
该模块主要提供重启、关机、查询屏幕状态等接口。

5 6
> **说明:**
>
Z
zengyawen 已提交
7
> 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
Z
zengyawen 已提交
8

Z
zengyawen 已提交
9
## 导入模块
Z
zengyawen 已提交
10

A
aqxyjay 已提交
11
```js
Z
zengyawen 已提交
12 13 14
import power from '@ohos.power';
```

A
aqxyjay 已提交
15
## power.shutdown
Z
zengyawen 已提交
16

A
aqxyjay 已提交
17
shutdown(reason: string): void
Z
zengyawen 已提交
18 19 20

系统关机。

A
aqxyjay 已提交
21
**系统接口:** 此接口为系统接口。
Z
zengyawen 已提交
22

H
hujun211 已提交
23
**需要权限:** ohos.permission.REBOOT
Z
zengyawen 已提交
24

25 26
**系统能力:** SystemCapability.PowerManager.PowerManager.Core

Z
zengyawen 已提交
27
**参数:**
Z
zengyawen 已提交
28

H
hujun211 已提交
29 30 31
| 参数名    | 类型     | 必填   | 说明    |
| ------ | ------ | ---- | ----- |
| reason | string | 是    | 关机原因。 |
Z
zengyawen 已提交
32

A
aqxyjay 已提交
33 34 35 36 37 38 39 40
**错误码:**

以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)

| 错误码ID   | 错误信息    |
|---------|---------|
| 4900101 | 连接服务失败。 |

Z
zengyawen 已提交
41 42
**示例:**

A
aqxyjay 已提交
43
```js
A
aqxyjay 已提交
44 45 46 47 48
try {
    power.shutdown('shutdown_test');
} catch(err) {
    console.error('shutdown failed, err: ' + err);
}
Z
zengyawen 已提交
49
```
Z
zengyawen 已提交
50

A
aqxyjay 已提交
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
## power.reboot<sup>9+</sup>

reboot(reason: string): void

重启设备。

**系统接口:** 此接口为系统接口。

**需要权限:** ohos.permission.REBOOT

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

**参数:**

| 参数名 | 类型   | 必填 | 说明       |
| ------ | ------ | ---- | ---------- |
| reason | string | 是   | 重启原因。 |

**错误码:**
Z
zengyawen 已提交
70

A
aqxyjay 已提交
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)

| 错误码ID   | 错误信息    |
|---------|---------|
| 4900101 | 连接服务失败。 |

**示例:**

```js
try {
    power.reboot('reboot_test');
} catch(err) {
    console.error('reboot failed, err: ' + err);
}
```

## power.isActive<sup>9+</sup>
88

A
aqxyjay 已提交
89
isActive(): boolean
90

Z
zblue 已提交
91
检测当前设备是否处于活动状态。有屏的设备为亮屏状态,无屏的设备为非休眠状态。
92 93 94

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

A
aqxyjay 已提交
95
**错误码:**
96

A
aqxyjay 已提交
97 98 99 100 101
以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)

| 错误码ID   | 错误信息    |
|---------|---------|
| 4900101 | 连接服务失败。 |
102 103 104 105

**示例:**

```js
A
aqxyjay 已提交
106 107
try {
    var isActive = power.isActive();
A
aqxyjay 已提交
108
    console.info('power is active: ' + isActive);
A
aqxyjay 已提交
109 110 111
} catch(err) {
    console.error('check active status failed, err: ' + err);
}
112 113
```

A
aqxyjay 已提交
114
## power.wakeup<sup>9+</sup>
115

A
aqxyjay 已提交
116
wakeup(detail: string): void
117

A
aqxyjay 已提交
118
唤醒设备。
119

A
aqxyjay 已提交
120
**系统接口:** 此接口为系统接口。
121 122 123

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

A
aqxyjay 已提交
124 125 126 127 128 129 130 131 132 133 134 135 136 137
**参数:**

| 参数名 | 类型   | 必填 | 说明       |
| ------ | ------ | ---- | ---------- |
| detail | string | 是   | 唤醒原因。 |

**错误码:**

以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)

| 错误码ID   | 错误信息    |
|---------|---------|
| 4900101 | 连接服务失败。 |

138 139 140
**示例:**

```js
A
aqxyjay 已提交
141 142 143 144 145
try {
    power.wakeup('wakeup_test');
} catch(err) {
    console.error('wakeup failed, err: ' + err);
}
146 147
```

A
aqxyjay 已提交
148
## power.suspend<sup>9+</sup>
149

Y
yangziyong 已提交
150
suspend(isImmediate?: boolean): void
151

A
aqxyjay 已提交
152
休眠设备。
153

A
aqxyjay 已提交
154
**系统接口:** 此接口为系统接口。
155 156 157

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

Y
yangziyong 已提交
158 159 160 161 162 163 164
**参数:**

| 参数名 | 类型   | 必填 | 说明       |
| ------ | ------ | ---- | ---------- |
| isImmediate<sup>10+</sup> | boolean |  否  | 是否直接休眠设备。不填该参数则默认为false由系统自动检测何时进入休眠。<br>**说明:** 从API version 10开始,支持该参数。|


A
aqxyjay 已提交
165
**错误码:**
166

A
aqxyjay 已提交
167 168 169 170 171
以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)

| 错误码ID   | 错误信息    |
|---------|---------|
| 4900101 | 连接服务失败。 |
172 173 174 175

**示例:**

```js
A
aqxyjay 已提交
176
try {
A
aqxyjay 已提交
177
    power.suspend();
A
aqxyjay 已提交
178
} catch(err) {
A
aqxyjay 已提交
179
    console.error('suspend failed, err: ' + err);
A
aqxyjay 已提交
180
}
181 182 183 184
```

## power.getPowerMode<sup>9+</sup>

A
aqxyjay 已提交
185
getPowerMode(): DevicePowerMode
186 187 188 189 190 191 192

获取当前设备的电源模式。

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

**返回值:**

A
aqxyjay 已提交
193 194 195 196 197 198 199 200 201 202 203
| 类型                                 | 说明       |
| ------------------------------------ | ---------- |
| [DevicePowerMode](#devicepowermode9) | 电源模式。 |

**错误码:**

以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)

| 错误码ID   | 错误信息    |
|---------|---------|
| 4900101 | 连接服务失败。 |
204 205 206 207

**示例:**

```js
A
aqxyjay 已提交
208 209
try {
    var mode = power.getPowerMode();
A
aqxyjay 已提交
210
    console.info('power mode: ' + mode);
A
aqxyjay 已提交
211 212 213
} catch(err) {
    console.error('get power mode failed, err: ' + err);
}
214 215 216 217
```

## power.setPowerMode<sup>9+</sup>

A
aqxyjay 已提交
218
setPowerMode(mode: DevicePowerMode, callback: AsyncCallback&lt;void&gt;): void
219

A
aqxyjay 已提交
220
设置当前设备的电源模式。使用callback异步回调。
221

A
aqxyjay 已提交
222
**系统接口:** 此接口为系统接口。
223 224 225 226 227 228 229

**需要权限:** ohos.permission.POWER_OPTIMIZATION

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

**参数:**

A
aqxyjay 已提交
230 231 232 233 234 235 236 237 238 239 240 241
| 参数名   | 类型                                 | 必填 | 说明                                                         |
| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
| mode     | [DevicePowerMode](#devicepowermode9) | 是   | 电源模式。                                                   |
| callback | AsyncCallback&lt;void&gt;            | 是   | 回调函数。当设置电源模式成功,err为undefined,否则为错误对象。 |

**错误码:**

以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)

| 错误码ID   | 错误信息    |
|---------|---------|
| 4900101 | 连接服务失败。 |
242 243 244 245

**示例:**

```js
A
aqxyjay 已提交
246 247 248 249 250 251 252
power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, err => {
    if (typeof err === 'undefined') {
        console.info('set power mode to MODE_PERFORMANCE');
    } else {
        console.error('set power mode failed, err: ' + err);
    }
});
253 254 255 256 257 258
```

## power.setPowerMode<sup>9+</sup>

setPowerMode(mode: DevicePowerMode): Promise&lt;void&gt;

A
aqxyjay 已提交
259
设置当前设备的电源模式。使用Promise异步回调。
260

A
aqxyjay 已提交
261
**系统接口:** 此接口为系统接口。
262 263 264 265 266 267 268 269 270 271 272 273 274

**需要权限:** ohos.permission.POWER_OPTIMIZATION

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

**参数:**

| 参数名 | 类型                                 | 必填 | 说明       |
| ------ | ------------------------------------ | ---- | ---------- |
| mode   | [DevicePowerMode](#devicepowermode9) | 是   | 电源模式。 |

**返回值:**

A
aqxyjay 已提交
275 276 277 278 279 280 281 282 283 284 285
| 类型                | 说明                                   |
| ------------------- | -------------------------------------- |
| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |

**错误码:**

以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)

| 错误码ID   | 错误信息    |
|---------|---------|
| 4900101 | 链接服务失败。 |
286 287 288 289

**示例:**

```js
A
aqxyjay 已提交
290 291 292 293 294
power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE)
.then(() => {
    console.info('set power mode to MODE_PERFORMANCE');
})
.catch(err => {
A
aqxyjay 已提交
295
    console.error('set power mode failed, err: ' + err);
A
aqxyjay 已提交
296 297 298 299 300 301 302
});
```

## power.rebootDevice<sup>(deprecated)</sup>

rebootDevice(reason: string): void

Z
zengyawen 已提交
303
> **说明:**<br>从API version 7开始支持,从API version 9开始不再维护。建议使用[power.reboot](#powerreboot9)替代,替代接口能力仅对系统应用开放。
A
aqxyjay 已提交
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326

重启设备。

**需要权限:** ohos.permission.REBOOT

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

**参数:**

| 参数名    | 类型     | 必填   | 说明    |
| ------ | ------ | ---- | ----- |
| reason | string | 是    | 重启原因。 |

**示例:**

```js
power.rebootDevice('reboot_test');
```

## power.isScreenOn<sup>(deprecated)</sup>

isScreenOn(callback: AsyncCallback&lt;boolean&gt;): void

Z
zengyawen 已提交
327
> **说明:**<br>从API version 9开始不再维护,建议使用[power.isActive](#powerisactive9)替代。
A
aqxyjay 已提交
328 329 330 331 332 333 334 335 336

检测当前设备的亮灭屏状态。使用callback异步回调。

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

**参数:**

| 参数名   | 类型                         | 必填 | 说明                                                         |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
337
| callback | AsyncCallback&lt;boolean&gt; | 是   | 回调函数。当检测成功,err为undefined,data为获取到的亮灭屏状态,返回true表示亮屏,返回false表示灭屏;否则为错误对象。 |
A
aqxyjay 已提交
338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354

**示例:**

```js
power.isScreenOn((err, data) => {
    if (typeof err === 'undefined') {
        console.info('screen on status is ' + data);
    } else {
        console.error('check screen status failed, err: ' + err);
    }
})
```

## power.isScreenOn<sup>(deprecated)</sup>

isScreenOn(): Promise&lt;boolean&gt;

Z
zengyawen 已提交
355
> **说明:**<br>从API version 9开始不再维护,建议使用[power.isActive](#powerisactive9)替代。
A
aqxyjay 已提交
356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375

检测当前设备的亮灭屏状态。使用Promise异步回调。

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

**返回值:**
| 类型                   | 说明                                               |
| ---------------------- | -------------------------------------------------- |
| Promise&lt;boolean&gt; | Promise对象。返回true表示亮屏;返回false表示灭屏。 |

**示例:**

```js
power.isScreenOn()
.then(data => {
    console.info('screen on status is ' + data);
})
.catch(err => {
    console.error('check screen status failed, err: ' + err);
})
376 377 378 379 380 381 382 383
```

## DevicePowerMode<sup>9+</sup>

表示电源模式的枚举值。

**系统能力:** SystemCapability.PowerManager.PowerManager.Core

A
aqxyjay 已提交
384 385 386 387 388 389
| 名称                    | 值   | 说明                   |
| ----------------------- | ---- | ---------------------- |
| MODE_NORMAL             | 600  | 表示标准模式,默认值。 |
| MODE_POWER_SAVE         | 601  | 表示省电模式。         |
| MODE_PERFORMANCE        | 602  | 表示性能模式。         |
| MODE_EXTREME_POWER_SAVE | 603  | 表示超级省电模式。     |