• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.bundle.overlay (overlay模块)(系统接口)
2<!--Kit: Ability Kit-->
3<!--Subsystem: BundleManager-->
4<!--Owner: @wanghang904-->
5<!--Designer: @hanfeng6-->
6<!--Tester: @kongjing2-->
7<!--Adviser: @Brilliantry_Rui-->
8
9本模块提供[overlay特征应用](js-apis-overlay.md)的安装，overlay特征应用的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息的查询以及overlay特征应用的禁用使能的能力。
10
11> **说明：**
12>
13> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
14>
15> 当前页面仅包含本模块的系统接口，其他公开接口参见[`@ohos.bundle.overlay`](js-apis-overlay.md)。
16
17## 导入模块
18
19``` ts
20import { overlay } from '@kit.AbilityKit';
21```
22
23## overlay.setOverlayEnabledByBundleName
24
25setOverlayEnabledByBundleName(bundleName: string, moduleName: string, isEnabled: boolean): Promise\<void>
26
27设置指定应用的overlay module的禁用使能状态。使用Promise异步回调。
28
29指定应用是调用方自身时不需要权限。
30
31**需要权限：** ohos.permission.CHANGE_OVERLAY_ENABLED_STATE
32
33**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
34
35**系统接口：**  此接口为系统接口。
36
37**参数：**
38
39| 参数名       | 类型     | 必填   | 说明                                    |
40| ----------- | ------ | ---- | --------------------------------------- |
41| bundleName  | string | 是    | 指定应用的bundle名称。                 |
42| moduleName  | string | 是    | 指定应用的overlay module的名称。    |
43| isEnabled   | boolean  | 是  | 值为true表示使能，值为false表示禁用。 |
44
45**返回值：**
46
47| 类型                        | 说明                 |
48| ------------------------- | ------------------ |
49| Promise\<void> | Promise对象。无返回结果的Promise对象。 |
50
51**错误码：**
52
53以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
54
55| 错误码ID | 错误信息                                |
56| ------ | -------------------------------------- |
57| 201 | Permission denied. |
58| 202 | Permission denied, non-system app called system api. |
59| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
60| 17700001 | The specified bundleName is not found. |
61| 17700002 | The specified module name is not found. |
62| 17700032 | The specified bundle does not contain any overlay module. |
63| 17700033 | The specified module is not an overlay module. |
64
65**示例：**
66
67```ts
68import { overlay } from '@kit.AbilityKit';
69import { BusinessError } from '@kit.BasicServicesKit';
70let bundleName = "com.example.myapplication_xxxxx";
71let moduleName = "feature";
72let isEnabled = false;
73
74try {
75    overlay.setOverlayEnabledByBundleName(bundleName, moduleName, isEnabled)
76        .then((data) => {
77            console.info('setOverlayEnabledByBundleName successfully');
78        }).catch((err: BusinessError) => {
79            console.error('setOverlayEnabledByBundleName failed due to err code: ' + err.code + ' ' + 'message:' + err.message);
80        });
81} catch (err) {
82    let code = (err as BusinessError).code;
83    let message = (err as BusinessError).message;
84    console.error('setOverlayEnabledByBundleName failed due to err code: ' + code + ' ' + 'message:' + message);
85}
86```
87
88## overlay.setOverlayEnabledByBundleName
89
90setOverlayEnabledByBundleName(bundleName: string, moduleName: string, isEnabled: boolean, callback: AsyncCallback\<void>): void
91
92设置指定应用的overlay module的禁用使能状态。使用callback异步回调。
93
94指定应用是调用方自身时不需要权限。
95
96**需要权限：** ohos.permission.CHANGE_OVERLAY_ENABLED_STATE
97
98**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
99
100**系统接口：**  此接口为系统接口。
101
102**参数：**
103
104| 参数名       | 类型     | 必填   | 说明                                  |
105| ----------- | ------ | ---- | --------------------------------------- |
106| bundleName  | string | 是    | 指定应用的bundle名称。                 |
107| moduleName  | string | 是    | 指定应用的overlay特征module的名称。    |
108| isEnabled   | boolean  | 是  | 值为true表示使能，值为false表示禁用。 |
109| callback    | AsyncCallback\<void> | 是    | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)。当设置指定应用的overlay module的禁用使能状态成功时，err为null，否则为错误对象。                    |
110
111**错误码：**
112
113以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
114
115| 错误码ID | 错误信息                                |
116| ------ | -------------------------------------- |
117| 201 | Permission denied. |
118| 202 | Permission denied, non-system app called system api. |
119| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
120| 17700001 | The specified bundleName is not found. |
121| 17700002 | The specified module name is not found. |
122| 17700032 | The specified bundle does not contain any overlay module. |
123| 17700033 | The specified module is not an overlay module. |
124
125**示例：**
126
127```ts
128import { overlay } from '@kit.AbilityKit';
129import { BusinessError } from '@kit.BasicServicesKit';
130let bundleName = "com.example.myapplication_xxxxx";
131let moduleName = "feature";
132let isEnabled = false;
133
134try {
135    overlay.setOverlayEnabledByBundleName(bundleName, moduleName, isEnabled, (err, data) => {
136        if (err) {
137            console.error('setOverlayEnabledByBundleName failed due to err code: ' + err.code + ' ' + 'message:' + err.message);
138            return;
139        }
140        console.info('setOverlayEnabledByBundleName successfully');
141    });
142} catch (err) {
143    let code = (err as BusinessError).code;
144    let message = (err as BusinessError).message;
145    console.error('setOverlayEnabledByBundleName failed due to err code: ' + code + ' ' + 'message:' + message);
146}
147```
148
149## overlay.getOverlayModuleInfoByBundleName
150
151getOverlayModuleInfoByBundleName(bundleName: string, moduleName?: string): Promise\<Array\<OverlayModuleInfo>>
152
153获取指定应用中指定module的OverlayModuleInfo信息。使用promise异步回调。
154
155指定应用是调用方自身时不需要权限。
156
157**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
158
159**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
160
161**系统接口：**  此接口为系统接口。
162
163**参数：**
164
165| 参数名       | 类型     | 必填   | 说明                                    |
166| ----------- | ------ | ---- | --------------------------------------- |
167| bundleName | string | 是    | 指定应用的bundle名称。                    |
168| moduleName | string | 否    | 指定应用中的overlay module的名称。默认值：缺省该字段时，查询接口将查询指定应用中所有module的OverlayModuleInfo信息。     |
169
170**返回值：**
171
172| 类型                                                         | 说明                                                         |
173| ------------------------------------------------------------ | ------------------------------------------------------------ |
174| Promise\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Promise对象，返回\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>>。 |
175
176**错误码：**
177
178以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
179
180| 错误码ID | 错误信息                                |
181| ------ | -------------------------------------- |
182| 201 | Permission denied. |
183| 202 | Permission denied, non-system app called system api. |
184| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
185| 17700001 | The specified bundleName is not found. |
186| 17700002 | The specified module name is not found. |
187| 17700032 | The specified bundle does not contain any overlay module. |
188| 17700033 | The specified module is not an overlay module. |
189
190**示例：**
191
192```ts
193import { overlay } from '@kit.AbilityKit';
194import { BusinessError } from '@kit.BasicServicesKit';
195let bundleName = "com.example.myapplication_xxxxx";
196let moduleName = "feature";
197
198(async() => {
199    try {
200        let overlayModuleInfos = await overlay.getOverlayModuleInfoByBundleName(bundleName, moduleName);
201        console.info('overlayModuleInfos are ' + JSON.stringify(overlayModuleInfos));
202    } catch(err) {
203        let code = (err as BusinessError).code;
204        let message = (err as BusinessError).message;
205        console.error('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message);
206    }
207})();
208```
209
210## overlay.getOverlayModuleInfoByBundleName
211
212getOverlayModuleInfoByBundleName(bundleName: string, moduleName: string, callback: AsyncCallback\<Array\<OverlayModuleInfo>>): void
213
214获取指定应用中指定module的OverlayModuleInfo信息。使用callback异步回调。
215
216指定应用是调用方自身时不需要权限。
217
218**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
219
220**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
221
222**系统接口：**  此接口为系统接口。
223
224**参数：**
225
226| 参数名       | 类型     | 必填   | 说明                                    |
227| ----------- | ------ | ---- | --------------------------------------- |
228| bundleName | string | 是    | 指定应用的bundle名称。                    |
229| moduleName | string | 是    | 指定应用中的overlay module的名称。缺省该字段时，查询接口将查询指定应用中所有module的OverlayModuleInfo信息。     |
230| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | 是    | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，当获取指定应用中指定module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息成功时，err返回null。否则回调函数返回具体错误对象。    |
231
232**错误码：**
233
234以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
235
236| 错误码ID | 错误信息                                |
237| ------ | -------------------------------------- |
238| 201 | Permission denied. |
239| 202 | Permission denied, non-system app called system api. |
240| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
241| 17700001 | The specified bundleName is not found. |
242| 17700002 | The specified module name is not found. |
243| 17700032 | The specified bundle does not contain any overlay module. |
244| 17700033 | The specified module is not an overlay module. |
245
246**示例：**
247
248```ts
249import { overlay } from '@kit.AbilityKit';
250import { BusinessError } from '@kit.BasicServicesKit';
251let bundleName = "com.example.myapplication_xxxxx";
252let moduleName = "feature";
253
254try {
255    overlay.getOverlayModuleInfoByBundleName(bundleName, moduleName, (err, data) => {
256        if (err) {
257            console.error('getOverlayModuleInfoByBundleName failed due to err code : ' + err.code + ' ' + 'message :' + err.message);
258            return;
259        }
260        console.info('overlayModuleInfo is ' + JSON.stringify(data));
261    });
262} catch (err) {
263    let code = (err as BusinessError).code;
264    let message = (err as BusinessError).message;
265    console.error('getOverlayModuleInfoByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
266}
267```
268
269## overlay.getOverlayModuleInfoByBundleName
270
271getOverlayModuleInfoByBundleName(bundleName: string, callback: AsyncCallback\<Array\<OverlayModuleInfo>>): void
272
273获取指定应用中所有module的OverlayModuleInfo信息。使用callback异步回调。
274
275指定应用是调用方自身时不需要权限。
276
277**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
278
279**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
280
281**系统接口：**  此接口为系统接口。
282
283**参数：**
284
285| 参数名       | 类型     | 必填   | 说明                                    |
286| ----------- | ------ | ---- | --------------------------------------- |
287| bundleName | string | 是    | 指定应用的bundle名称。                    |
288| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | 是    | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，当获取指定应用中所有module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息成功时，err返回null。否则回调函数返回具体错误对象。                   |
289
290**错误码：**
291
292以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
293
294| 错误码ID | 错误信息                                |
295| ------ | -------------------------------------- |
296| 201 | Permission denied. |
297| 202 | Permission denied, non-system app called system api. |
298| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
299| 17700001 | The specified bundleName is not found. |
300| 17700032 | The specified bundle does not contain any overlay module. |
301
302**示例：**
303
304```ts
305import { overlay } from '@kit.AbilityKit';
306import { BusinessError } from '@kit.BasicServicesKit';
307let bundleName = "com.example.myapplication_xxxxx";
308
309try {
310    overlay.getOverlayModuleInfoByBundleName(bundleName, (err, data) => {
311        if (err) {
312            console.error('getOverlayModuleInfoByBundleName failed due to err code : ' + err.code + ' ' + 'message :' + err.message);
313            return;
314        }
315        console.info('overlayModuleInfo is ' + JSON.stringify(data));
316    });
317} catch (err) {
318    let code = (err as BusinessError).code;
319    let message = (err as BusinessError).message;
320    console.error('getOverlayModuleInfoByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
321}
322```
323
324## overlay.getTargetOverlayModuleInfosByBundleName
325
326getTargetOverlayModuleInfosByBundleName(targetBundleName: string, moduleName?: string): Promise\<Array\<OverlayModuleInfo>>
327
328获取指定应用中指定module关联的所有OverlayModuleInfo信息。使用promise异步回调。
329
330指定应用是调用方自身时不需要权限。
331
332**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
333
334**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
335
336**系统接口：**  此接口为系统接口。
337
338**参数：**
339
340| 参数名       | 类型     | 必填   | 说明                                    |
341| ----------- | ------ | ---- | --------------------------------------- |
342| targetBundleName | string | 是    | 指定目标应用的bundle名称。                    |
343| moduleName | string | 否    | 指定应用中的目标module的名称。默认值：缺省该字段时，查询接口将查询指定应用中所有module所关联的OverlayModuleInfo信息。     |
344
345**返回值：**
346
347| 类型                        | 说明                 |
348| ------------------------- | ------------------ |
349| Promise\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Promise对象，返回\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>>。 |
350
351**错误码：**
352
353以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
354
355| 错误码ID | 错误信息                                |
356| ------ | -------------------------------------- |
357| 201 | Permission denied. |
358| 202 | Permission denied, non-system app called system api. |
359| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
360| 17700001 | The specified bundleName is not found. |
361| 17700002 | The specified module name is not found. |
362| 17700034 | The specified module is an overlay module. |
363| 17700035 | The specified bundle is an overlay bundle. |
364
365**示例：**
366
367```ts
368import { overlay } from '@kit.AbilityKit';
369import { BusinessError } from '@kit.BasicServicesKit';
370let targetBundleName = "com.example.myapplication_xxxxx";
371let moduleName = "feature";
372
373(async() => {
374    try {
375        let overlayModuleInfos = await overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, moduleName);
376        console.info('overlayModuleInfos are ' + JSON.stringify(overlayModuleInfos));
377    } catch(err) {
378        let code = (err as BusinessError).code;
379        let message = (err as BusinessError).message;
380        console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
381    }
382})();
383```
384
385## overlay.getTargetOverlayModuleInfosByBundleName
386
387getTargetOverlayModuleInfosByBundleName(targetBundleName: string, moduleName: string, callback: AsyncCallback&lt;Array&lt;OverlayModuleInfo&gt;&gt;): void
388
389获取指定应用中指定module关联的所有OverlayModuleInfo信息。使用callback异步回调。
390
391指定应用是调用方自身时不需要权限。
392
393**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
394
395**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
396
397**系统接口：**  此接口为系统接口。
398
399**参数：**
400
401| 参数名       | 类型     | 必填   | 说明                                    |
402| ----------- | ------ | ---- | --------------------------------------- |
403| targetBundleName | string | 是    | 指定目标应用的bundle名称。                    |
404| moduleName | string | 是    | 指定应用中的目标module的名称。缺省该字段时，查询接口将查询指定应用中所有module所关联的OverlayModuleInfo信息。     |
405| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | 是    | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，当获取指定应用中指定module关联的所有[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息成功时，err返回null。否则回调函数返回具体错误对象。                   |
406
407**错误码：**
408
409以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
410
411| 错误码ID | 错误信息                                |
412| ------ | -------------------------------------- |
413| 201 | Permission denied. |
414| 202 | Permission denied, non-system app called system api. |
415| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
416| 17700001 | The specified bundleName is not found. |
417| 17700002 | The specified module name is not found. |
418| 17700034 | The specified module is an overlay module. |
419| 17700035 | The specified bundle is an overlay bundle. |
420
421**示例：**
422
423```ts
424import { overlay } from '@kit.AbilityKit';
425import { BusinessError } from '@kit.BasicServicesKit';
426let targetBundleName = "com.example.myapplication_xxxxx";
427let moduleName = "feature";
428
429try {
430    overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, moduleName, (err, data) => {
431        if (err) {
432            console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + err.code + ' ' + 'message :' + err.message);
433            return;
434        }
435        console.info('overlayModuleInfo is ' + JSON.stringify(data));
436    });
437} catch (err) {
438    let code = (err as BusinessError).code;
439    let message = (err as BusinessError).message;
440    console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
441}
442```
443
444## overlay.getTargetOverlayModuleInfosByBundleName
445
446getTargetOverlayModuleInfosByBundleName(targetBundleName: string, callback: AsyncCallback&lt;Array&lt;OverlayModuleInfo&gt;&gt;): void
447
448获取指定应用中所有module关联的所有OverlayModuleInfo信息。使用callback异步回调。
449
450指定应用是调用方自身时不需要权限。
451
452**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
453
454**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
455
456**系统接口：**  此接口为系统接口。
457
458**参数：**
459
460| 参数名       | 类型     | 必填   | 说明                                    |
461| ----------- | ------ | ---- | --------------------------------------- |
462| targetBundleName | string | 是    | 指定目标应用的bundle名称。                    |
463| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | 是    | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，当获取指定应用中所有module关联的所有[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息成功时，err返回null。否则回调函数返回具体错误对象。                   |
464
465**错误码：**
466
467以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
468
469| 错误码ID | 错误信息                                |
470| ------ | -------------------------------------- |
471| 201 | Permission denied. |
472| 202 | Permission denied, non-system app called system api. |
473| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
474| 17700001 | The specified bundleName is not found. |
475| 17700035 | The specified bundle is an overlay bundle. |
476
477**示例：**
478
479```ts
480import { overlay } from '@kit.AbilityKit';
481import { BusinessError } from '@kit.BasicServicesKit';
482let targetBundleName = "com.example.myapplication_xxxxx";
483
484try {
485    overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, (err, data) => {
486        if (err) {
487            console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + err.code + ' ' + 'message :' + err.message);
488            return;
489        }
490        console.info('overlayModuleInfo is ' + JSON.stringify(data));
491    });
492} catch (err) {
493    let code = (err as BusinessError).code;
494    let message = (err as BusinessError).message;
495    console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
496}
497```