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