• 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 '@ohos.runningLock';
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锁错误码](../errorcodes/errorcode-runninglock.md)。
38
39| 错误码ID   | 错误信息    |
40|---------|---------|
41| 4900101 | If connecting to the service failed. |
42
43**示例：**
44
45```js
46try {
47    var isSupported = runningLock.isSupported(runningLock.RunningLockType.BACKGROUND);
48    console.info('BACKGROUND type supported: ' + isSupported);
49} catch(err) {
50    console.error('check supported failed, err: ' + err);
51}
52```
53
54## runningLock.create<sup>9+</sup>
55
56create(name: string, type: RunningLockType, callback: AsyncCallback&lt;RunningLock&gt;): void
57
58创建RunningLock锁。
59
60**系统能力：** SystemCapability.PowerManager.PowerManager.Core
61
62**需要权限：** ohos.permission.RUNNING_LOCK
63
64**参数：**
65
66| 参数名   | 类型                                       | 必填 | 说明                                                         |
67| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ |
68| name     | string                                     | 是   | 锁的名字。                                                   |
69| type     | [RunningLockType](#runninglocktype)        | 是   | 要创建的锁的类型。                                           |
70| callback | AsyncCallback<[RunningLock](#runninglock)> | 是   | 回调函数。当创建锁成功，err为undefined，data为创建的RunningLock；否则为错误对象。 |
71
72**错误码：**
73
74以下错误码的详细介绍请参见[RunningLock锁错误码](../errorcodes/errorcode-runninglock.md)。
75
76| 错误码ID   | 错误信息     |
77|---------|----------|
78| 4900101 | If connecting to the service failed. |
79
80**示例：**
81
82```js
83runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND, (err, lock) => {
84    if (typeof err === 'undefined') {
85        console.info('created running lock: ' + lock);
86    } else {
87        console.error('create running lock failed, err: ' + err);
88    }
89});
90```
91
92## runningLock.create<sup>9+</sup>
93
94create(name: string, type: RunningLockType): Promise&lt;RunningLock&gt;
95
96创建RunningLock锁。
97
98**系统能力：** SystemCapability.PowerManager.PowerManager.Core
99
100**需要权限：** ohos.permission.RUNNING_LOCK
101
102**参数：**
103
104| 参数名 | 类型                                | 必填 | 说明               |
105| ------ | ----------------------------------- | ---- | ------------------ |
106| name   | string                              | 是   | 锁的名字。         |
107| type   | [RunningLockType](#runninglocktype) | 是   | 要创建的锁的类型。 |
108
109**返回值：**
110
111| 类型                                       | 说明                                 |
112| ------------------------------------------ | ------------------------------------ |
113| Promise&lt;[RunningLock](#runninglock)&gt; | Promise对象，返回RunningLock锁对象。 |
114
115**错误码：**
116
117以下错误码的详细介绍请参见[RunningLock锁错误码](../errorcodes/errorcode-runninglock.md)。
118
119| 错误码ID   | 错误信息     |
120|---------|----------|
121| 4900101 | If connecting to the service failed. |
122
123**示例：**
124
125```js
126runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND)
127.then(lock => {
128    console.info('created running lock: ' + lock);
129})
130.catch(err => {
131    console.error('create running lock failed, error: ' + err);
132});
133```
134
135## runningLock.isRunningLockTypeSupported<sup>(deprecated)</sup>
136
137isRunningLockTypeSupported(type: RunningLockType, callback: AsyncCallback&lt;boolean&gt;): void
138
139> **说明：**<br>从API version 9开始不再维护，建议使用[runningLock.isSupported](#runninglockissupported9)替代。
140
141查询系统是否支持该类型的锁。使用callback异步回调。
142
143**系统能力：** SystemCapability.PowerManager.PowerManager.Core
144
145**参数：**
146
147| 参数名   | 类型                                | 必填 | 说明                                                         |
148| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ |
149| type     | [RunningLockType](#runninglocktype) | 是   | 需要查询的锁的类型。                                         |
150| callback | AsyncCallback&lt;boolean&gt;        | 是   | 回调函数。当查询成功，err为undefined，data为获取到的支持情况，返回true表示支持，返回false表示不支持；否则为错误对象。 |
151
152**示例：**
153
154```js
155runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND, (err, data) => {
156    if (typeof err === 'undefined') {
157        console.info('BACKGROUND lock support status: ' + data);
158    } else {
159        console.log('check BACKGROUND lock support status failed, err: ' + err);
160    }
161});
162```
163
164## runningLock.isRunningLockTypeSupported<sup>(deprecated)</sup>
165
166isRunningLockTypeSupported(type: RunningLockType): Promise&lt;boolean>
167
168> **说明：**<br>从API version 9开始不再维护，建议使用[runningLock.isSupported](#runninglockissupported9)替代。
169
170查询系统是否支持该类型的锁。使用Promise异步回调。
171
172**系统能力：** SystemCapability.PowerManager.PowerManager.Core
173
174**参数：**
175
176| 参数名 | 类型                                | 必填 | 说明                 |
177| ------ | ----------------------------------- | ---- | -------------------- |
178| type   | [RunningLockType](#runninglocktype) | 是   | 需要查询的锁的类型。 |
179
180**返回值：**
181
182| 类型                   | 说明                                                 |
183| ---------------------- | ---------------------------------------------------- |
184| Promise&lt;boolean&gt; | Promise对象。返回true表示支持；返回false表示不支持。 |
185
186**示例：**
187
188```js
189runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND)
190.then(data => {
191    console.info('BACKGROUND lock support status: ' + data);
192})
193.catch(err => {
194    console.log('check BACKGROUND lock support status failed, err: ' + err);
195});
196```
197
198## runningLock.createRunningLock<sup>(deprecated)</sup>
199
200createRunningLock(name: string, type: RunningLockType, callback: AsyncCallback&lt;RunningLock&gt;): void
201
202> **说明：**<br>从API version 9开始不再维护，建议使用[runningLock.create](#runninglockcreate9)替代。
203
204创建RunningLock锁。
205
206**系统能力：** SystemCapability.PowerManager.PowerManager.Core
207
208**需要权限：** ohos.permission.RUNNING_LOCK
209
210**参数：**
211
212| 参数名   | 类型                                       | 必填 | 说明                                                         |
213| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ |
214| name     | string                                     | 是   | 锁的名字。                                                   |
215| type     | [RunningLockType](#runninglocktype)        | 是   | 要创建的锁的类型。                                           |
216| callback | AsyncCallback<[RunningLock](#runninglock)> | 是   | 回调函数。当创建锁成功，err为undefined，data为创建的RunningLock；否则为错误对象。 |
217
218**示例：**
219
220```js
221runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND, (err, lock) => {
222    if (typeof err === 'undefined') {
223        console.info('created running lock: ' + lock);
224    } else {
225        console.error('create running lock failed, err: ' + err);
226    }
227});
228```
229
230## runningLock.createRunningLock<sup>(deprecated)</sup>
231
232createRunningLock(name: string, type: RunningLockType): Promise&lt;RunningLock&gt;
233
234> **说明：**<br>从API version 9开始不再维护，建议使用[runningLock.create](#runninglockcreate9)替代。
235
236创建RunningLock锁。
237
238**系统能力：** SystemCapability.PowerManager.PowerManager.Core
239
240**需要权限：** ohos.permission.RUNNING_LOCK
241
242**参数：**
243
244| 参数名 | 类型                                | 必填 | 说明               |
245| ------ | ----------------------------------- | ---- | ------------------ |
246| name   | string                              | 是   | 锁的名字。         |
247| type   | [RunningLockType](#runninglocktype) | 是   | 要创建的锁的类型。 |
248
249**返回值：**
250
251| 类型                                       | 说明                                 |
252| ------------------------------------------ | ------------------------------------ |
253| Promise&lt;[RunningLock](#runninglock)&gt; | Promise对象，返回RunningLock锁对象。 |
254
255**示例：**
256
257```js
258runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
259.then(lock => {
260    console.info('created running lock: ' + lock);
261})
262.catch(err => {
263    console.log('create running lock failed, err: ' + err);
264});
265```
266
267## RunningLock
268
269阻止系统休眠的锁。
270
271### hold<sup>9+</sup>
272
273hold(timeout: number): void
274
275锁定和持有RunningLock。
276
277**系统能力：** SystemCapability.PowerManager.PowerManager.Core
278
279**需要权限：** ohos.permission.RUNNING_LOCK
280
281**参数：**
282
283| 参数名  | 类型   | 必填 | 说明                                      |
284| ------- | ------ | ---- | ----------------------------------------- |
285| timeout | number | 是   | 锁定和持有RunningLock的时长，单位：毫秒。 |
286
287**错误码：**
288
289以下错误码的详细介绍请参见[RunningLock锁错误码](../errorcodes/errorcode-runninglock.md)。
290
291| 错误码ID   | 错误信息     |
292|---------|----------|
293| 4900101 | If connecting to the service failed. |
294
295**示例：**
296
297```js
298runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND)
299.then(lock => {
300    console.info('create running lock success');
301    try {
302        lock.hold(500);
303        console.info('hold running lock success');
304    } catch(err) {
305        console.error('hold running lock failed, err: ' + err);
306    }
307})
308.catch(err => {
309    console.error('create running lock failed, err: ' + err);
310});
311```
312
313### unhold<sup>9+</sup>
314
315unhold(): void
316
317释放RunningLock锁。
318
319**系统能力：** SystemCapability.PowerManager.PowerManager.Core
320
321**需要权限：** ohos.permission.RUNNING_LOCK
322
323**错误码：**
324
325以下错误码的详细介绍请参见[RunningLock锁错误码](../errorcodes/errorcode-runninglock.md)。
326
327| 错误码ID   | 错误信息     |
328|---------|----------|
329| 4900101 | If connecting to the service failed. |
330
331**示例：**
332
333```js
334runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND)
335.then(lock => {
336    console.info('create running lock success');
337    try {
338        lock.unhold();
339        console.info('unhold running lock success');
340    } catch(err) {
341        console.error('unhold running lock failed, err: ' + err);
342    }
343})
344.catch(err => {
345    console.error('create running lock failed, err: ' + err);
346});
347```
348
349### isHolding<sup>9+</sup>
350
351isHolding(): boolean
352
353查询当前RunningLock是持有状态还是释放状态。
354
355**系统能力：** SystemCapability.PowerManager.PowerManager.Core
356
357**返回值：**
358
359| 类型    | 说明                                                         |
360| ------- | ------------------------------------------------------------ |
361| boolean | 返回true表示当前RunningLock是持有状态，返回false表示当前RunningLock是释放状态。 |
362
363**错误码：**
364
365以下错误码的详细介绍请参见[RunningLock锁错误码](../errorcodes/errorcode-runninglock.md)。
366
367| 错误码ID   | 错误信息    |
368|---------|---------|
369| 4900101 | If connecting to the service failed. |
370
371**示例：**
372
373```js
374runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND)
375.then(lock => {
376    console.info('create running lock success');
377    try {
378        var isHolding = lock.isHolding();
379        console.info('check running lock holding status: ' + isHolding);
380    } catch(err) {
381        console.error('check running lock holding status failed, err: ' + err);
382    }
383})
384.catch(err => {
385    console.error('create running lock failed, err: ' + err);
386});
387```
388
389### lock<sup>(deprecated)</sup>
390
391lock(timeout: number): void
392
393> **说明：**<br>从API version 9开始不再维护，建议使用[RunningLock.hold](#hold9)替代。
394
395锁定和持有RunningLock。
396
397**系统能力：** SystemCapability.PowerManager.PowerManager.Core
398
399**需要权限：** ohos.permission.RUNNING_LOCK
400
401**参数：**
402
403| 参数名  | 类型   | 必填 | 说明                                      |
404| ------- | ------ | ---- | ----------------------------------------- |
405| timeout | number | 是   | 锁定和持有RunningLock的时长，单位：毫秒。 |
406
407**示例：**
408
409```js
410runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
411.then(lock => {
412    lock.lock(500);
413    console.info('create running lock and lock success');
414})
415.catch(err => {
416    console.error('create running lock failed, err: ' + err);
417});
418```
419
420### unlock<sup>(deprecated)</sup>
421
422unlock(): void
423
424> **说明：**<br>从API version 9开始不再维护，建议使用[RunningLock.unhold](#unhold9)替代。
425
426释放RunningLock锁。
427
428**系统能力：** SystemCapability.PowerManager.PowerManager.Core
429
430**需要权限：** ohos.permission.RUNNING_LOCK
431
432**示例：**
433
434```js
435runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
436.then(lock => {
437    lock.unlock();
438    console.info('create running lock and unlock success');
439})
440.catch(err => {
441    console.error('create running lock failed, err: ' + err);
442});
443```
444
445### isUsed<sup>(deprecated)</sup>
446
447isUsed(): boolean
448
449> **说明：**<br>从API version 9开始不再维护，建议使用[RunningLock.isHolding](#isholding9)替代。
450
451查询当前RunningLock是持有状态还是释放状态。
452
453**系统能力：** SystemCapability.PowerManager.PowerManager.Core
454
455**返回值：**
456| 类型    | 说明                                                         |
457| ------- | ------------------------------------------------------------ |
458| boolean | 返回true表示当前RunningLock是持有状态，返回false表示当前RunningLock是释放状态。 |
459
460**示例：**
461
462```js
463runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND)
464.then(lock => {
465    var isUsed = lock.isUsed();
466    console.info('check running lock used status: ' + isUsed);
467})
468.catch(err => {
469    console.error('check running lock used status failed, err: ' + err);
470});
471```
472
473## RunningLockType
474
475RunningLock锁的类型。
476
477**系统能力：** SystemCapability.PowerManager.PowerManager.Core
478
479| 名称                     | 值   | 说明                                   |
480| ------------------------ | ---- | -------------------------------------- |
481| BACKGROUND               | 1    | 阻止系统休眠的锁。                     |
482| PROXIMITY_SCREEN_CONTROL | 2    | 通过接近或者远离状态来控制亮灭屏的锁。 |
483