1# @ohos.screenLock (锁屏管理)（系统接口） 2 3锁屏管理服务是OpenHarmony中的系统服务，为锁屏应用提供注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听，并提供回调结果给锁屏应用。锁屏管理服务向三方应用提供请求解锁、查询锁屏状态、查询是否设置锁屏密码的能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9>当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.screenLock (锁屏管理)](js-apis-screen-lock.md)。 10 11## 导入模块 12 13```ts 14import screenLock from '@ohos.screenLock'; 15``` 16 17## EventType<sup>9+</sup> 18 19定义系统事件类型。 20 21**系统能力：** SystemCapability.MiscServices.ScreenLock 22 23**系统接口**：此接口为系统接口。 24 25| 事件类型 | 说明 | 26| ------------------ | ------------------------ | 27| beginWakeUp | 表示设备开始唤醒。 | 28| endWakeUp | 表示设备结束唤醒。 | 29| beginScreenOn | 表示设备开始亮屏。 | 30| endScreenOn | 表示设备结束亮屏。 | 31| beginScreenOff | 表示设备开始灭屏。 | 32| endScreenOff | 表示设备结束灭屏。 | 33| unlockScreen | 表示请求屏幕解锁。 | 34| lockScreen | 表示请求屏幕锁定。 | 35| beginExitAnimation | 表示开始退场动画。 | 36| beginSleep | 表示设备开始休眠。 | 37| endSleep | 表示设备结束休眠。 | 38| changeUser | 表示切换用户。 | 39| screenlockEnabled | 表示锁屏是否启用。 | 40| serviceRestart | 表示锁屏服务进行重启。 | 41 42## SystemEvent<sup>9+</sup> 43 44定义系统事件回调参数结构。 45 46**系统能力：** SystemCapability.MiscServices.ScreenLock 47 48**系统接口**：此接口为系统接口 49 50| 名称 | 类型 | 必填 | 说明 | 51| --------- | ------ | ---- | ------------- | 52| eventType | [EventType](#eventtype9) | 是 | 系统事件类型。 | 53| params | string | 是 | 系统事件参数。 | 54 55## screenLock.isLocked<sup>9+</sup> 56 57isLocked(): boolean 58 59判断屏幕是否锁屏。 60 61**系统能力：** SystemCapability.MiscServices.ScreenLock 62 63**系统接口**：此接口为系统接口 64 65**返回值：** 66 67| 类型 | 说明 | 68| ------- | ------------------------------------------------- | 69| boolean | 返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | 70 71**错误码**： 72 73以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 74 75| 错误码ID | 错误信息 | 76| -------- | ---------------------------------------- | 77| 202 | permission verification failed, application which is not a system application uses system API. | 78 79**示例：** 80 81```ts 82let isLocked = screenLock.isLocked(); 83``` 84 85## screenLock.unlock<sup>9+</sup> 86 87unlock(callback: AsyncCallback<boolean>): void 88 89解锁屏幕。使用callback异步回调。 90 91**系统能力：** SystemCapability.MiscServices.ScreenLock 92 93**系统接口**：此接口为系统接口 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| -------- | --------------------- | ---- | ------------------------- | 99| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕解锁成功；返回false表示取消解锁。 | 100 101**错误码**： 102 103以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 104 105| 错误码ID | 错误信息 | 106| -------- | ---------------------------------------- | 107| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 108| 202 | permission verification failed, application which is not a system application uses system API. | 109| 13200002 | the screenlock management service is abnormal. | 110| 13200003 | illegal use. | 111 112**示例：** 113 114 ```ts 115 import { BusinessError } from '@ohos.base'; 116 117 screenLock.unlock((err: BusinessError, data: Boolean) => { 118 if (err) { 119 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 120 return; 121 } 122 console.info(`Succeeded in unlocking the screen. result: ${data}`); 123 }); 124 ``` 125 126> **说明：** 127> 128> 在 api11 中 增加错误码`13200003 illegal use` 。 129 130## screenLock.unlock<sup>9+</sup> 131 132unlock(): Promise<boolean> 133 134解锁屏幕。使用Promise异步回调。 135 136**系统能力：** SystemCapability.MiscServices.ScreenLock 137 138**系统接口**：此接口为系统接口 139 140**返回值：** 141 142| 类型 | 说明 | 143| ------------------- | ------------------------------------------------------------ | 144| Promise<boolean> | Promise对象。返回true表示屏幕解锁成功；返回false表示取消解锁。 | 145 146**错误码**： 147 148以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 149 150| 错误码ID | 错误信息 | 151| -------- | ---------------------------------------- | 152| 202 | permission verification failed, application which is not a system application uses system API. | 153| 13200002 | the screenlock management service is abnormal. | 154| 13200003 | illegal use. | 155 156**示例：** 157 158 ```ts 159 import { BusinessError } from '@ohos.base'; 160 161 screenLock.unlock().then((data: Boolean) => { 162 console.info(`Succeeded in unlocking the screen. result: ${data}`); 163 }).catch((err: BusinessError) => { 164 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 165 }); 166 ``` 167 168> **说明：** 169> 170> 在 api11 中 增加错误码`13200003 illegal use` 。 171 172## screenLock.lock<sup>9+</sup> 173 174lock(callback: AsyncCallback<boolean>): void 175 176锁定屏幕。使用callback异步回调。 177 178**系统能力：** SystemCapability.MiscServices.ScreenLock 179 180**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 181 182**系统接口**：此接口为系统接口 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| -------- | ---------------------- | ---- | ---------------- | 188| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。 | 189 190**错误码**： 191 192以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 193 194| 错误码ID | 错误信息 | 195| -------- | ---------------------------------------- | 196| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 197| 201 | permission denied. | 198| 202 | permission verification failed, application which is not a system application uses system API. | 199| 13200002 | the screenlock management service is abnormal. | 200 201**示例：** 202 203 ```ts 204 import { BusinessError } from '@ohos.base'; 205 206 screenLock.lock((err: BusinessError, data: Boolean) => { 207 if (err) { 208 console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`); 209 return; 210 } 211 console.info(`Succeeded in locking the screen. result: ${data}`); 212 }); 213 ``` 214 215## screenLock.lock<sup>9+</sup> 216 217lock(): Promise<boolean> 218 219锁定屏幕。使用Promise异步回调。 220 221**系统能力：** SystemCapability.MiscServices.ScreenLock 222 223**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 224 225**系统接口**：此接口为系统接口 226 227**返回值：** 228 229| 类型 | 说明 | 230| ---------------------- | ------------------------------------------------------------ | 231| Promise<boolean> | Promise对象。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。 | 232 233**错误码**： 234 235以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 236 237| 错误码ID | 错误信息 | 238| -------- | ---------------------------------------- | 239| 201 | permission denied. | 240| 202 | permission verification failed, application which is not a system application uses system API. | 241| 13200002 | the screenlock management service is abnormal. | 242 243**示例：** 244 245 ```ts 246 import { BusinessError } from '@ohos.base'; 247 248 screenLock.lock().then((data: Boolean) => { 249 console.info(`Succeeded in locking the screen. result: ${data}`); 250 }).catch((err: BusinessError) => { 251 console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`); 252 }); 253 ``` 254 255## screenLock.onSystemEvent<sup>9+</sup> 256 257onSystemEvent(callback: Callback<SystemEvent>): boolean 258 259注册锁屏相关的系统事件，仅支持锁屏应用使用。 260 261**系统能力：** SystemCapability.MiscServices.ScreenLock 262 263**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 264 265**系统接口**：此接口为系统接口 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| -------- | ------------------------- | ---- | ----------------- | 271| callback | Callback\<[SystemEvent](#systemevent9)> | 是 | 锁屏相关的系统事件回调函数。 | 272 273**返回值：** 274 275| 类型 | 说明 | 276| ------- | ------------------------------------------------- | 277| boolean | 返回true表示锁屏相关系统事件注册成功；返回false表示锁屏相关系统事件注册失败。 | 278 279**错误码**： 280 281以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 282 283| 错误码ID | 错误信息 | 284| -------- | ---------------------------------------- | 285| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 286| 201 | permission denied. | 287| 202 | permission verification failed, application which is not a system application uses system API. | 288| 13200002 | the screenlock management service is abnormal. | 289 290**示例：** 291 292 ```ts 293 try { 294 let isSuccess = screenLock.onSystemEvent((event: screenLock.SystemEvent) => { 295 console.log(`Succeeded in Registering the system event which related to screenlock. eventType: ${event.eventType}`) 296 }); 297 } catch (err) { 298 let error = err as BusinessError; 299 console.error(`Failed to register the system event which related to screenlock, Code: ${error.code}, message: ${error.message}`) 300 } 301 ``` 302 303## screenLock.sendScreenLockEvent<sup>9+</sup> 304 305sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void 306 307应用发送事件到锁屏服务，仅支持锁屏应用使用。使用callback异步回调。 308 309**系统能力：** SystemCapability.MiscServices.ScreenLock 310 311**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 312 313**系统接口**：此接口为系统接口 314 315**参数：** 316 317| 参数名 | 类型 | 必填 | 说明 | 318| --------- | ------------------------ | ---- | -------------------- | 319| event | String | 是 | 事件类型，支持如下取值:<br/>- "unlockScreenResult"，表示解锁结果。<br/>- "lockScreenResult"，表示锁屏结果。<br/>- "screenDrawDone"，表示屏幕绘制完成。 | 320| parameter | number | 是 | 事件结果。<br/>- parameter为0，表示成功。例如解锁成功或锁屏成功。<br/>- parameter为1，表示失败。例如解锁失败或锁屏失败。<br/>- parameter为2，表示取消。例如锁屏取消或解锁取消。 | 321| callback | AsyncCallback\<boolean> | 是 | 回调函数。返回true表示发送事件成功；返回false表示发送事件失败。 | 322 323**错误码**： 324 325以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 326 327| 错误码ID | 错误信息 | 328| -------- | ---------------------------------------- | 329| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 330| 201 | permission denied. | 331| 202 | permission verification failed, application which is not a system application uses system API. | 332| 13200002 |the screenlock management service is abnormal. | 333 334**示例：** 335 336 ```ts 337 import { BusinessError } from '@ohos.base'; 338 339 screenLock.sendScreenLockEvent('unlockScreenResult', 0, (err: BusinessError, result: Boolean) => { 340 if (err) { 341 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 342 return; 343 } 344 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 345 }); 346 ``` 347 348## screenLock.sendScreenLockEvent<sup>9+</sup> 349 350sendScreenLockEvent(event: String, parameter: number): Promise<boolean> 351 352应用发送事件到锁屏服务，仅支持锁屏应用使用。使用Promise异步回调。 353 354**系统能力：** SystemCapability.MiscServices.ScreenLock 355 356**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 357 358**系统接口**：此接口为系统接口 359 360**参数：** 361 362| 参数名 | 类型 | 必填 | 说明 | 363| --------- | ------ | ---- | --------------------------------------- | 364| event | String | 是 | 事件类型，支持如下取值:<br/>- "unlockScreenResult"，表示解锁结果。<br/>- "lockScreenResult"，表示锁屏结果。<br/>- "screenDrawDone"，表示屏幕绘制完成。 | 365| parameter | number | 是 | 事件结果。<br/>- parameter为0，表示成功。例如解锁成功或锁屏成功。<br/>- parameter为1，表示失败。例如解锁失败或锁屏失败。<br/>- parameter为2，表示取消。例如锁屏取消或解锁取消。 | 366 367**返回值：** 368 369| 类型 | 说明 | 370| ----------------- | ---------------------------------------------- | 371| Promise\<boolean> | Promise对象。返回true表示发送事件成功；返回false表示发送事件失败。 | 372 373**错误码**： 374 375以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 376 377| 错误码ID | 错误信息 | 378| -------- | ---------------------------------------- | 379| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 380| 201 | permission denied. | 381| 202 | permission verification failed, application which is not a system application uses system API. | 382| 13200002 | the screenlock management service is abnormal. | 383 384**示例：** 385 386 ```ts 387 import { BusinessError } from '@ohos.base'; 388 389 screenLock.sendScreenLockEvent('unlockScreenResult', 0).then((result: Boolean) => { 390 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 391 }).catch((err: BusinessError) => { 392 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 393 }); 394 ``` 395 396