• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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的时长，单位：毫秒。<br>该参数必须为数字类型：<br>**-1**：永久持锁，需要主动释放。<br>**0**：默认3s后超时释放。<br>**>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```ts
305// RunningLockTest.ets
306class RunningLockTest {
307    public static recordLock: runningLock.RunningLock;
308
309    public static holdRunningLock(): void {
310        if (RunningLockTest.recordLock) {
311            RunningLockTest.recordLock.hold(500);
312            console.info('hold running lock success');
313        } else {
314            runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => {
315                if (typeof err === 'undefined') {
316                    console.info('create running lock: ' + lock);
317                    RunningLockTest.recordLock = lock;
318                    try {
319                        lock.hold(500);
320                        console.info('hold running lock success');
321                    } catch(err) {
322                        console.error('hold running lock failed, err: ' + err);
323                    }
324                } else {
325                    console.error('create running lock failed, err: ' + err);
326                }
327            });
328        }
329    }
330}
331```
332
333### unhold<sup>9+</sup>
334
335unhold(): void
336
337释放RunningLock锁。
338
339**系统能力：** SystemCapability.PowerManager.PowerManager.Core
340
341**需要权限：** ohos.permission.RUNNING_LOCK
342
343**错误码：**
344
345以下错误码的详细介绍请参见[RunningLock锁错误码](errorcode-runninglock.md)。
346
347| 错误码ID   | 错误信息     |
348|---------|----------|
349| 4900101 | Failed to connect to the service. |
350| 201     | If the permission is denied.|
351
352
353**示例：**
354
355```ts
356// RunningLockTest.ets
357class RunningLockTest {
358    public static recordLock: runningLock.RunningLock;
359
360    public static unholdRunningLock(): void {
361        if (RunningLockTest.recordLock) {
362            RunningLockTest.recordLock.unhold();
363            console.info('hold running lock success');
364        } else {
365            runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => {
366                if (typeof err === 'undefined') {
367                    console.info('create running lock: ' + lock);
368                    RunningLockTest.recordLock = lock;
369                    try {
370                        lock.unhold();
371                        console.info('unhold running lock success');
372                    } catch(err) {
373                        console.error('unhold running lock failed, err: ' + err);
374                    }
375                } else {
376                    console.error('create running lock failed, err: ' + err);
377                }
378            });
379        }
380    }
381}
382```
383
384### isHolding<sup>9+</sup>
385
386isHolding(): boolean
387
388查询当前RunningLock是持有状态还是释放状态。
389
390**系统能力：** SystemCapability.PowerManager.PowerManager.Core
391
392**返回值：**
393
394| 类型    | 说明                                                         |
395| ------- | ------------------------------------------------------------ |
396| boolean | 返回true表示当前RunningLock是持有状态，返回false表示当前RunningLock是释放状态。 |
397
398**错误码：**
399
400以下错误码的详细介绍请参见[RunningLock锁错误码](errorcode-runninglock.md)。
401
402| 错误码ID   | 错误信息    |
403|---------|---------|
404| 4900101 | Failed to connect to the service. |
405
406**示例：**
407
408```ts
409// RunningLockTest.ets
410class RunningLockTest {
411    public static recordLock: runningLock.RunningLock;
412
413    public static isHoldingRunningLock(): void {
414        if (RunningLockTest.recordLock) {
415            let isHolding = RunningLockTest.recordLock.isHolding();
416            console.info('check running lock holding status: ' + isHolding);
417        } else {
418            runningLock.create('running_lock_test', runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL, (err: Error, lock: runningLock.RunningLock) => {
419                if (typeof err === 'undefined') {
420                    console.info('create running lock: ' + lock);
421                    RunningLockTest.recordLock = lock;
422                    try {
423                        let isHolding = lock.isHolding();
424                        console.info('check running lock holding status: ' + isHolding);
425                    } catch(err) {
426                        console.error('check running lock holding status failed, err: ' + err);
427                    }
428                } else {
429                    console.error('create running lock failed, err: ' + err);
430                }
431            });
432        }
433    }
434}
435```
436
437### lock<sup>(deprecated)</sup>
438
439lock(timeout: number): void
440
441> **说明：**<br>从API version 9开始不再维护，建议使用[RunningLock.hold](#hold9)替代。
442
443锁定和持有RunningLock。
444
445**系统能力：** SystemCapability.PowerManager.PowerManager.Core
446
447**需要权限：** ohos.permission.RUNNING_LOCK
448
449**参数：**
450
451| 参数名  | 类型   | 必填 | 说明                                      |
452| ------- | ------ | ---- | ----------------------------------------- |
453| timeout | number | 是   | 锁定和持有RunningLock的时长，单位：毫秒。 |
454
455**示例：**
456
457```js
458runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
459.then((lock: runningLock.RunningLock) => {
460    lock.lock(500);
461    console.info('create running lock and lock success');
462})
463.catch((err: Error) => {
464    console.error('create running lock failed, err: ' + err);
465});
466```
467
468### unlock<sup>(deprecated)</sup>
469
470unlock(): void
471
472> **说明：**<br>从API version 9开始不再维护，建议使用[RunningLock.unhold](#unhold9)替代。
473
474释放RunningLock锁。
475
476**系统能力：** SystemCapability.PowerManager.PowerManager.Core
477
478**需要权限：** ohos.permission.RUNNING_LOCK
479
480**示例：**
481
482```js
483runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
484.then((lock: runningLock.RunningLock) => {
485    lock.unlock();
486    console.info('create running lock and unlock success');
487})
488.catch((err: Error) => {
489    console.error('create running lock failed, err: ' + err);
490});
491```
492
493### isUsed<sup>(deprecated)</sup>
494
495isUsed(): boolean
496
497> **说明：**<br>从API version 9开始不再维护，建议使用[RunningLock.isHolding](#isholding9)替代。
498
499查询当前RunningLock是持有状态还是释放状态。
500
501**系统能力：** SystemCapability.PowerManager.PowerManager.Core
502
503**返回值：**
504| 类型    | 说明                                                         |
505| ------- | ------------------------------------------------------------ |
506| boolean | 返回true表示当前RunningLock是持有状态，返回false表示当前RunningLock是释放状态。 |
507
508**示例：**
509
510```js
511runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
512.then((lock: runningLock.RunningLock) => {
513    let isUsed = lock.isUsed();
514    console.info('check running lock used status: ' + isUsed);
515})
516.catch((err: Error) => {
517    console.error('check running lock used status failed, err: ' + err);
518});
519```
520
521## RunningLockType
522
523RunningLock锁的类型。
524
525**系统能力：** SystemCapability.PowerManager.PowerManager.Core
526
527| 名称                              | 值   | 说明                                                         |
528| --------------------------------- | ---- | ------------------------------------------------------------ |
529| BACKGROUND<sup>(deprecated)</sup> | 1    | 阻止系统休眠的锁。<br>**说明：** 从API version 7开始支持，从API version 10开始废弃。 |
530| PROXIMITY_SCREEN_CONTROL          | 2    | 接近光锁，使能接近光传感器，并根据传感器与障碍物的距离远近发起亮灭屏流程。  |