1# @ohos.bundle.overlay (overlay)
2
3The **overlay** module provides APIs for installing a [module with the overlay feature](#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## Modules to Import
10
11``` ts
12import { overlay } from '@kit.AbilityKit';
13```
14
15## overlay.setOverlayEnabled
16
17setOverlayEnabled(moduleName:string, isEnabled: boolean): Promise\<void>
18
19Enables or disables a module with the overlay feature in the current application. This API uses a promise to return the result. If the operation is successful, **null** is returned; otherwise, an error message is returned.
20
21**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
22
23**Parameters**
24
25| Name      | Type    | Mandatory  | Description                                   |
26| ----------- | ------ | ---- | --------------------------------------- |
27| moduleName  | string | Yes   | Name of the module with the overlay feature.              |
28| 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.|
29
30**Return value**
31
32| Type                       | Description                |
33| ------------------------- | ------------------ |
34| Promise\<void> | Promise that returns no value.|
35
36**Error codes**
37
38For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
39
40| ID| Error Message                               |
41| ------ | -------------------------------------- |
42| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
43| 17700002 | The specified module name is not found. |
44| 17700033 | The specified module is not an overlay module. |
45
46**Example**
47
48```ts
49import { overlay } from '@kit.AbilityKit';
50import { BusinessError } from '@kit.BasicServicesKit';
51
52let moduleName = "feature";
53let isEnabled = false;
54
55try {
56  overlay.setOverlayEnabled(moduleName, isEnabled)
57    .then(() => {
58      console.info('setOverlayEnabled success');
59    }).catch((err: BusinessError) => {
60      console.info('setOverlayEnabled failed due to err code: ' + err.code + ' ' + 'message:' + err.message);
61    });
62} catch (err) {
63  let code = (err as BusinessError).code;
64  let message = (err as BusinessError).message;
65  console.info('setOverlayEnabled failed due to err code: ' + code + ' ' + 'message:' + message);
66}
67```
68
69## overlay.setOverlayEnabled
70
71setOverlayEnabled(moduleName:string, isEnabled: boolean, callback: AsyncCallback\<void>): void
72
73Enables or disables a module with the overlay feature in the current 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.
74
75**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
76
77**Parameters**
78
79| Name      | Type    | Mandatory  | Description                                   |
80| ----------- | ------ | ---- | --------------------------------------- |
81| moduleName  | string | Yes   | Name of the module with the overlay feature.              |
82| 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.|
83| callback    | AsyncCallback\<void> | Yes   | Callback used to return the result. If the operation is successful, **err** is **null**; otherwise, **err** is an error object.|
84
85**Error codes**
86
87For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
88
89| ID| Error Message                               |
90| ------ | -------------------------------------- |
91| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
92| 17700002 | The specified module name is not found. |
93| 17700033 | The specified module is not an overlay module. |
94
95**Example**
96
97```ts
98import { overlay } from '@kit.AbilityKit';
99import { BusinessError } from '@kit.BasicServicesKit';
100
101let moduleName = "feature";
102let isEnabled = false;
103
104try {
105  overlay.setOverlayEnabled(moduleName, isEnabled, (err, data) => {
106    if (err) {
107      console.info('setOverlayEnabled failed due to err code: ' + err.code + ' ' + 'message:' + err.message);
108      return;
109    }
110    console.info('setOverlayEnabled success');
111  });
112} catch (err) {
113  let code = (err as BusinessError).code;
114  let message = (err as BusinessError).message;
115  console.info('setOverlayEnabled failed due to err code: ' + code + ' ' + 'message:' + message);
116}
117```
118
119## overlay.getOverlayModuleInfo
120
121getOverlayModuleInfo(moduleName: string): Promise\<OverlayModuleInfo>
122
123Obtains the information about a module with the overlay feature in the current application. This API uses a promise to return the result. If the operation is successful, **null** is returned; otherwise, an error message is returned.
124
125**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
126
127**Parameters**
128
129| Name      | Type    | Mandatory  | Description                                   |
130| ----------- | ------ | ---- | ------------------------------------------ |
131| moduleName | string | Yes   | Name of the module with the overlay feature.    |
132
133**Return value**
134
135| Type                       | Description                |
136| ------------------------- | ------------------ |
137| Promise\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | Promise used to return the result, which is an [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) object.|
138
139**Error codes**
140
141For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
142
143| ID| Error Message                               |
144| ------ | -------------------------------------- |
145| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
146| 17700002 | The specified module name is not found. |
147| 17700032 | The specified bundle does not contain any overlay module. |
148| 17700033 | The specified module is not an overlay module. |
149
150**Example**
151
152```ts
153import { overlay } from '@kit.AbilityKit';
154import { BusinessError } from '@kit.BasicServicesKit';
155
156let moduleName = "feature";
157
158(async () => {
159  try {
160    let overlayModuleInfo = await overlay.getOverlayModuleInfo(moduleName);
161    console.log('overlayModuleInfo is ' + JSON.stringify(overlayModuleInfo));
162  } catch (err) {
163    let code = (err as BusinessError).code;
164    let message = (err as BusinessError).message;
165    console.log('getOverlayModuleInfo failed due to err code : ' + code + ' ' + 'message :' + message);
166  }
167})();
168```
169
170## overlay.getOverlayModuleInfo
171
172getOverlayModuleInfo(moduleName: string, callback: AsyncCallback\<OverlayModuleInfo>): void
173
174Obtains the information about a module with the overlay feature in the current 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.
175
176**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
177
178**Parameters**
179
180| Name      | Type    | Mandatory  | Description                                   |
181| ----------- | ------ | ---- | --------------------------------------- |
182| moduleName | string | Yes   | Name of the module with the overlay feature.    |
183| callback    | AsyncCallback\<[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.                  |
184
185**Error codes**
186
187For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
188
189| ID| Error Message                               |
190| ------ | -------------------------------------- |
191| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
192| 17700002 | The specified module name is not found. |
193| 17700032 | The specified bundle does not contain any overlay module. |
194| 17700033 | The specified module is not an overlay module. |
195
196**Example**
197
198```ts
199import { overlay } from '@kit.AbilityKit';
200import { BusinessError } from '@kit.BasicServicesKit';
201
202let moduleName = "feature";
203
204try {
205  overlay.getOverlayModuleInfo(moduleName, (err, data) => {
206    if (err) {
207      console.log('getOverlayModuleInfo failed due to err code : ' + err.code + ' ' + 'message :' + err.message);
208      return;
209    }
210    console.log('overlayModuleInfo is ' + JSON.stringify(data));
211  });
212} catch (err) {
213  let code = (err as BusinessError).code;
214  let message = (err as BusinessError).message;
215  console.log('getOverlayModuleInfo failed due to err code : ' + code + ' ' + 'message :' + message);
216}
217```
218
219## overlay.getTargetOverlayModuleInfos
220
221getTargetOverlayModuleInfos(targetModuleName: string): Promise\<Array\<OverlayModuleInfo>>
222
223Obtains the information about modules with the overlay feature in the current 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.
224
225**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
226
227**Parameters**
228
229| Name      | Type    | Mandatory  | Description                                   |
230| ----------- | ------ | ---- | --------------------------------------- |
231| targetModuleName | string | Yes   | Name of the target module specified by modules with the overlay feature.    |
232
233**Return value**
234
235| Type                                                        | Description                                                        |
236| ------------------------------------------------------------ | ------------------------------------------------------------ |
237| 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.|
238
239**Error codes**
240
241For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
242
243| ID| Error Message                               |
244| ------ | -------------------------------------- |
245| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
246| 17700002 | The specified module name is not found. |
247| 17700034 | The specified module is an overlay module. |
248
249**Example**
250
251```ts
252import { overlay } from '@kit.AbilityKit';
253import { BusinessError } from '@kit.BasicServicesKit';
254
255let targetModuleName = "feature";
256
257(async () => {
258  try {
259    let overlayModuleInfos = await overlay.getTargetOverlayModuleInfos(targetModuleName);
260    console.log('overlayModuleInfos are ' + JSON.stringify(overlayModuleInfos));
261  } catch (err) {
262    let code = (err as BusinessError).code;
263    let message = (err as BusinessError).message;
264    console.log('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message);
265  }
266})();
267```
268
269## overlay.getTargetOverlayModuleInfos
270
271getTargetOverlayModuleInfos(targetModuleName: string, callback: AsyncCallback\<Array\<OverlayModuleInfo>>): void
272
273Obtains the information about modules with the overlay feature in the current 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.
274
275**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay
276
277**Parameters**
278
279| Name      | Type    | Mandatory  | Description                                   |
280| ----------- | ------ | ---- | --------------------------------------- |
281| targetModuleName | string | Yes   | Name of the target module specified by modules with the overlay feature.    |
282| 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. |
283
284**Error codes**
285
286For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md).
287
288| ID| Error Message                               |
289| ------ | -------------------------------------- |
290| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.|
291| 17700002 | The specified module name is not found.  |
292| 17700034 | The specified module is an overlay module. |
293
294**Example**
295
296```ts
297import { overlay } from '@kit.AbilityKit';
298import { BusinessError } from '@kit.BasicServicesKit';
299
300let targetModuleName = "feature";
301
302try {
303  overlay.getTargetOverlayModuleInfos(targetModuleName, (err, data) => {
304    if (err) {
305      console.log('getTargetOverlayModuleInfos failed due to err code : ' + err.code + ' ' + 'message :' + err.message);
306      return;
307    }
308    console.log('overlayModuleInfo is ' + JSON.stringify(data));
309  });
310} catch (err) {
311  let code = (err as BusinessError).code;
312  let message = (err as BusinessError).message;
313  console.log('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message);
314}
315```
316
317## Module with the Overlay Feature
318
319**Concept**
320A module with the overlay feature generally provides additional resource files for modules without the overlay feature on the device, so that the target modules can use these resource files at runtime to display different colors, labels, themes, and the like. The overlay feature applies only to the stage model.
321
322**How do I identify a module with the overlay feature?**
323If the **module.json5** file of a module contains the **targetModuleName** and **targetPriority fields** during project creation on DevEco Studio, the module is identified as a module with the overlay feature in the installation phase.
324