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**Example** 92 93```js 94screenlock.unlock((err, data) => { 95 if (err) { 96 console.error(`Failed to unlock the screen, because: ${err.message}`); 97 return; 98 } 99 console.info(`unlock the screen successfully. result: ${data}`); 100}); 101``` 102 103## screenlock.unlock<sup>9+</sup> 104 105unlock(): Promise<boolean> 106 107Unlocks the screen. This API uses a promise to return the result. 108 109**System capability**: SystemCapability.MiscServices.ScreenLock 110 111**System API**: This is a system API. 112 113**Return value** 114 115| Type | Description | 116| ------------------- | ------------------------------------------------------------ | 117| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means the opposite.| 118 119**Example** 120 121```js 122screenlock.unlock().then((data) => { 123 console.info(`unlock the screen successfully. result: ${data}`); 124}).catch((err) => { 125 console.error(`Failed to unlock the screen, because: ${err.message}`); 126}); 127``` 128 129## screenlock.lock<sup>9+</sup> 130 131lock(callback: AsyncCallback<boolean>): void 132 133Locks the screen. This API uses an asynchronous callback to return the result. 134 135**System capability**: SystemCapability.MiscServices.ScreenLock 136 137**System API**: This is a system API. 138 139**Parameters** 140 141| Name | Type | Mandatory| Description | 142| -------- | ---------------------- | ---- | ---------------- | 143| 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.| 144 145**Example** 146 147```js 148screenlock.lock((err, data) => { 149 if (err) { 150 console.error(`Failed to lock the screen, because: ${err.message}`); 151 return; 152 } 153 console.info(`lock the screen successfully. result: ${data}`); 154}); 155``` 156 157## screenlock.lock<sup>9+</sup> 158 159lock(): Promise<boolean> 160 161Locks the screen. This API uses a promise to return the result. 162 163**System capability**: SystemCapability.MiscServices.ScreenLock 164 165**System API**: This is a system API. 166 167**Return value** 168 169| Type | Description | 170| ---------------------- | ------------------------------------------------------------ | 171| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked successfully, and **false** means the opposite.| 172 173 174**Example** 175 176```js 177screenlock.lock().then((data) => { 178 console.info(`lock the screen successfully. result: ${data}`); 179}).catch((err) => { 180 console.error(`Failed to lock the screen, because: ${err.message}`); 181}); 182``` 183 184## screenlock.onSystemEvent<sup>9+</sup> 185 186onSystemEvent(callback: Callback<SystemEvent>): boolean 187 188Registers a callback for system events related to screen locking. This API can be called only by system screen lock applications. 189 190**System capability**: SystemCapability.MiscServices.ScreenLock 191 192**System API**: This is a system API. 193 194**Parameters** 195 196| Name | Type | Mandatory| Description | 197| -------- | ------------------------- | ---- | ----------------- | 198| callback | Callback\<[SystemEvent](#systemevent9)> | Yes | Callback for system events related to screen locking.| 199 200**Return value** 201 202| Type | Description | 203| ------- | ------------------------------------------------- | 204| boolean | Returns **true** if the callback is registered successfully; returns **false** otherwise.| 205 206 207**Example** 208 209```js 210try { 211 let isSuccess = screenlock.onSystemEvent((event) => { 212 console.log(`Register the system event which related to screenlock successfully. eventType: ${event.eventType}`) 213 }); 214} catch (err) { 215 console.error(`Failed to register the system event which related to screenlock, because: ${err.message}`) 216} 217``` 218 219## screenlock.sendScreenLockEvent<sup>9+</sup> 220 221sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void 222 223Sends an event to the screen lock service. This API uses an asynchronous callback to return the result. 224 225**System capability**: SystemCapability.MiscServices.ScreenLock 226 227**System API**: This is a system API. 228 229**Parameters** 230 231| Name | Type | Mandatory| Description | 232| --------- | ------------------------ | ---- | -------------------- | 233| event | String | Yes | Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"lockScreenResult"**: Screen lock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| 234| 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.| 235| 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. | 236 237 238**Example** 239 240```js 241screenlock.sendScreenLockEvent('unlockScreenResult', 0, (err, result) => { 242 if (err) { 243 console.error(`Failed to send screenlock event, because: ${err.message}`); 244 return; 245 } 246 console.info(`Send screenlock event successfully. result: ${result}`); 247}); 248``` 249 250## screenlock.sendScreenLockEvent<sup>9+</sup> 251 252sendScreenLockEvent(event: String, parameter: number): Promise<boolean> 253 254Sends an event to the screen lock service. This API uses a promise to return the result. 255 256**System capability**: SystemCapability.MiscServices.ScreenLock 257 258**System API**: This is a system API. 259 260**Parameters** 261 262| Name | Type | Mandatory| Description | 263| --------- | ------ | ---- | --------------------------------------- | 264| event | String | Yes | Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"lockScreenResult"**: Screen lock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| 265| 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.| 266 267**Return value** 268 269| Type | Description | 270| ----------------- | ---------------------------------------------- | 271| Promise\<boolean> | Promise used to return the result. The **value** true means that the event is sent successfully, and **false** means the opposite.| 272 273**Example** 274 275```js 276screenlock.sendScreenLockEvent('unlockScreenResult', 0).then((result) => { 277 console.info(`Send screenlock event successfully. result: ${result}`); 278}).catch((err) => { 279 console.error(`Failed to send screenlock event, because: ${err.message}`); 280}); 281``` 282 283## screenlock.isScreenLocked<sup>(deprecated)</sup> 284 285isScreenLocked(callback: AsyncCallback<boolean>): void 286 287Checks whether the screen is locked. This API uses an asynchronous callback to return the result. 288 289> **NOTE** 290> 291> This API is supported since API version 7 and deprecated since API version 9. 292 293**System capability**: SystemCapability.MiscServices.ScreenLock 294 295**Parameters** 296 297| Name | Type | Mandatory| Description | 298| -------- | ---------------------------- | ---- | ----------------------------------------------------------- | 299| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is locked, and **false** means the opposite.| 300 301**Example** 302 303```js 304screenlock.isScreenLocked((err, data)=>{ 305 if (err) { 306 console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`); 307 return; 308 } 309 console.info(`Obtain whether the screen is locked successfully. result: ${data}`); 310}); 311``` 312 313## screenlock.isScreenLocked<sup>(deprecated)</sup> 314 315isScreenLocked(): Promise<boolean> 316 317Checks whether the screen is locked. This API uses a promise to return the result. 318 319> **NOTE** 320> 321> This API is supported since API version 7 and deprecated since API version 9. 322 323**System capability**: SystemCapability.MiscServices.ScreenLock 324 325**Return value** 326 327| Type | Description | 328| ---------------------- | ------------------------------------------- | 329| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked, and **false** means the opposite.| 330 331**Example** 332 333```js 334screenlock.isScreenLocked().then((data) => { 335 console.info(`Obtain whether the screen is locked successfully. result: ${data}`); 336}).catch((err) => { 337 console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`); 338}); 339``` 340 341## screenlock.isSecureMode<sup>(deprecated)</sup> 342 343isSecureMode(callback: AsyncCallback<boolean>): void 344 345Checks 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. 346 347> **NOTE** 348> 349> This API is supported since API version 7 and deprecated since API version 9. 350 351**System capability**: SystemCapability.MiscServices.ScreenLock 352 353**Parameters** 354 355| Name | Type | Mandatory| Description | 356| -------- | --------------------- | ---- | ------------------------ | 357| 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.| 358 359**Example** 360 361```js 362screenlock.isSecureMode((err, data)=>{ 363 if (err) { 364 console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`); 365 return; 366 } 367 console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`); 368}); 369``` 370 371## screenlock.isSecureMode<sup>(deprecated)</sup> 372 373isSecureMode(): Promise<boolean> 374 375Checks 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. 376 377> **NOTE** 378> 379> This API is supported since API version 7 and deprecated since API version 9. 380 381**System capability**: SystemCapability.MiscServices.ScreenLock 382 383**Return value** 384 385| Type | Description | 386| ---------------------- | ------------------------------------------------------------ | 387| Promise<boolean> | Promise used to return the result. The value **true** means that the device is in secure mode, and **false** means the opposite.| 388 389**Example** 390 391```js 392screenlock.isSecureMode().then((data) => { 393 console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`); 394}).catch((err) => { 395 console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`); 396}); 397``` 398## screenlock.unlockScreen<sup>(deprecated)</sup> 399 400unlockScreen(callback: AsyncCallback<void>): void 401 402Unlocks the screen. This API uses an asynchronous callback to return the result. 403 404> **NOTE** 405> 406> This API is supported since API version 7 and deprecated since API version 9. 407 408**System capability**: SystemCapability.MiscServices.ScreenLock 409 410**Parameters** 411 412| Name | Type | Mandatory| Description | 413| -------- | ------------- | ---- | --------------- | 414| 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.| 415 416**Example** 417 418```js 419screenlock.unlockScreen((err) => { 420 if (err) { 421 console.error(`Failed to unlock the screen, because: ${err.message}`); 422 return; 423 } 424 console.info('unlock the screen successfully.'); 425}); 426``` 427 428## screenlock.unlockScreen<sup>(deprecated)</sup> 429 430unlockScreen(): Promise<void> 431 432Unlocks the screen. This API uses a promise to return the result. 433 434> **NOTE** 435> 436> This API is supported since API version 7 and deprecated since API version 9. 437 438**System capability**: SystemCapability.MiscServices.ScreenLock 439 440**Return value** 441 442| Type | Description | 443| ------------------- | ------------------------- | 444| Promise<void> | Promise that returns no value.| 445 446**Example** 447 448```js 449screenlock.unlockScreen().then(() => { 450 console.info('unlock the screen successfully.'); 451}).catch((err) => { 452 console.error(`Failed to unlock the screen, because: ${err.message}`); 453}); 454``` 455