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 '@kit.BasicServicesKit'; 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 '@kit.BasicServicesKit'; 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 '@kit.BasicServicesKit'; 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 '@kit.BasicServicesKit'; 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 '@kit.BasicServicesKit'; 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 import { BusinessError } from '@kit.BasicServicesKit'; 294 295 try { 296 let isSuccess = screenLock.onSystemEvent((event: screenLock.SystemEvent) => { 297 console.log(`Succeeded in Registering the system event which related to screenlock. eventType: ${event.eventType}`) 298 }); 299 } catch (err) { 300 let error = err as BusinessError; 301 console.error(`Failed to register the system event which related to screenlock, Code: ${error.code}, message: ${error.message}`) 302 } 303 ``` 304 305## screenLock.sendScreenLockEvent<sup>9+</sup> 306 307sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void 308 309应用发送事件到锁屏服务，仅支持锁屏应用使用。使用callback异步回调。 310 311**系统能力：** SystemCapability.MiscServices.ScreenLock 312 313**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 314 315**系统接口**：此接口为系统接口。 316 317**参数：** 318 319| 参数名 | 类型 | 必填 | 说明 | 320| --------- | ------------------------ | ---- |-------------------------------------------------------------------------------------------------------------------| 321| event | String | 是 | 事件类型，支持如下取值：<br/>- "unlockScreenResult"，表示解锁结果。<br/>- "lockScreenResult"，表示锁屏结果。<br/>- "screenDrawDone"，表示屏幕绘制完成。 | 322| parameter | number | 是 | 事件结果。<br/>- parameter为0，表示成功。例如解锁成功或锁屏成功。<br/>- parameter为1，表示失败。例如解锁失败或锁屏失败。<br/>- parameter为2，表示取消。例如锁屏取消或解锁取消。 | 323| callback | AsyncCallback\<boolean> | 是 | 回调函数。返回true表示发送事件成功；返回false表示发送事件失败。 | 324 325**错误码**： 326 327以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 328 329| 错误码ID | 错误信息 | 330| -------- | ---------------------------------------- | 331| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 332| 201 | permission denied. | 333| 202 | permission verification failed, application which is not a system application uses system API. | 334| 13200002 |the screenlock management service is abnormal. | 335 336**示例：** 337 338 ```ts 339 import { BusinessError } from '@kit.BasicServicesKit'; 340 341 screenLock.sendScreenLockEvent('unlockScreenResult', 0, (err: BusinessError, result: Boolean) => { 342 if (err) { 343 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 344 return; 345 } 346 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 347 }); 348 ``` 349 350## screenLock.sendScreenLockEvent<sup>9+</sup> 351 352sendScreenLockEvent(event: String, parameter: number): Promise<boolean> 353 354应用发送事件到锁屏服务，仅支持锁屏应用使用。使用Promise异步回调。 355 356**系统能力：** SystemCapability.MiscServices.ScreenLock 357 358**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 359 360**系统接口**：此接口为系统接口。 361 362**参数：** 363 364| 参数名 | 类型 | 必填 | 说明 | 365| --------- | ------ | ---- |-------------------------------------------------------------------------------------------------------------------| 366| event | String | 是 | 事件类型，支持如下取值：<br/>- "unlockScreenResult"，表示解锁结果。<br/>- "lockScreenResult"，表示锁屏结果。<br/>- "screenDrawDone"，表示屏幕绘制完成。 | 367| parameter | number | 是 | 事件结果。<br/>- parameter为0，表示成功。例如解锁成功或锁屏成功。<br/>- parameter为1，表示失败。例如解锁失败或锁屏失败。<br/>- parameter为2，表示取消。例如锁屏取消或解锁取消。 | 368 369**返回值：** 370 371| 类型 | 说明 | 372| ----------------- | ---------------------------------------------- | 373| Promise\<boolean> | Promise对象。返回true表示发送事件成功；返回false表示发送事件失败。 | 374 375**错误码**： 376 377以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和见[锁屏服务错误码](errorcode-screenlock.md)。 378 379| 错误码ID | 错误信息 | 380| -------- | ---------------------------------------- | 381| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 382| 201 | permission denied. | 383| 202 | permission verification failed, application which is not a system application uses system API. | 384| 13200002 | the screenlock management service is abnormal. | 385 386**示例：** 387 388 ```ts 389 import { BusinessError } from '@kit.BasicServicesKit'; 390 391 screenLock.sendScreenLockEvent('unlockScreenResult', 0).then((result: Boolean) => { 392 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 393 }).catch((err: BusinessError) => { 394 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 395 }); 396 ``` 397 398