1# @ohos.screenLock (锁屏管理) 2 3锁屏管理服务是OpenHarmony中的系统服务，为锁屏应用提供注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听，并提供回调结果给锁屏应用。锁屏管理服务向三方应用提供请求解锁、查询锁屏状态、查询是否设置锁屏密码的能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import screenLock from '@ohos.screenLock'; 13``` 14 15## EventType<sup>9+</sup> 16 17定义系统事件类型。 18 19**系统能力：** SystemCapability.MiscServices.ScreenLock 20 21**系统接口**：此接口为系统接口。 22 23| 事件类型 | 说明 | 24| ------------------ | ------------------------ | 25| beginWakeUp | 表示设备开始唤醒。 | 26| endWakeUp | 表示设备结束唤醒。 | 27| beginScreenOn | 表示设备开始亮屏。 | 28| endScreenOn | 表示设备结束亮屏。 | 29| beginScreenOff | 表示设备开始灭屏。 | 30| endScreenOff | 表示设备结束灭屏。 | 31| unlockScreen | 表示请求屏幕解锁。 | 32| lockScreen | 表示请求屏幕锁定。 | 33| beginExitAnimation | 表示开始退场动画。 | 34| beginSleep | 表示设备开始休眠。 | 35| endSleep | 表示设备结束休眠。 | 36| changeUser | 表示切换用户。 | 37| screenlockEnabled | 表示锁屏是否启用。 | 38| serviceRestart | 表示锁屏服务进行重启。 | 39 40## SystemEvent<sup>9+</sup> 41 42定义系统事件回调参数结构。 43 44**系统能力：** SystemCapability.MiscServices.ScreenLock 45 46**系统接口**：此接口为系统接口 47 48| 名称 | 类型 | 必填 | 说明 | 49| --------- | ------ | ---- | ------------- | 50| eventType | [EventType](#eventtype9) | 是 | 系统事件类型。 | 51| params | string | 是 | 系统事件参数。 | 52 53## screenLock.isLocked<sup>9+</sup> 54 55isLocked(): boolean 56 57判断屏幕是否锁屏。 58 59**系统能力：** SystemCapability.MiscServices.ScreenLock 60 61**系统接口**：此接口为系统接口 62 63**返回值：** 64 65| 类型 | 说明 | 66| ------- | ------------------------------------------------- | 67| boolean | 返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | 68 69**示例：** 70 71```ts 72let isLocked = screenLock.isLocked(); 73``` 74 75## screenLock.unlock<sup>9+</sup> 76 77unlock(callback: AsyncCallback<boolean>): void 78 79解锁屏幕。使用callback异步回调。 80 81**系统能力：** SystemCapability.MiscServices.ScreenLock 82 83**系统接口**：此接口为系统接口 84 85**参数：** 86 87| 参数名 | 类型 | 必填 | 说明 | 88| -------- | --------------------- | ---- | ------------------------- | 89| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕解锁成功；返回false表示取消解锁。 | 90 91**错误码**： 92 93以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 94 95| 错误码ID | 错误信息 | 96| -------- | ---------------------------------------- | 97| 13200002 | the screenlock management service is abnormal. | 98 99**示例：** 100 101 ```ts 102 import { BusinessError } from '@ohos.base'; 103 104 screenLock.unlock((err: BusinessError, data: Boolean) => { 105 if (err) { 106 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 107 return; 108 } 109 console.info(`Succeeded in unlocking the screen. result: ${data}`); 110 }); 111 ``` 112 113## screenLock.unlock<sup>9+</sup> 114 115unlock(): Promise<boolean> 116 117解锁屏幕。使用Promise异步回调。 118 119**系统能力：** SystemCapability.MiscServices.ScreenLock 120 121**系统接口**：此接口为系统接口 122 123**返回值：** 124 125| 类型 | 说明 | 126| ------------------- | ------------------------------------------------------------ | 127| Promise<boolean> | Promise对象。返回true表示屏幕解锁成功；返回false表示取消解锁。 | 128 129**错误码**： 130 131以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 132 133| 错误码ID | 错误信息 | 134| -------- | ---------------------------------------- | 135| 13200002 | the screenlock management service is abnormal. | 136 137**示例：** 138 139 ```ts 140 import { BusinessError } from '@ohos.base'; 141 142 screenLock.unlock().then((data: Boolean) => { 143 console.info(`Succeeded in unlocking the screen. result: ${data}`); 144 }).catch((err: BusinessError) => { 145 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 146 }); 147 ``` 148 149## screenLock.lock<sup>9+</sup> 150 151lock(callback: AsyncCallback<boolean>): void 152 153锁定屏幕。使用callback异步回调。 154 155**系统能力：** SystemCapability.MiscServices.ScreenLock 156 157**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 158 159**系统接口**：此接口为系统接口 160 161**参数：** 162 163| 参数名 | 类型 | 必填 | 说明 | 164| -------- | ---------------------- | ---- | ---------------- | 165| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。 | 166 167**错误码**： 168 169以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 170 171| 错误码ID | 错误信息 | 172| -------- | ---------------------------------------- | 173| 13200002 | the screenlock management service is abnormal. | 174 175**示例：** 176 177 ```ts 178 import { BusinessError } from '@ohos.base'; 179 180 screenLock.lock((err: BusinessError, data: Boolean) => { 181 if (err) { 182 console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`); 183 return; 184 } 185 console.info(`Succeeded in locking the screen. result: ${data}`); 186 }); 187 ``` 188 189## screenLock.lock<sup>9+</sup> 190 191lock(): Promise<boolean> 192 193锁定屏幕。使用Promise异步回调。 194 195**系统能力：** SystemCapability.MiscServices.ScreenLock 196 197**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 198 199**系统接口**：此接口为系统接口 200 201**返回值：** 202 203| 类型 | 说明 | 204| ---------------------- | ------------------------------------------------------------ | 205| Promise<boolean> | Promise对象。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。 | 206 207**错误码**： 208 209以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 210 211| 错误码ID | 错误信息 | 212| -------- | ---------------------------------------- | 213| 13200002 | the screenlock management service is abnormal. | 214 215**示例：** 216 217 ```ts 218 import { BusinessError } from '@ohos.base'; 219 220 screenLock.lock().then((data: Boolean) => { 221 console.info(`Succeeded in locking the screen. result: ${data}`); 222 }).catch((err: BusinessError) => { 223 console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`); 224 }); 225 ``` 226 227## screenLock.onSystemEvent<sup>9+</sup> 228 229onSystemEvent(callback: Callback<SystemEvent>): boolean 230 231注册锁屏相关的系统事件，仅支持锁屏应用使用。 232 233**系统能力：** SystemCapability.MiscServices.ScreenLock 234 235**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 236 237**系统接口**：此接口为系统接口 238 239**参数：** 240 241| 参数名 | 类型 | 必填 | 说明 | 242| -------- | ------------------------- | ---- | ----------------- | 243| callback | Callback\<[SystemEvent](#systemevent9)> | 是 | 锁屏相关的系统事件回调函数。 | 244 245**返回值：** 246 247| 类型 | 说明 | 248| ------- | ------------------------------------------------- | 249| boolean | 返回true表示锁屏相关系统事件注册成功；返回false表示锁屏相关系统事件注册失败。 | 250 251**错误码**： 252 253以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 254 255| 错误码ID | 错误信息 | 256| -------- | ---------------------------------------- | 257| 13200002 | the screenlock management service is abnormal. | 258 259**示例：** 260 261 ```ts 262 try { 263 let isSuccess = screenLock.onSystemEvent((event: screenLock.SystemEvent) => { 264 console.log(`Succeeded in Registering the system event which related to screenlock. eventType: ${event.eventType}`) 265 }); 266 } catch (err) { 267 let error = err as BusinessError; 268 console.error(`Failed to register the system event which related to screenlock, Code: ${error.code}, message: ${error.message}`) 269 } 270 ``` 271 272## screenLock.sendScreenLockEvent<sup>9+</sup> 273 274sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void 275 276应用发送事件到锁屏服务，仅支持锁屏应用使用。使用callback异步回调。 277 278**系统能力：** SystemCapability.MiscServices.ScreenLock 279 280**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 281 282**系统接口**：此接口为系统接口 283 284**参数：** 285 286| 参数名 | 类型 | 必填 | 说明 | 287| --------- | ------------------------ | ---- | -------------------- | 288| event | String | 是 | 事件类型，支持如下取值:<br/>- "unlockScreenResult"，表示解锁结果。<br/>- "lockScreenResult"，表示锁屏结果。<br/>- "screenDrawDone"，表示屏幕绘制完成。 | 289| parameter | number | 是 | 事件结果。<br/>- parameter为0，表示成功。例如解锁成功或锁屏成功。<br/>- parameter为1，表示失败。例如解锁失败或锁屏失败。<br/>- parameter为2，表示取消。例如锁屏取消或解锁取消。 | 290| callback | AsyncCallback\<boolean> | 是 | 回调函数。返回true表示发送事件成功；返回false表示发送事件失败。 | 291 292**错误码**： 293 294以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 295 296| 错误码ID | 错误信息 | 297| -------- | ---------------------------------------- | 298| 13200002 |the screenlock management service is abnormal. | 299 300**示例：** 301 302 ```ts 303 import { BusinessError } from '@ohos.base'; 304 305 screenLock.sendScreenLockEvent('unlockScreenResult', 0, (err: BusinessError, result: Boolean) => { 306 if (err) { 307 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 308 return; 309 } 310 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 311 }); 312 ``` 313 314## screenLock.sendScreenLockEvent<sup>9+</sup> 315 316sendScreenLockEvent(event: String, parameter: number): Promise<boolean> 317 318应用发送事件到锁屏服务，仅支持锁屏应用使用。使用Promise异步回调。 319 320**系统能力：** SystemCapability.MiscServices.ScreenLock 321 322**需要权限：** ohos.permission.ACCESS_SCREEN_LOCK_INNER 323 324**系统接口**：此接口为系统接口 325 326**参数：** 327 328| 参数名 | 类型 | 必填 | 说明 | 329| --------- | ------ | ---- | --------------------------------------- | 330| event | String | 是 | 事件类型，支持如下取值:<br/>- "unlockScreenResult"，表示解锁结果。<br/>- "lockScreenResult"，表示锁屏结果。<br/>- "screenDrawDone"，表示屏幕绘制完成。 | 331| parameter | number | 是 | 事件结果。<br/>- parameter为0，表示成功。例如解锁成功或锁屏成功。<br/>- parameter为1，表示失败。例如解锁失败或锁屏失败。<br/>- parameter为2，表示取消。例如锁屏取消或解锁取消。 | 332 333**返回值：** 334 335| 类型 | 说明 | 336| ----------------- | ---------------------------------------------- | 337| Promise\<boolean> | Promise对象。返回true表示发送事件成功；返回false表示发送事件失败。 | 338 339**错误码**： 340 341以下错误码的详细介绍请参见[锁屏服务错误码](../errorcodes/errorcode-screenlock.md)。 342 343| 错误码ID | 错误信息 | 344| -------- | ---------------------------------------- | 345| 13200002 | the screenlock management service is abnormal. | 346 347**示例：** 348 349 ```ts 350 import { BusinessError } from '@ohos.base'; 351 352 screenLock.sendScreenLockEvent('unlockScreenResult', 0).then((result: Boolean) => { 353 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 354 }).catch((err: BusinessError) => { 355 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 356 }); 357 ``` 358 359## screenLock.isScreenLocked<sup>(deprecated)</sup> 360 361isScreenLocked(callback: AsyncCallback<boolean>): void 362 363判断屏幕是否锁屏。使用callback异步回调。 364 365> **说明：** 366> 367> 从API version 7开始支持，从API version 9开始废弃。 368 369**系统能力：** SystemCapability.MiscServices.ScreenLock 370 371**参数：** 372 373| 参数名 | 类型 | 必填 | 说明 | 374| -------- | ---------------------------- | ---- | ----------------------------------------------------------- | 375| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | 376 377**示例：** 378 379 ```ts 380 import { BusinessError } from '@ohos.base'; 381 382 screenLock.isScreenLocked((err: BusinessError, data: Boolean)=>{ 383 if (err) { 384 console.error(`Failed to obtain whether the screen is locked, Code: ${err.code}, message: ${err.message}`); 385 return; 386 } 387 console.info(`Succeeded in Obtaining whether the screen is locked. result: ${data}`); 388 }); 389 ``` 390 391## screenLock.isScreenLocked<sup>(deprecated)</sup> 392 393isScreenLocked(): Promise<boolean> 394 395判断屏幕是否锁屏。使用Promise异步回调。 396 397> **说明：** 398> 399> 从API version 7开始支持，从API version 9开始废弃。 400 401**系统能力：** SystemCapability.MiscServices.ScreenLock 402 403**返回值：** 404 405| 类型 | 说明 | 406| ---------------------- | ------------------------------------------- | 407| Promise<boolean> | Promise对象。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | 408 409**示例：** 410 411 ```ts 412 import { BusinessError } from '@ohos.base'; 413 414 screenLock.isScreenLocked().then((data: Boolean) => { 415 console.info(`Succeeded in Obtaining whether the screen is locked. result: ${data}`); 416 }).catch((err: BusinessError) => { 417 console.error(`Failed to obtain whether the screen is locked, Code: ${err.code}, message: ${err.message}`); 418 }); 419 ``` 420 421## screenLock.isSecureMode<sup>(deprecated)</sup> 422 423isSecureMode(callback: AsyncCallback<boolean>): void 424 425判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。使用callback异步回调。 426 427> **说明：** 428> 429> 从API version 7开始支持，从API version 9开始废弃。 430 431**系统能力：** SystemCapability.MiscServices.ScreenLock 432 433**参数：** 434 435| 参数名 | 类型 | 必填 | 说明 | 436| -------- | --------------------- | ---- | ------------------------ | 437| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。 | 438 439**示例：** 440 441 ```ts 442 import { BusinessError } from '@ohos.base'; 443 444 screenLock.isSecureMode((err: BusinessError, data: Boolean)=>{ 445 if (err) { 446 console.error(`Failed to obtain whether the device is in secure mode, Code: ${err.code}, message: ${err.message}`); 447 return; 448 } 449 console.info(`Succeeded in Obtaining whether the device is in secure mode. result: ${data}`); 450 }); 451 ``` 452 453## screenLock.isSecureMode<sup>(deprecated)</sup> 454 455isSecureMode(): Promise<boolean> 456 457判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。使用Promise异步回调。 458 459> **说明：** 460> 461> 从API version 7开始支持，从API version 9开始废弃。 462 463**系统能力：** SystemCapability.MiscServices.ScreenLock 464 465**返回值：** 466 467| 类型 | 说明 | 468| ---------------------- | ------------------------------------------------------------ | 469| Promise<boolean> | Promise对象。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。 | 470 471**示例：** 472 473 ```ts 474 import { BusinessError } from '@ohos.base'; 475 476 screenLock.isSecureMode().then((data: Boolean) => { 477 console.info(`Succeeded in Obtaining whether the device is in secure mode. result: ${data}`); 478 }).catch((err: BusinessError) => { 479 console.error(`Failed to obtain whether the device is in secure mode, Code: ${err.code}, message: ${err.message}`); 480 }); 481 ``` 482 483## screenLock.unlockScreen<sup>(deprecated)</sup> 484 485unlockScreen(callback: AsyncCallback<void>): void 486 487解锁屏幕。使用callback异步回调。 488 489> **说明：** 490> 491> 从API version 7开始支持，从API version 9开始废弃。 492 493**系统能力：** SystemCapability.MiscServices.ScreenLock 494 495**参数：** 496 497| 参数名 | 类型 | 必填 | 说明 | 498| -------- | ------------- | ---- | --------------- | 499| callback | AsyncCallback<void> | 是 | 回调函数。解锁屏幕成功，err为undefined，否则为错误对象。 | 500 501**示例：** 502 503 ```ts 504 import { BusinessError } from '@ohos.base'; 505 506 screenLock.unlockScreen((err: BusinessError) => { 507 if (err) { 508 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 509 return; 510 } 511 console.info(`Succeeded unlocking the screen.`); 512 }); 513 ``` 514 515## screenLock.unlockScreen<sup>(deprecated)</sup> 516 517unlockScreen(): Promise<void> 518 519解锁屏幕。使用Promise异步回调。 520 521> **说明：** 522> 523> 从API version 7开始支持，从API version 9开始废弃。 524 525**系统能力：** SystemCapability.MiscServices.ScreenLock 526 527**返回值：** 528 529| 类型 | 说明 | 530| ------------------- | ------------------------- | 531| Promise<void> | Promise对象。无返回结果的Promise对象。 | 532 533**示例：** 534 535 ```ts 536 import { BusinessError } from '@ohos.base'; 537 538 screenLock.unlockScreen().then(() => { 539 console.info('Succeeded unlocking the screen.'); 540 }).catch((err: BusinessError) => { 541 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 542 }); 543 ``` 544