1# @ohos.bundle.overlay (overlay) (System API)
2
3The **overlay** module provides APIs for installing a [module with the overlay feature]((js-apis-overlay.md#module-with-the-overlay-feature), querying the [module information](js-apis-bundleManager-overlayModuleInfo.md), and disabling and enabling the module.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.bundle.overlay](js-apis-overlay.md).
10
11## Modules to Import
12
13``` ts
14import { overlay } from '@kit.AbilityKit';
15```
16
17## overlay.setOverlayEnabledByBundleName
18
19setOverlayEnabledByBundleName(bundleName:string, moduleName:string, isEnabled: boolean): Promise\<void>
20
21Enables or disables a module with the overlay feature in another application. This API uses a promise to return the result. If the operation is successful, the processing result is returned; otherwise, an error message is returned.
22
23**Required permissions**: ohos.permission.CHANGE_OVERLAY_ENABLED_STATE
24
25**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
26
27**System API**: This is a system API.
28
29**Parameters**
30
31| Name      | Type    | Mandatory  | Description                                   |
32| ----------- | ------ | ---- | --------------------------------------- |
33| bundleName  | string | Yes   | Bundle name of the application.                |
34| moduleName  | string | Yes   | Name of the module with the overlay feature.   |
35| isEnabled   | boolean  | Yes | Whether to enable the module with the overlay feature. The value **true** means to enable the module, and **false** means to disable the module. |
36
37**Return value**
38
39| Type                       | Description                |
40| ------------------------- | ------------------ |
41| Promise\<void> | Promise that returns no value. |
42
43**Error codes**
44
45For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
46
47| ID | Error Message                               |
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**Example**
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
84Enables or disables a module with the overlay feature in another application. This API uses an asynchronous callback to return the result. If the operation is successful, the processing result is returned; otherwise, an error message is returned.
85
86**Required permissions**: ohos.permission.CHANGE_OVERLAY_ENABLED_STATE
87
88**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
89
90**System API**: This is a system API.
91
92**Parameters**
93
94| Name      | Type    | Mandatory  | Description                                 |
95| ----------- | ------ | ---- | --------------------------------------- |
96| bundleName  | string | Yes   | Bundle name of the application.                |
97| moduleName  | string | Yes   | Name of the module with the overlay feature.   |
98| isEnabled   | boolean  | Yes | Whether to enable the module with the overlay feature. The value **true** means to enable the module, and **false** means to disable the module. |
99| callback    | AsyncCallback\<void> | Yes   | Callback used to return the result. If the operation is successful, **err** is **null**; otherwise, **err** is an error object.                   |
100
101**Error codes**
102
103For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
104
105| ID | Error Message                               |
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**Example**
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
143Obtains the information about a module with the overlay feature in another application. This API uses a promise to return the result. If the operation is successful, **null** is returned; otherwise, an error message is returned.
144
145**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
146
147**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
148
149**System API**: This is a system API.
150
151**Parameters**
152
153| Name      | Type    | Mandatory  | Description                                   |
154| ----------- | ------ | ---- | --------------------------------------- |
155| bundleName | string | Yes   | Bundle name of the application.                   |
156| moduleName | string | No   | Name of the module with the overlay feature. By default, no value is passed, and the API obtains the information of all modules with the overlay feature in that application.    |
157
158**Return value**
159
160| Type                                                        | Description                                                        |
161| ------------------------------------------------------------ | ------------------------------------------------------------ |
162| Promise\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Promise used to return the result, which is an array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. |
163
164**Error codes**
165
166For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
167
168| ID | Error Message                               |
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**Example**
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
202Obtains the information about a module with the overlay feature in another application. This API uses an asynchronous callback to return the result. If the operation is successful, **null** is returned; otherwise, an error message is returned.
203
204**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
205
206**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
207
208**System API**: This is a system API.
209
210**Parameters**
211
212| Name      | Type    | Mandatory  | Description                                   |
213| ----------- | ------ | ---- | --------------------------------------- |
214| bundleName | string | Yes   | Bundle name of the application.                   |
215| moduleName | string | Yes   | Name of the module with the overlay feature. If this parameter is not specified, the API obtains the information of all modules with the overlay feature in that application.    |
216| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Yes   | Callback used to return the result, which is an array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. If the operation is successful, **err** is **null**; otherwise, **err** is an error object.   |
217
218**Error codes**
219
220For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
221
222| ID | Error Message                               |
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**Example**
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
259Obtains the information about all modules with the overlay feature in another application. This API uses an asynchronous callback to return the result. If the operation is successful, **null** is returned; otherwise, an error message is returned.
260
261**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
262
263**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
264
265**System API**: This is a system API.
266
267**Parameters**
268
269| Name      | Type    | Mandatory  | Description                                   |
270| ----------- | ------ | ---- | --------------------------------------- |
271| bundleName | string | Yes   | Bundle name of the application.                   |
272| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Yes   | Callback used to return the result, which is an [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) object. If the operation is successful, **err** is **null**; otherwise, **err** is an error object.                  |
273
274**Error codes**
275
276For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
277
278| ID | Error Message                               |
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**Example**
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
312Obtains the information about modules with the overlay feature in another application based on the target module name. This API uses a promise to return the result. If the operation is successful, **null** is returned; otherwise, an error message is returned.
313
314**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
315
316**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
317
318**System API**: This is a system API.
319
320**Parameters**
321
322| Name      | Type    | Mandatory  | Description                                   |
323| ----------- | ------ | ---- | --------------------------------------- |
324| targetBundleName | string | Yes   | Bundle name of the application.                   |
325| moduleName | string | No   | Name of the target module, which is **targetModuleName** specified by modules with the overlay feature. By default, no value is passed, and the API obtains the information associated with all modules in that application.    |
326
327**Return value**
328
329| Type                       | Description                |
330| ------------------------- | ------------------ |
331| Promise\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Promise used to return the result, which is an array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. |
332
333**Error codes**
334
335For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
336
337| ID | Error Message                               |
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**Example**
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
371Obtains the information about modules with the overlay feature in another application based on the target module name. This API uses an asynchronous callback to return the result. If the operation is successful, **null** is returned; otherwise, an error message is returned.
372
373**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
374
375**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
376
377**System API**: This is a system API.
378
379**Parameters**
380
381| Name      | Type    | Mandatory  | Description                                   |
382| ----------- | ------ | ---- | --------------------------------------- |
383| targetBundleName | string | Yes   | Bundle name of the application.                   |
384| moduleName | string | Yes   | Name of the target module, which is **targetModuleName** specified by modules with the overlay feature. If this parameter is not specified, the API obtains the information associated with all modules in that application.    |
385| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Yes   | Callback used to return the result, which is an array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. If the operation is successful, **err** is **null**; otherwise, **err** is an error object.                  |
386
387**Error codes**
388
389For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
390
391| ID | Error Message                               |
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**Example**
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
428Obtains the information about all modules with the overlay feature in another application. This API uses an asynchronous callback to return the result. If the operation is successful, **null** is returned; otherwise, an error message is returned.
429
430**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
431
432**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
433
434**System API**: This is a system API.
435
436**Parameters**
437
438| Name      | Type    | Mandatory  | Description                                   |
439| ----------- | ------ | ---- | --------------------------------------- |
440| targetBundleName | string | Yes   | Bundle name of the application.                   |
441| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Yes   | Callback used to return the result, which is an array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. If the operation is successful, **err** is **null**; otherwise, **err** is an error object.                  |
442
443**Error codes**
444
445For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
446
447| ID | Error Message                               |
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**Example**
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```
476