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&lt;RunningLock&gt;): 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&lt;RunningLock&gt;
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&lt;[RunningLock](#runninglock)&gt; | 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&lt;boolean&gt;): 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&lt;boolean&gt;        | 是   | 回调函数。当查询成功,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&lt;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&lt;boolean&gt; | 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&lt;RunningLock&gt;): 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&lt;RunningLock&gt;
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&lt;[RunningLock](#runninglock)&gt; | 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    | 接近光锁,使能接近光传感器,并根据传感器与障碍物的距离远近发起亮灭屏流程。  |