1# @ohos.runningLock (Runninglock锁) 2 3该模块主要提供RunningLock锁相关操作的接口,包括创建、查询、持锁、释放锁等操作。 4 5> **说明:** 6> 7> 本模块首批接口从API version 7开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 12import {runningLock} from '@kit.BasicServicesKit'; 13``` 14 15## runningLock.isSupported<sup>9+</sup> 16 17isSupported(type: RunningLockType): boolean; 18 19查询系统是否支持该类型的锁。 20 21**系统能力:** SystemCapability.PowerManager.PowerManager.Core 22 23**参数:** 24 25| 参数名 | 类型 | 必填 | 说明 | 26| ------ | ----------------------------------- | ---- | -------------------- | 27| type | [RunningLockType](#runninglocktype) | 是 | 需要查询的锁的类型;该参数必须是一个枚举类。 | 28 29**返回值:** 30 31| 类型 | 说明 | 32| ------- | --------------------------------------- | 33| boolean | 返回true表示支持,返回false表示不支持。 | 34 35**错误码:** 36 37以下错误码的详细介绍请参见[RunningLock锁错误码](errorcode-runninglock.md)。 38 39| 错误码ID | 错误信息 | 40|---------|---------| 41| 4900101 | Failed to connect to the service. | 42| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. | 43 44**示例:** 45 46```js 47try { 48 let isSupported = runningLock.isSupported(runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL); 49 console.info('BACKGROUND type supported: ' + isSupported); 50} catch(err) { 51 console.error('check supported failed, err: ' + err); 52} 53``` 54 55## runningLock.create<sup>9+</sup> 56 57create(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void 58 59创建RunningLock锁。 60 61**系统能力:** SystemCapability.PowerManager.PowerManager.Core 62 63**需要权限:** ohos.permission.RUNNING_LOCK 64 65**参数:** 66 67| 参数名 | 类型 | 必填 | 说明 | 68| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 69| name | string | 是 | 锁的名字;该参数必须为字符串类型。 | 70| type | [RunningLockType](#runninglocktype) | 是 | 要创建的锁的类型;该参数必须是一个枚举类。 | 71| callback | AsyncCallback<[RunningLock](#runninglock)> | 是 | 回调函数。当创建锁成功,err为undefined,data为创建的RunningLock;否则为错误对象;AsyncCallback封装了一个RunningLock类型的类。 | 72 73**错误码:** 74 75以下错误码的详细介绍请参见[RunningLock锁错误码](errorcode-runninglock.md)。 76 77| 错误码ID | 错误信息 | 78|---------|---------| 79| 401 | Parameter error. Possible causes: 1.Parameter verification failed. | 80| 201 | If the permission is denied.| 81 82**示例:** 83 84```js 85 86runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => { 87 if (typeof err === 'undefined') { 88 console.info('created running lock: ' + lock); 89 } else { 90 console.error('create running lock failed, err: ' + err); 91 } 92}); 93``` 94 95## runningLock.create<sup>9+</sup> 96 97create(name: string, type: RunningLockType): Promise<RunningLock> 98 99创建RunningLock锁。 100 101**系统能力:** SystemCapability.PowerManager.PowerManager.Core 102 103**需要权限:** ohos.permission.RUNNING_LOCK 104 105**参数:** 106 107| 参数名 | 类型 | 必填 | 说明 | 108| ------ | ----------------------------------- | ---- | ------------------ | 109| name | string | 是 | 锁的名字;该参数必须为字符串类型。 | 110| type | [RunningLockType](#runninglocktype) | 是 | 要创建的锁的类型;该参数必须是一个枚举类。 | 111 112**返回值:** 113 114| 类型 | 说明 | 115| ------------------------------------------ | ------------------------------------ | 116| Promise<[RunningLock](#runninglock)> | Promise对象,返回RunningLock锁对象。 | 117 118**错误码:** 119 120以下错误码的详细介绍请参见[RunningLock锁错误码](errorcode-runninglock.md)。 121 122| 错误码ID | 错误信息 | 123|---------|---------| 124| 401 | Parameter error. Possible causes: 1.Parameter verification failed. | 125| 201 | If the permission is denied.| 126 127**示例:** 128 129```js 130 131runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL) 132.then((lock: runningLock.RunningLock) => { 133 console.info('created running lock: ' + lock); 134}) 135.catch((err: Error) => { 136 console.error('create running lock failed, err: ' + err); 137}); 138``` 139 140## runningLock.isRunningLockTypeSupported<sup>(deprecated)</sup> 141 142isRunningLockTypeSupported(type: RunningLockType, callback: AsyncCallback<boolean>): void 143 144> **说明:**<br>从API version 9开始不再维护,建议使用[runningLock.isSupported](#runninglockissupported9)替代。 145 146查询系统是否支持该类型的锁。使用callback异步回调。 147 148**系统能力:** SystemCapability.PowerManager.PowerManager.Core 149 150**参数:** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 154| type | [RunningLockType](#runninglocktype) | 是 | 需要查询的锁的类型。 | 155| callback | AsyncCallback<boolean> | 是 | 回调函数。当查询成功,err为undefined,data为获取到的支持情况,返回true表示支持,返回false表示不支持;否则为错误对象。 | 156 157**示例:** 158 159```js 160runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND, (err: Error, data: boolean) => { 161 if (typeof err === 'undefined') { 162 console.info('BACKGROUND lock support status: ' + data); 163 } else { 164 console.log('check BACKGROUND lock support status failed, err: ' + err); 165 } 166}); 167``` 168 169## runningLock.isRunningLockTypeSupported<sup>(deprecated)</sup> 170 171isRunningLockTypeSupported(type: RunningLockType): Promise<boolean> 172 173> **说明:**<br>从API version 9开始不再维护,建议使用[runningLock.isSupported](#runninglockissupported9)替代。 174 175查询系统是否支持该类型的锁。使用Promise异步回调。 176 177**系统能力:** SystemCapability.PowerManager.PowerManager.Core 178 179**参数:** 180 181| 参数名 | 类型 | 必填 | 说明 | 182| ------ | ----------------------------------- | ---- | -------------------- | 183| type | [RunningLockType](#runninglocktype) | 是 | 需要查询的锁的类型。 | 184 185**返回值:** 186 187| 类型 | 说明 | 188| ---------------------- | ---------------------------------------------------- | 189| Promise<boolean> | Promise对象。返回true表示支持;返回false表示不支持。 | 190 191**示例:** 192 193```js 194runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND) 195.then((data: boolean) => { 196 console.info('BACKGROUND lock support status: ' + data); 197}) 198.catch((err: Error) => { 199 console.log('check BACKGROUND lock support status failed, err: ' + err); 200}); 201``` 202 203## runningLock.createRunningLock<sup>(deprecated)</sup> 204 205createRunningLock(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void 206 207> **说明:**<br>从API version 9开始不再维护,建议使用[runningLock.create](#runninglockcreate9)替代。 208 209创建RunningLock锁。 210 211**系统能力:** SystemCapability.PowerManager.PowerManager.Core 212 213**需要权限:** ohos.permission.RUNNING_LOCK 214 215**参数:** 216 217| 参数名 | 类型 | 必填 | 说明 | 218| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 219| name | string | 是 | 锁的名字。 | 220| type | [RunningLockType](#runninglocktype) | 是 | 要创建的锁的类型。 | 221| callback | AsyncCallback<[RunningLock](#runninglock)> | 是 | 回调函数。当创建锁成功,err为undefined,data为创建的RunningLock;否则为错误对象。 | 222 223**示例:** 224 225```js 226runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND, (err: Error, lock: runningLock.RunningLock) => { 227 if (typeof err === 'undefined') { 228 console.info('created running lock: ' + lock); 229 } else { 230 console.error('create running lock failed, err: ' + err); 231 } 232}); 233``` 234 235## runningLock.createRunningLock<sup>(deprecated)</sup> 236 237createRunningLock(name: string, type: RunningLockType): Promise<RunningLock> 238 239> **说明:**<br>从API version 9开始不再维护,建议使用[runningLock.create](#runninglockcreate9)替代。 240 241创建RunningLock锁。 242 243**系统能力:** SystemCapability.PowerManager.PowerManager.Core 244 245**需要权限:** ohos.permission.RUNNING_LOCK 246 247**参数:** 248 249| 参数名 | 类型 | 必填 | 说明 | 250| ------ | ----------------------------------- | ---- | ------------------ | 251| name | string | 是 | 锁的名字。 | 252| type | [RunningLockType](#runninglocktype) | 是 | 要创建的锁的类型。 | 253 254**返回值:** 255 256| 类型 | 说明 | 257| ------------------------------------------ | ------------------------------------ | 258| Promise<[RunningLock](#runninglock)> | Promise对象,返回RunningLock锁对象。 | 259 260**示例:** 261 262```js 263runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND) 264.then((lock: runningLock.RunningLock) => { 265 console.info('created running lock: ' + lock); 266}) 267.catch((err: Error) => { 268 console.log('create running lock failed, err: ' + err); 269}); 270``` 271 272## RunningLock 273 274阻止系统休眠的锁。 275 276### hold<sup>9+</sup> 277 278hold(timeout: number): void 279 280锁定和持有RunningLock。 281 282**系统能力:** SystemCapability.PowerManager.PowerManager.Core 283 284**需要权限:** ohos.permission.RUNNING_LOCK 285 286**参数:** 287 288| 参数名 | 类型 | 必填 | 说明 | 289| ------- | ------ | ---- | ----------------------------------------- | 290| timeout | number | 是 | 锁定和持有RunningLock的时长,单位:毫秒;该参数必须为数字类型。 timeout = -1为永久持锁,需要主动释放;timeout = 0 3s后超时释放; timeout > 0 按传入值超时释放| 291 292**错误码:** 293 294以下错误码的详细介绍请参见[RunningLock锁错误码](errorcode-runninglock.md)。 295 296| 错误码ID | 错误信息 | 297|---------|----------| 298| 4900101 | Failed to connect to the service. | 299| 401 | Parameter error. Possible causes: 1. Incorrect parameter types; | 300| 201 | If the permission is denied.| 301 302**示例:** 303 304```js 305static recordLock = null; 306 307if (recordLock) { 308 recordLock.hold(500); 309 console.info('hold running lock success'); 310} else { 311 runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => { 312 if (typeof err === 'undefined') { 313 console.info('create running lock: ' + lock); 314 recordLock = lock; 315 try { 316 lock.hold(500); 317 console.info('hold running lock success'); 318 } catch(err) { 319 console.error('hold running lock failed, err: ' + err); 320 } 321 } else { 322 console.error('create running lock failed, err: ' + err); 323 } 324 }); 325} 326``` 327 328### unhold<sup>9+</sup> 329 330unhold(): void 331 332释放RunningLock锁。 333 334**系统能力:** SystemCapability.PowerManager.PowerManager.Core 335 336**需要权限:** ohos.permission.RUNNING_LOCK 337 338**错误码:** 339 340以下错误码的详细介绍请参见[RunningLock锁错误码](errorcode-runninglock.md)。 341 342| 错误码ID | 错误信息 | 343|---------|----------| 344| 4900101 | Failed to connect to the service. | 345| 201 | If the permission is denied.| 346 347 348**示例:** 349 350```js 351static recordLock = null; 352 353if (recordLock) { 354 recordLock.unhold(); 355 console.info('unhold running lock success'); 356} else { 357 runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => { 358 if (typeof err === 'undefined') { 359 console.info('create running lock: ' + lock); 360 recordLock = lock; 361 try { 362 lock.unhold(); 363 console.info('unhold running lock success'); 364 } catch(err) { 365 console.error('unhold running lock failed, err: ' + err); 366 } 367 } else { 368 console.error('create running lock failed, err: ' + err); 369 } 370 }); 371} 372``` 373 374### isHolding<sup>9+</sup> 375 376isHolding(): boolean 377 378查询当前RunningLock是持有状态还是释放状态。 379 380**系统能力:** SystemCapability.PowerManager.PowerManager.Core 381 382**返回值:** 383 384| 类型 | 说明 | 385| ------- | ------------------------------------------------------------ | 386| boolean | 返回true表示当前RunningLock是持有状态,返回false表示当前RunningLock是释放状态。 | 387 388**错误码:** 389 390以下错误码的详细介绍请参见[RunningLock锁错误码](errorcode-runninglock.md)。 391 392| 错误码ID | 错误信息 | 393|---------|---------| 394| 4900101 | Failed to connect to the service. | 395 396**示例:** 397 398```js 399 400static recordLock = null; 401 402if (recordLock) { 403 let isHolding = recordLock.isHolding(); 404 console.info('check running lock holding status: ' + isHolding); 405} else { 406 runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => { 407 if (typeof err === 'undefined') { 408 console.info('create running lock: ' + lock); 409 runningLock = lock; 410 try { 411 let isHolding = lock.isHolding(); 412 console.info('check running lock holding status: ' + isHolding); 413 } catch(err) { 414 console.error('check running lock holding status failed, err: ' + err); 415 } 416 } else { 417 console.error('create running lock failed, err: ' + err); 418 } 419 }); 420} 421``` 422 423### lock<sup>(deprecated)</sup> 424 425lock(timeout: number): void 426 427> **说明:**<br>从API version 9开始不再维护,建议使用[RunningLock.hold](#hold9)替代。 428 429锁定和持有RunningLock。 430 431**系统能力:** SystemCapability.PowerManager.PowerManager.Core 432 433**需要权限:** ohos.permission.RUNNING_LOCK 434 435**参数:** 436 437| 参数名 | 类型 | 必填 | 说明 | 438| ------- | ------ | ---- | ----------------------------------------- | 439| timeout | number | 是 | 锁定和持有RunningLock的时长,单位:毫秒。 | 440 441**示例:** 442 443```js 444runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND) 445.then((lock: runningLock.RunningLock) => { 446 lock.lock(500); 447 console.info('create running lock and lock success'); 448}) 449.catch((err: Error) => { 450 console.error('create running lock failed, err: ' + err); 451}); 452``` 453 454### unlock<sup>(deprecated)</sup> 455 456unlock(): void 457 458> **说明:**<br>从API version 9开始不再维护,建议使用[RunningLock.unhold](#unhold9)替代。 459 460释放RunningLock锁。 461 462**系统能力:** SystemCapability.PowerManager.PowerManager.Core 463 464**需要权限:** ohos.permission.RUNNING_LOCK 465 466**示例:** 467 468```js 469runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND) 470.then((lock: runningLock.RunningLock) => { 471 lock.unlock(); 472 console.info('create running lock and unlock success'); 473}) 474.catch((err: Error) => { 475 console.error('create running lock failed, err: ' + err); 476}); 477``` 478 479### isUsed<sup>(deprecated)</sup> 480 481isUsed(): boolean 482 483> **说明:**<br>从API version 9开始不再维护,建议使用[RunningLock.isHolding](#isholding9)替代。 484 485查询当前RunningLock是持有状态还是释放状态。 486 487**系统能力:** SystemCapability.PowerManager.PowerManager.Core 488 489**返回值:** 490| 类型 | 说明 | 491| ------- | ------------------------------------------------------------ | 492| boolean | 返回true表示当前RunningLock是持有状态,返回false表示当前RunningLock是释放状态。 | 493 494**示例:** 495 496```js 497runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND) 498.then((lock: runningLock.RunningLock) => { 499 let isUsed = lock.isUsed(); 500 console.info('check running lock used status: ' + isUsed); 501}) 502.catch((err: Error) => { 503 console.error('check running lock used status failed, err: ' + err); 504}); 505``` 506 507## RunningLockType 508 509RunningLock锁的类型。 510 511**系统能力:** SystemCapability.PowerManager.PowerManager.Core 512 513| 名称 | 值 | 说明 | 514| --------------------------------- | ---- | ------------------------------------------------------------ | 515| BACKGROUND<sup>(deprecated)</sup> | 1 | 阻止系统休眠的锁。<br>**说明:** 从API version 7开始支持,从API version 10开始废弃。 | 516| PROXIMITY_SCREEN_CONTROL | 2 | 接近光锁,使能接近光传感器,并根据传感器与障碍物的距离远近发起亮灭屏流程。 |