1# @ohos.bundle.overlay (overlay模块)
2
3本模块提供[overlay特征应用](#overlay特征应用介绍)的安装，overlay特征应用的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息的查询以及overlay特征应用的禁用使能的能力。
4
5> **说明：**
6>
7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11``` ts
12import { overlay } from '@kit.AbilityKit';
13```
14
15## overlay.setOverlayEnabled
16
17setOverlayEnabled(moduleName:string, isEnabled: boolean): Promise\<void>
18
19以异步方法设置当前应用中overlay特征module的禁用使能状态。使用Promise异步回调。成功返回null，失败返回对应错误信息。
20
21**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
22
23**参数：**
24
25| 参数名       | 类型     | 必填   | 说明                                    |
26| ----------- | ------ | ---- | --------------------------------------- |
27| moduleName  | string | 是    | overlay特征module的名称。               |
28| isEnabled   | boolean  | 是  | 值为true表示使能，值为false表示禁用。 |
29
30**返回值：**
31
32| 类型                        | 说明                 |
33| ------------------------- | ------------------ |
34| Promise\<void> | Promise对象。无返回结果的Promise对象。 |
35
36**错误码：**
37
38以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
39
40| 错误码ID | 错误信息                                |
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**示例：**
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
73以异步方法设置当前应用中overlay module的禁用使能状态。使用callback异步回调。成功返回null，失败返回对应错误信息。
74
75**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
76
77**参数：**
78
79| 参数名       | 类型     | 必填   | 说明                                    |
80| ----------- | ------ | ---- | --------------------------------------- |
81| moduleName  | string | 是    | overlay特征module的名称。               |
82| isEnabled   | boolean  | 是  | 值为true表示使能，值为false表示禁用。|
83| callback    | AsyncCallback\<void> | 是    | 回调函数，当设置指定module的overlay禁用使能状态成功时，err为null，否则为错误对象。 |
84
85**错误码：**
86
87以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
88
89| 错误码ID | 错误信息                                |
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**示例：**
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
123以异步方法获取当前应用中指定的module的overlayModuleInfo信息。使用promise异步回调，成功返回null，失败返回对应错误信息。
124
125**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
126
127**参数：**
128
129| 参数名       | 类型     | 必填   | 说明                                    |
130| ----------- | ------ | ---- | ------------------------------------------ |
131| moduleName | string | 是    | 指定当前应用中的overlay module的名称。     |
132
133**返回值：**
134
135| 类型                        | 说明                 |
136| ------------------------- | ------------------ |
137| Promise\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | Promise对象，返回[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)。|
138
139**错误码：**
140
141以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
142
143| 错误码ID | 错误信息                                |
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**示例：**
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
174以异步方法获取当前应用中指定的module的overlayModuleInfo信息。使用callback异步回调，成功返回null，失败返回对应错误信息。
175
176**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
177
178**参数：**
179
180| 参数名       | 类型     | 必填   | 说明                                    |
181| ----------- | ------ | ---- | --------------------------------------- |
182| moduleName | string | 是    | 指定当前应用中的overlay特征module的名称。     |
183| callback    | AsyncCallback\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | 是    | 回调函数，当获取当前应用中指定的module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息成功时，err返回null。否则回调函数返回具体错误对象。                   |
184
185**错误码：**
186
187以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
188
189| 错误码ID | 错误信息                                |
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**示例：**
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
223以异步方法获取指定的目标module的OverlayModuleInfo。使用promise异步回调，成功返回null，失败返回对应错误信息。
224
225**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
226
227**参数：**
228
229| 参数名       | 类型     | 必填   | 说明                                    |
230| ----------- | ------ | ---- | --------------------------------------- |
231| targetModuleName | string | 是    | 指定当前应用中的目标module的名称。     |
232
233**返回值：**
234
235| 类型                                                         | 说明                                                         |
236| ------------------------------------------------------------ | ------------------------------------------------------------ |
237| Promise\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Promise对象，返回\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>>。 |
238
239**错误码：**
240
241以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
242
243| 错误码ID | 错误信息                                |
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**示例：**
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
273以异步方法获取指定的目标module的OverlayModuleInfo。使用callback异步回调，成功返回null，失败返回对应错误信息。
274
275**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
276
277**参数：**
278
279| 参数名       | 类型     | 必填   | 说明                                    |
280| ----------- | ------ | ---- | --------------------------------------- |
281| targetModuleName | string | 是    | 指定当前应用中的目标module的名称。     |
282| callback    | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | 是    | 回调函数，当获取指定的目标module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)成功时，err返回null。否则回调函数返回具体错误对象。  |
283
284**错误码：**
285
286以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。
287
288| 错误码ID | 错误信息                                |
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**示例：**
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## OverlayModuleInfo
318
319type OverlayModuleInfo = _OverlayModuleInfo.OverlayModuleInfo
320
321OverlayModuleInfo信息。
322
323**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay
324
325| 类型                                                         | 说明           |
326| ------------------------------------------------------------ | -------------- |
327| [_OverlayModuleInfo.OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md#overlaymoduleinfo-1) |OverlayModuleInfo信息。 |
328
329## overlay特征应用介绍
330
331**概念**
332overlay特征应用指的是应用中包含有overlay特征的module。该特征module一般是为设备上存在的非overlay特征的module提供额外的资源文件，以便于目标module在运行阶段可以使用这些额外的资源文件来展示不同的颜色，标签，主题等等。overlay特征仅适用于stage模型。
333
334**如何识别overlay特征的module**
335在DevEco Studio中创建应用工程时, module的配置文件module.json5中包含targetModuleName和targetPriority字段时，该module将会在安装阶段被识别为overlay特征的module。
336