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