1# @ohos.power (系统电源管理) 2 3该模块主要提供重启、关机、查询屏幕状态等接口。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 12import power from '@ohos.power'; 13``` 14 15## power.shutdown 16 17shutdown(reason: string): void 18 19系统关机。 20 21**系统接口：** 此接口为系统接口。 22 23**需要权限：** ohos.permission.REBOOT 24 25**系统能力：** SystemCapability.PowerManager.PowerManager.Core 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------ | ------ | ---- | ----- | 31| reason | string | 是 | 关机原因。 | 32 33**错误码：** 34 35以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 36 37| 错误码ID | 错误信息 | 38|---------|---------| 39| 4900101 | If connecting to the service failed. | 40 41**示例：** 42 43```js 44try { 45 power.shutdown('shutdown_test'); 46} catch(err) { 47 console.error('shutdown failed, err: ' + err); 48} 49``` 50 51## power.reboot<sup>9+</sup> 52 53reboot(reason: string): void 54 55重启设备。 56 57**系统接口：** 此接口为系统接口。 58 59**需要权限：** ohos.permission.REBOOT 60 61**系统能力：** SystemCapability.PowerManager.PowerManager.Core 62 63**参数：** 64 65| 参数名 | 类型 | 必填 | 说明 | 66| ------ | ------ | ---- | ---------- | 67| reason | string | 是 | 重启原因。 | 68 69**错误码：** 70 71以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 72 73| 错误码ID | 错误信息 | 74|---------|---------| 75| 4900101 | If connecting to the service failed. | 76 77**示例：** 78 79```js 80try { 81 power.reboot('reboot_test'); 82} catch(err) { 83 console.error('reboot failed, err: ' + err); 84} 85``` 86 87## power.isActive<sup>9+</sup> 88 89isActive(): boolean 90 91检测当前设备是否处于活动状态。有屏的设备为亮屏状态，无屏的设备为非休眠状态。 92 93**系统能力：** SystemCapability.PowerManager.PowerManager.Core 94 95**错误码：** 96 97以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 98 99| 错误码ID | 错误信息 | 100|---------|---------| 101| 4900101 | If connecting to the service failed. | 102 103**示例：** 104 105```js 106try { 107 let isActive = power.isActive(); 108 console.info('power is active: ' + isActive); 109} catch(err) { 110 console.error('check active status failed, err: ' + err); 111} 112``` 113 114## power.wakeup<sup>9+</sup> 115 116wakeup(detail: string): void 117 118唤醒设备。 119 120**系统接口：** 此接口为系统接口。 121 122**系统能力：** SystemCapability.PowerManager.PowerManager.Core 123 124**参数：** 125 126| 参数名 | 类型 | 必填 | 说明 | 127| ------ | ------ | ---- | ---------- | 128| detail | string | 是 | 唤醒原因。 | 129 130**错误码：** 131 132以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 133 134| 错误码ID | 错误信息 | 135|---------|---------| 136| 4900101 | If connecting to the service failed. | 137 138**示例：** 139 140```js 141try { 142 power.wakeup('wakeup_test'); 143} catch(err) { 144 console.error('wakeup failed, err: ' + err); 145} 146``` 147 148## power.suspend<sup>9+</sup> 149 150suspend(isImmediate?: boolean): void 151 152休眠设备。 153 154**系统接口：** 此接口为系统接口。 155 156**系统能力：** SystemCapability.PowerManager.PowerManager.Core 157 158**参数：** 159 160| 参数名 | 类型 | 必填 | 说明 | 161| ------ | ------ | ---- | ---------- | 162| isImmediate<sup>10+</sup> | boolean | 否 | 是否直接休眠设备。不填该参数则默认为false由系统自动检测何时进入休眠。<br>**说明：** 从API version 10开始，支持该参数。| 163 164 165**错误码：** 166 167以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 168 169| 错误码ID | 错误信息 | 170|---------|---------| 171| 4900101 | If connecting to the service failed. | 172 173**示例：** 174 175```js 176try { 177 power.suspend(); 178} catch(err) { 179 console.error('suspend failed, err: ' + err); 180} 181``` 182 183## power.getPowerMode<sup>9+</sup> 184 185getPowerMode(): DevicePowerMode 186 187获取当前设备的电源模式。 188 189**系统能力：** SystemCapability.PowerManager.PowerManager.Core 190 191**返回值：** 192 193| 类型 | 说明 | 194| ------------------------------------ | ---------- | 195| [DevicePowerMode](#devicepowermode9) | 电源模式。 | 196 197**错误码：** 198 199以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 200 201| 错误码ID | 错误信息 | 202|---------|---------| 203| 4900101 | If connecting to the service failed. | 204 205**示例：** 206 207```js 208try { 209 let mode = power.getPowerMode(); 210 console.info('power mode: ' + mode); 211} catch(err) { 212 console.error('get power mode failed, err: ' + err); 213} 214``` 215 216## power.setPowerMode<sup>9+</sup> 217 218setPowerMode(mode: DevicePowerMode, callback: AsyncCallback<void>): void 219 220设置当前设备的电源模式。使用callback异步回调。 221 222**系统接口：** 此接口为系统接口。 223 224**需要权限：** ohos.permission.POWER_OPTIMIZATION 225 226**系统能力：** SystemCapability.PowerManager.PowerManager.Core 227 228**参数：** 229 230| 参数名 | 类型 | 必填 | 说明 | 231| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ | 232| mode | [DevicePowerMode](#devicepowermode9) | 是 | 电源模式。 | 233| callback | AsyncCallback<void> | 是 | 回调函数。当设置电源模式成功，err为undefined，否则为错误对象。 | 234 235**错误码：** 236 237以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 238 239| 错误码ID | 错误信息 | 240|---------|---------| 241| 4900101 | If connecting to the service failed. | 242 243**示例：** 244 245```js 246power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE, (err: Error) => { 247 if (typeof err === 'undefined') { 248 console.info('set power mode to MODE_PERFORMANCE'); 249 } else { 250 console.error('set power mode failed, err: ' + err); 251 } 252}); 253``` 254 255## power.setPowerMode<sup>9+</sup> 256 257setPowerMode(mode: DevicePowerMode): Promise<void> 258 259设置当前设备的电源模式。使用Promise异步回调。 260 261**系统接口：** 此接口为系统接口。 262 263**需要权限：** ohos.permission.POWER_OPTIMIZATION 264 265**系统能力：** SystemCapability.PowerManager.PowerManager.Core 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| ------ | ------------------------------------ | ---- | ---------- | 271| mode | [DevicePowerMode](#devicepowermode9) | 是 | 电源模式。 | 272 273**返回值：** 274 275| 类型 | 说明 | 276| ------------------- | -------------------------------------- | 277| Promise<void> | Promise对象。无返回结果的Promise对象。 | 278 279**错误码：** 280 281以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 282 283| 错误码ID | 错误信息 | 284|---------|---------| 285| 4900101 | If connecting to the service failed. | 286 287**示例：** 288 289```js 290power.setPowerMode(power.DevicePowerMode.MODE_PERFORMANCE) 291.then(() => { 292 console.info('set power mode to MODE_PERFORMANCE'); 293}) 294.catch((err : Error)=> { 295 console.error('set power mode failed, err: ' + err); 296}); 297``` 298 299## power.isStandby<sup>10+</sup> 300 301isStandby(): boolean 302 303检测当前设备是否进入待机低功耗续航模式。 304 305**系统能力：** SystemCapability.PowerManager.PowerManager.Core 306 307**返回值：** 308 309| 类型 | 说明 | 310| ------------------- | -------------------------------------- | 311| boolean | 进入待机模式返回true，否则返回false。 | 312 313**错误码：** 314 315以下错误码的详细介绍请参见[系统电源管理错误码](../errorcodes/errorcode-power.md)。 316 317| 错误码ID | 错误信息 | 318|---------|---------| 319| 4900101 | If connecting to the service failed. | 320 321**示例：** 322 323```js 324try { 325 let isStandby = power.isStandby(); 326 console.info('device is in standby: ' + isStandby); 327} catch(err) { 328 console.error('check isStandby failed, err: ' + err); 329} 330``` 331 332## power.rebootDevice<sup>(deprecated)</sup> 333 334rebootDevice(reason: string): void 335 336> **说明：**<br>从API version 7开始支持，从API version 9开始不再维护。建议使用[power.reboot](#powerreboot9)替代，替代接口能力仅对系统应用开放。 337 338重启设备。 339 340**需要权限：** ohos.permission.REBOOT，仅对系统应用开放。 341 342**系统能力：** SystemCapability.PowerManager.PowerManager.Core 343 344**参数：** 345 346| 参数名 | 类型 | 必填 | 说明 | 347| ------ | ------ | ---- | ----- | 348| reason | string | 是 | 重启原因。 | 349 350**示例：** 351 352```js 353power.rebootDevice('reboot_test'); 354``` 355 356## power.isScreenOn<sup>(deprecated)</sup> 357 358isScreenOn(callback: AsyncCallback<boolean>): void 359 360> **说明：**<br>从API version 9开始不再维护，建议使用[power.isActive](#powerisactive9)替代。 361 362检测当前设备的亮灭屏状态。使用callback异步回调。 363 364**系统能力：** SystemCapability.PowerManager.PowerManager.Core 365 366**参数：** 367 368| 参数名 | 类型 | 必填 | 说明 | 369| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 370| callback | AsyncCallback<boolean> | 是 | 回调函数。当检测成功，err为undefined，data为获取到的亮灭屏状态，返回true表示亮屏，返回false表示灭屏；否则为错误对象。 | 371 372**示例：** 373 374```js 375power.isScreenOn((err: Error, data: boolean) => { 376 if (typeof err === 'undefined') { 377 console.info('screen on status is ' + data); 378 } else { 379 console.error('check screen status failed, err: ' + err); 380 } 381}) 382``` 383 384## power.isScreenOn<sup>(deprecated)</sup> 385 386isScreenOn(): Promise<boolean> 387 388> **说明：**<br>从API version 9开始不再维护，建议使用[power.isActive](#powerisactive9)替代。 389 390检测当前设备的亮灭屏状态。使用Promise异步回调。 391 392**系统能力：** SystemCapability.PowerManager.PowerManager.Core 393 394**返回值：** 395| 类型 | 说明 | 396| ---------------------- | -------------------------------------------------- | 397| Promise<boolean> | Promise对象。返回true表示亮屏；返回false表示灭屏。 | 398 399**示例：** 400 401```js 402power.isScreenOn() 403.then((data: boolean) => { 404 console.info('screen on status is ' + data); 405}) 406.catch((err: { code: number, message: string }) => { 407 console.error('check screen status failed, err: ' + err); 408}) 409``` 410 411## DevicePowerMode<sup>9+</sup> 412 413表示电源模式的枚举值。 414 415**系统能力：** SystemCapability.PowerManager.PowerManager.Core 416 417| 名称 | 值 | 说明 | 418| ----------------------- | ---- | ---------------------- | 419| MODE_NORMAL | 600 | 表示标准模式，默认值。 | 420| MODE_POWER_SAVE | 601 | 表示省电模式。 | 421| MODE_PERFORMANCE | 602 | 表示性能模式。 | 422| MODE_EXTREME_POWER_SAVE | 603 | 表示超级省电模式。 | 423