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