1# @ohos.screenLock (锁屏管理) 2 3锁屏管理服务是OpenHarmony中的系统服务，为锁屏应用提供注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听，并提供回调结果给锁屏应用。锁屏管理服务向三方应用提供请求解锁、查询锁屏状态、查询是否设置锁屏密码的能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 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```js 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```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 107解锁屏幕。使用Promise异步回调。 108 109**系统能力：** SystemCapability.MiscServices.ScreenLock 110 111**系统接口**：此接口为系统接口。 112 113**返回值：** 114 115| 类型 | 说明 | 116| ------------------- | ------------------------------------------------------------ | 117| Promise<boolean> | Promise对象。返回true表示屏幕解锁成功；返回false表示屏幕解锁失败。 | 118 119**示例：** 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 133锁定屏幕。使用callback异步回调。 134 135**系统能力：** SystemCapability.MiscServices.ScreenLock 136 137**系统接口**：此接口为系统接口。 138 139**参数：** 140 141| 参数名 | 类型 | 必填 | 说明 | 142| -------- | ---------------------- | ---- | ---------------- | 143| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。 | 144 145**示例：** 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 161锁定屏幕。使用Promise异步回调。 162 163**系统能力：** SystemCapability.MiscServices.ScreenLock 164 165**系统接口**：此接口为系统接口。 166 167**返回值：** 168 169| 类型 | 说明 | 170| ---------------------- | ------------------------------------------------------------ | 171| Promise<boolean> | Promise对象。返回true表示屏幕锁定成功；返回false表示屏幕锁定失败。 | 172 173**示例：** 174 175```js 176screenlock.lock().then((data) => { 177 console.info(`lock the screen successfully. result: ${data}`); 178}).catch((err) => { 179 console.error(`Failed to lock the screen, because: ${err.message}`); 180}); 181``` 182 183## screenlock.onSystemEvent<sup>9+</sup> 184 185onSystemEvent(callback: Callback<SystemEvent>): boolean 186 187注册锁屏相关的系统事件，仅系统锁屏应用可调用。 188 189**系统能力：** SystemCapability.MiscServices.ScreenLock 190 191**系统接口**：此接口为系统接口。 192 193**参数：** 194 195| 参数名 | 类型 | 必填 | 说明 | 196| -------- | ------------------------- | ---- | ----------------- | 197| callback | Callback\<[SystemEvent](#systemevent9)> | 是 | 锁屏相关的系统事件回调函数。 | 198 199**返回值：** 200 201| 类型 | 说明 | 202| ------- | ------------------------------------------------- | 203| boolean | 返回true表示锁屏相关系统事件注册成功；返回false表示锁屏相关系统事件注册失败。 | 204 205**示例：** 206 207```js 208try { 209 let isSuccess = screenlock.onSystemEvent((event) => { 210 console.log(`Register the system event which related to screenlock successfully. eventType: ${event.eventType}`) 211 }); 212} catch (err) { 213 console.error(`Failed to register the system event which related to screenlock, because: ${err.message}`) 214} 215``` 216 217## screenlock.sendScreenLockEvent<sup>9+</sup> 218 219sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void 220 221应用发送事件到锁屏服务。使用callback异步回调。 222 223**系统能力：** SystemCapability.MiscServices.ScreenLock 224 225**系统接口**：此接口为系统接口。 226 227**参数：** 228 229| 参数名 | 类型 | 必填 | 说明 | 230| --------- | ------------------------ | ---- | -------------------- | 231| event | String | 是 | 事件类型，支持如下取值:<br/>- "unlockScreenResult"，表示解锁结果。<br/>- "lockScreenResult"，表示锁屏结果。<br/>- "screenDrawDone"，表示屏幕绘制完成。 | 232| parameter | number | 是 | 事件结果。<br/>- parameter为0，表示成功。例如解锁成功或锁屏成功。<br/>- parameter为1，表示失败。例如解锁失败或锁屏失败。<br/>- parameter为2，表示取消。例如锁屏取消或解锁取消。 | 233| callback | AsyncCallback\<boolean> | 是 | 回调函数。返回true表示发送事件成功；返回false表示发送事件失败。 | 234 235**示例：** 236 237```js 238screenlock.sendScreenLockEvent('unlockScreenResult', 0, (err, result) => { 239 if (err) { 240 console.error(`Failed to send screenlock event, because: ${err.message}`); 241 return; 242 } 243 console.info(`Send screenlock event successfully. result: ${result}`); 244}); 245``` 246 247## screenlock.sendScreenLockEvent<sup>9+</sup> 248 249sendScreenLockEvent(event: String, parameter: number): Promise<boolean> 250 251应用发送事件到锁屏服务。使用Promise异步回调。 252 253**系统能力：** SystemCapability.MiscServices.ScreenLock 254 255**系统接口**：此接口为系统接口。 256 257**参数：** 258 259| 参数名 | 类型 | 必填 | 说明 | 260| --------- | ------ | ---- | --------------------------------------- | 261| event | String | 是 | 事件类型，支持如下取值:<br/>- "unlockScreenResult"，表示解锁结果。<br/>- "lockScreenResult"，表示锁屏结果。<br/>- "screenDrawDone"，表示屏幕绘制完成。 | 262| parameter | number | 是 | 事件结果。<br/>- parameter为0，表示成功。例如解锁成功或锁屏成功。<br/>- parameter为1，表示失败。例如解锁失败或锁屏失败。<br/>- parameter为2，表示取消。例如锁屏取消或解锁取消。 | 263 264**返回值：** 265 266| 类型 | 说明 | 267| ----------------- | ---------------------------------------------- | 268| Promise\<boolean> | Promise对象。返回true表示发送事件成功；返回false表示发送事件失败。 | 269 270**示例：** 271 272```js 273screenlock.sendScreenLockEvent('unlockScreenResult', 0).then((result) => { 274 console.info(`Send screenlock event successfully. result: ${result}`); 275}).catch((err) => { 276 console.error(`Failed to send screenlock event, because: ${err.message}`); 277}); 278``` 279 280## screenlock.isScreenLocked<sup>(deprecated)</sup> 281 282isScreenLocked(callback: AsyncCallback<boolean>): void 283 284判断屏幕是否锁屏。使用callback异步回调。 285 286> **说明：** 287> 288> 从API version 7开始支持，从API version 9开始废弃。 289 290**系统能力：** SystemCapability.MiscServices.ScreenLock 291 292**参数：** 293 294| 参数名 | 类型 | 必填 | 说明 | 295| -------- | ---------------------------- | ---- | ----------------------------------------------------------- | 296| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | 297 298**示例：** 299 300```js 301screenlock.isScreenLocked((err, data)=>{ 302 if (err) { 303 console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`); 304 return; 305 } 306 console.info(`Obtain whether the screen is locked successfully. result: ${data}`); 307}); 308``` 309 310## screenlock.isScreenLocked<sup>(deprecated)</sup> 311 312isScreenLocked(): Promise<boolean> 313 314判断屏幕是否锁屏。使用Promise异步回调。 315 316> **说明：** 317> 318> 从API version 7开始支持，从API version 9开始废弃。 319 320**系统能力：** SystemCapability.MiscServices.ScreenLock 321 322**返回值：** 323 324| 类型 | 说明 | 325| ---------------------- | ------------------------------------------- | 326| Promise<boolean> | Promise对象。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。 | 327 328**示例：** 329 330```js 331screenlock.isScreenLocked().then((data) => { 332 console.info(`Obtain whether the screen is locked successfully. result: ${data}`); 333}).catch((err) => { 334 console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`); 335}); 336``` 337 338## screenlock.isSecureMode<sup>(deprecated)</sup> 339 340isSecureMode(callback: AsyncCallback<boolean>): void 341 342判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。使用callback异步回调。 343 344> **说明：** 345> 346> 从API version 7开始支持，从API version 9开始废弃。 347 348**系统能力：** SystemCapability.MiscServices.ScreenLock 349 350**参数：** 351 352| 参数名 | 类型 | 必填 | 说明 | 353| -------- | --------------------- | ---- | ------------------------ | 354| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。 | 355 356**示例：** 357 358```js 359screenlock.isSecureMode((err, data)=>{ 360 if (err) { 361 console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`); 362 return; 363 } 364 console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`); 365}); 366``` 367 368## screenlock.isSecureMode<sup>(deprecated)</sup> 369 370isSecureMode(): Promise<boolean> 371 372判断当前设备的屏幕锁定是否安全（安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别）。使用Promise异步回调。 373 374> **说明：** 375> 376> 从API version 7开始支持，从API version 9开始废弃。 377 378**系统能力：** SystemCapability.MiscServices.ScreenLock 379 380**返回值：** 381 382| 类型 | 说明 | 383| ---------------------- | ------------------------------------------------------------ | 384| Promise<boolean> | Promise对象。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。 | 385 386**示例：** 387 388```js 389screenlock.isSecureMode().then((data) => { 390 console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`); 391}).catch((err) => { 392 console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`); 393}); 394``` 395## screenlock.unlockScreen<sup>(deprecated)</sup> 396 397unlockScreen(callback: AsyncCallback<void>): void 398 399解锁屏幕。使用callback异步回调。 400 401> **说明：** 402> 403> 从API version 7开始支持，从API version 9开始废弃。 404 405**系统能力：** SystemCapability.MiscServices.ScreenLock 406 407**参数：** 408 409| 参数名 | 类型 | 必填 | 说明 | 410| -------- | ------------- | ---- | --------------- | 411| callback | AsyncCallback<void> | 是 | 回调函数。解锁屏幕成功，err为undefined，否则为错误对象。 | 412 413**示例：** 414 415```js 416screenlock.unlockScreen((err) => { 417 if (err) { 418 console.error(`Failed to unlock the screen, because: ${err.message}`); 419 return; 420 } 421 console.info('unlock the screen successfully.'); 422}); 423``` 424 425## screenlock.unlockScreen<sup>(deprecated)</sup> 426 427unlockScreen(): Promise<void> 428 429解锁屏幕。使用Promise异步回调。 430 431> **说明：** 432> 433> 从API version 7开始支持，从API version 9开始废弃。 434 435**系统能力：** SystemCapability.MiscServices.ScreenLock 436 437**返回值：** 438 439| 类型 | 说明 | 440| ------------------- | ------------------------- | 441| Promise<void> | Promise对象。无返回结果的Promise对象。 | 442 443**示例：** 444 445```js 446screenlock.unlockScreen().then(() => { 447 console.info('unlock the screen successfully.'); 448}).catch((err) => { 449 console.error(`Failed to unlock the screen, because: ${err.message}`); 450}); 451``` 452