1# @ohos.screenLock (Screen Lock) 2 3The **screenlock** module is a system module in OpenHarmony. It provides APIs for screen lock applications to subscribe to screen lock status changes as well as callbacks for them to receive the results. It also provides APIs for third-party applications to unlock the screen, obtain the screen locked status, and check whether a lock screen password has been set. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```js 12import screenlock from '@ohos.screenLock'; 13``` 14 15## EventType<sup>9+</sup> 16 17Defines the system event type. 18 19**System capability**: SystemCapability.MiscServices.ScreenLock 20 21**System API**: This is a system API. 22 23| Event Type | Description | 24| ------------------ | ------------------------ | 25| beginWakeUp | Wakeup starts.| 26| endWakeUp | Wakeup ends.| 27| beginScreenOn | Screen turn-on starts.| 28| endScreenOn | Screen turn-on ends.| 29| beginScreenOff | Screen turn-off starts.| 30| endScreenOff | Screen turn-off ends.| 31| unlockScreen | The screen is unlocked. | 32| lockScreen | The screen is locked. | 33| beginExitAnimation | Exit animation starts. | 34| beginSleep | The device enters sleep mode. | 35| endSleep | The device exits sleep mode. | 36| changeUser | The user is switched. | 37| screenlockEnabled | Screen lock is enabled. | 38| serviceRestart | The screen lock service is restarted. | 39 40## SystemEvent<sup>9+</sup> 41 42Defines the structure of the system event callback. 43 44**System capability**: SystemCapability.MiscServices.ScreenLock 45 46**System API**: This is a system API. 47 48| Name | Type | Mandatory| Description | 49| --------- | ------ | ---- | ------------- | 50| eventType | [EventType](#eventtype9) | Yes | System event type.| 51| params | string | Yes | System event parameters.| 52 53## screenlock.isLocked<sup>9+</sup> 54 55isLocked(): boolean 56 57Checks whether the screen is locked. 58 59**System capability**: SystemCapability.MiscServices.ScreenLock 60 61**System API**: This is a system API. 62 63**Return value** 64 65| Type | Description | 66| ------- | ------------------------------------------------- | 67| boolean | Returns **true** if the screen is locked; returns **false** otherwise.| 68 69**Example** 70 71```js 72let isLocked = screenlock.isLocked(); 73``` 74 75## screenlock.unlock<sup>9+</sup> 76 77unlock(callback: AsyncCallback<boolean>): void 78 79Unlocks the screen. This API uses an asynchronous callback to return the result. 80 81**System capability**: SystemCapability.MiscServices.ScreenLock 82 83**System API**: This is a system API. 84 85**Parameters** 86 87| Name | Type | Mandatory| Description | 88| -------- | --------------------- | ---- | ------------------------- | 89| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means the opposite.| 90 91**Error codes** 92 93For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 94 95| ID| Error Message| 96| -------- | ---------------------------------------- | 97| 13200002 | the screenlock management service is abnormal. | 98 99**Example** 100 101```js 102screenlock.unlock((err, data) => { 103 if (err) { 104 console.error(`Failed to unlock the screen, because: ${err.message}`); 105 return; 106 } 107 console.info(`unlock the screen successfully. result: ${data}`); 108}); 109``` 110 111## screenlock.unlock<sup>9+</sup> 112 113unlock(): Promise<boolean> 114 115Unlocks the screen. This API uses a promise to return the result. 116 117**System capability**: SystemCapability.MiscServices.ScreenLock 118 119**System API**: This is a system API. 120 121**Return value** 122 123| Type | Description | 124| ------------------- | ------------------------------------------------------------ | 125| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means the opposite.| 126 127**Error codes** 128 129For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 130 131| ID| Error Message| 132| -------- | ---------------------------------------- | 133| 13200002 | the screenlock management service is abnormal. | 134 135**Example** 136 137```js 138screenlock.unlock().then((data) => { 139 console.info(`unlock the screen successfully. result: ${data}`); 140}).catch((err) => { 141 console.error(`Failed to unlock the screen, because: ${err.message}`); 142}); 143``` 144 145## screenlock.lock<sup>9+</sup> 146 147lock(callback: AsyncCallback<boolean>): void 148 149Locks the screen. This API uses an asynchronous callback to return the result. 150 151**System capability**: SystemCapability.MiscServices.ScreenLock 152 153**System API**: This is a system API. 154 155**Parameters** 156 157| Name | Type | Mandatory| Description | 158| -------- | ---------------------- | ---- | ---------------- | 159| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is locked successfully, and **false** means the opposite.| 160 161**Error codes** 162 163For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 164 165| ID| Error Message| 166| -------- | ---------------------------------------- | 167| 13200002 | the screenlock management service is abnormal. | 168 169**Example** 170 171```js 172screenlock.lock((err, data) => { 173 if (err) { 174 console.error(`Failed to lock the screen, because: ${err.message}`); 175 return; 176 } 177 console.info(`lock the screen successfully. result: ${data}`); 178}); 179``` 180 181## screenlock.lock<sup>9+</sup> 182 183lock(): Promise<boolean> 184 185Locks the screen. This API uses a promise to return the result. 186 187**System capability**: SystemCapability.MiscServices.ScreenLock 188 189**System API**: This is a system API. 190 191**Return value** 192 193| Type | Description | 194| ---------------------- | ------------------------------------------------------------ | 195| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked successfully, and **false** means the opposite.| 196 197**Error codes** 198 199For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 200 201| ID| Error Message| 202| -------- | ---------------------------------------- | 203| 13200002 | the screenlock management service is abnormal. | 204 205**Example** 206 207```js 208screenlock.lock().then((data) => { 209 console.info(`lock the screen successfully. result: ${data}`); 210}).catch((err) => { 211 console.error(`Failed to lock the screen, because: ${err.message}`); 212}); 213``` 214 215## screenlock.onSystemEvent<sup>9+</sup> 216 217onSystemEvent(callback: Callback<SystemEvent>): boolean 218 219Registers a callback for system events related to screen locking. This API can be called only by system screen lock applications. 220 221**System capability**: SystemCapability.MiscServices.ScreenLock 222 223**System API**: This is a system API. 224 225**Parameters** 226 227| Name | Type | Mandatory| Description | 228| -------- | ------------------------- | ---- | ----------------- | 229| callback | Callback\<[SystemEvent](#systemevent9)> | Yes | Callback for system events related to screen locking.| 230 231**Return value** 232 233| Type | Description | 234| ------- | ------------------------------------------------- | 235| boolean | Returns **true** if the callback is registered successfully; returns **false** otherwise.| 236 237**Error codes** 238 239For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 240 241| ID| Error Message| 242| -------- | ---------------------------------------- | 243| 13200002 | the screenlock management service is abnormal. | 244 245**Example** 246 247```js 248try { 249 let isSuccess = screenlock.onSystemEvent((event) => { 250 console.log(`Register the system event which related to screenlock successfully. eventType: ${event.eventType}`) 251 }); 252} catch (err) { 253 console.error(`Failed to register the system event which related to screenlock, because: ${err.message}`) 254} 255``` 256 257## screenlock.sendScreenLockEvent<sup>9+</sup> 258 259sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void 260 261Sends an event to the screen lock service. This API uses an asynchronous callback to return the result. 262 263**System capability**: SystemCapability.MiscServices.ScreenLock 264 265**System API**: This is a system API. 266 267**Parameters** 268 269| Name | Type | Mandatory| Description | 270| --------- | ------------------------ | ---- | -------------------- | 271| event | String | Yes | Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"lockScreenResult"**: Screen lock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| 272| parameter | number | Yes | Result.<br>- **0**: The operation is successful. For example, the screen is locked or unlocked successfully.<br>- **1**, the operation fails. For example, screen locking or unlocking fails.<br>- **2**: The operation is canceled. For example, screen locking or unlocking is canceled.| 273| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. The **value** true means that the event is sent successfully, and **false** means the opposite. | 274 275**Error codes** 276 277For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 278 279| ID| Error Message| 280| -------- | ---------------------------------------- | 281| 13200002 |the screenlock management service is abnormal. | 282 283**Example** 284 285```js 286screenlock.sendScreenLockEvent('unlockScreenResult', 0, (err, result) => { 287 if (err) { 288 console.error(`Failed to send screenlock event, because: ${err.message}`); 289 return; 290 } 291 console.info(`Send screenlock event successfully. result: ${result}`); 292}); 293``` 294 295## screenlock.sendScreenLockEvent<sup>9+</sup> 296 297sendScreenLockEvent(event: String, parameter: number): Promise<boolean> 298 299Sends an event to the screen lock service. This API uses a promise to return the result. 300 301**System capability**: SystemCapability.MiscServices.ScreenLock 302 303**System API**: This is a system API. 304 305**Parameters** 306 307| Name | Type | Mandatory| Description | 308| --------- | ------ | ---- | --------------------------------------- | 309| event | String | Yes | Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"lockScreenResult"**: Screen lock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| 310| parameter | number | Yes | Result.<br>- **0**: The operation is successful. For example, the screen is locked or unlocked successfully.<br>- **1**, the operation fails. For example, screen locking or unlocking fails.<br>- **2**: The operation is canceled. For example, screen locking or unlocking is canceled.| 311 312**Return value** 313 314| Type | Description | 315| ----------------- | ---------------------------------------------- | 316| Promise\<boolean> | Promise used to return the result. The **value** true means that the event is sent successfully, and **false** means the opposite.| 317 318**Error codes** 319 320For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 321 322| ID| Error Message| 323| -------- | ---------------------------------------- | 324| 13200002 | the screenlock management service is abnormal. | 325 326**Example** 327 328```js 329screenlock.sendScreenLockEvent('unlockScreenResult', 0).then((result) => { 330 console.info(`Send screenlock event successfully. result: ${result}`); 331}).catch((err) => { 332 console.error(`Failed to send screenlock event, because: ${err.message}`); 333}); 334``` 335 336## screenlock.isScreenLocked<sup>(deprecated)</sup> 337 338isScreenLocked(callback: AsyncCallback<boolean>): void 339 340Checks whether the screen is locked. This API uses an asynchronous callback to return the result. 341 342> **NOTE** 343> 344> This API is supported since API version 7 and deprecated since API version 9. 345 346**System capability**: SystemCapability.MiscServices.ScreenLock 347 348**Parameters** 349 350| Name | Type | Mandatory| Description | 351| -------- | ---------------------------- | ---- | ----------------------------------------------------------- | 352| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is locked, and **false** means the opposite.| 353 354**Example** 355 356```js 357screenlock.isScreenLocked((err, data)=>{ 358 if (err) { 359 console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`); 360 return; 361 } 362 console.info(`Obtain whether the screen is locked successfully. result: ${data}`); 363}); 364``` 365 366## screenlock.isScreenLocked<sup>(deprecated)</sup> 367 368isScreenLocked(): Promise<boolean> 369 370Checks whether the screen is locked. This API uses a promise to return the result. 371 372> **NOTE** 373> 374> This API is supported since API version 7 and deprecated since API version 9. 375 376**System capability**: SystemCapability.MiscServices.ScreenLock 377 378**Return value** 379 380| Type | Description | 381| ---------------------- | ------------------------------------------- | 382| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked, and **false** means the opposite.| 383 384**Example** 385 386```js 387screenlock.isScreenLocked().then((data) => { 388 console.info(`Obtain whether the screen is locked successfully. result: ${data}`); 389}).catch((err) => { 390 console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`); 391}); 392``` 393 394## screenlock.isSecureMode<sup>(deprecated)</sup> 395 396isSecureMode(callback: AsyncCallback<boolean>): void 397 398Checks whether the device is in secure mode. When the device is in secure mode, its screen requires a password, unlock pattern, or other user credentials to unlock. This API uses an asynchronous callback to return the result. 399 400> **NOTE** 401> 402> This API is supported since API version 7 and deprecated since API version 9. 403 404**System capability**: SystemCapability.MiscServices.ScreenLock 405 406**Parameters** 407 408| Name | Type | Mandatory| Description | 409| -------- | --------------------- | ---- | ------------------------ | 410| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the device is in secure mode, and **false** means the opposite.| 411 412**Example** 413 414```js 415screenlock.isSecureMode((err, data)=>{ 416 if (err) { 417 console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`); 418 return; 419 } 420 console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`); 421}); 422``` 423 424## screenlock.isSecureMode<sup>(deprecated)</sup> 425 426isSecureMode(): Promise<boolean> 427 428Checks whether the device is in secure mode. When the device is in secure mode, its screen requires a password, unlock pattern, or other user credentials to unlock. This API uses a promise to return the result. 429 430> **NOTE** 431> 432> This API is supported since API version 7 and deprecated since API version 9. 433 434**System capability**: SystemCapability.MiscServices.ScreenLock 435 436**Return value** 437 438| Type | Description | 439| ---------------------- | ------------------------------------------------------------ | 440| Promise<boolean> | Promise used to return the result. The value **true** means that the device is in secure mode, and **false** means the opposite.| 441 442**Example** 443 444```js 445screenlock.isSecureMode().then((data) => { 446 console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`); 447}).catch((err) => { 448 console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`); 449}); 450``` 451## screenlock.unlockScreen<sup>(deprecated)</sup> 452 453unlockScreen(callback: AsyncCallback<void>): void 454 455Unlocks the screen. This API uses an asynchronous callback to return the result. 456 457> **NOTE** 458> 459> This API is supported since API version 7 and deprecated since API version 9. 460 461**System capability**: SystemCapability.MiscServices.ScreenLock 462 463**Parameters** 464 465| Name | Type | Mandatory| Description | 466| -------- | ------------- | ---- | --------------- | 467| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the screen is unlocked successfully, **err** is **undefined**; otherwise, **err** is an error object.| 468 469**Example** 470 471```js 472screenlock.unlockScreen((err) => { 473 if (err) { 474 console.error(`Failed to unlock the screen, because: ${err.message}`); 475 return; 476 } 477 console.info('unlock the screen successfully.'); 478}); 479``` 480 481## screenlock.unlockScreen<sup>(deprecated)</sup> 482 483unlockScreen(): Promise<void> 484 485Unlocks the screen. This API uses a promise to return the result. 486 487> **NOTE** 488> 489> This API is supported since API version 7 and deprecated since API version 9. 490 491**System capability**: SystemCapability.MiscServices.ScreenLock 492 493**Return value** 494 495| Type | Description | 496| ------------------- | ------------------------- | 497| Promise<void> | Promise that returns no value.| 498 499**Example** 500 501```js 502screenlock.unlockScreen().then(() => { 503 console.info('unlock the screen successfully.'); 504}).catch((err) => { 505 console.error(`Failed to unlock the screen, because: ${err.message}`); 506}); 507``` 508