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