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