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