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 '@ohos.bundle.overlay'; 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 [Bundle Error Codes](errorcode-bundle.md). 39 40| ID| Error Message | 41| ------ | -------------------------------------- | 42| 17700002 | The specified module name is not found. | 43| 17700033 | The specified module is not an overlay module. | 44 45**Example** 46 47```ts 48import overlay from '@ohos.bundle.overlay'; 49import { BusinessError } from '@ohos.base'; 50let moduleName = "feature"; 51let isEnabled = false; 52 53try { 54 overlay.setOverlayEnabled(moduleName, isEnabled) 55 .then(() => { 56 console.info('setOverlayEnabled success'); 57 }).catch((err: BusinessError) => { 58 console.info('setOverlayEnabled failed due to err code: ' + err.code + ' ' + 'message:' + err.message); 59 }); 60} catch (err) { 61 let code = (err as BusinessError).code; 62 let message = (err as BusinessError).message; 63 console.info('setOverlayEnabled failed due to err code: ' + code + ' ' + 'message:' + message); 64} 65``` 66 67## overlay.setOverlayEnabled 68 69setOverlayEnabled(moduleName:string, isEnabled: boolean, callback: AsyncCallback\<void>): void 70 71Enables 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. 72 73**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 74 75**Parameters** 76 77| Name | Type | Mandatory | Description | 78| ----------- | ------ | ---- | --------------------------------------- | 79| moduleName | string | Yes | Name of the module with the overlay feature. | 80| 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.| 81| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **null**; otherwise, **err** is an error object.| 82 83**Error codes** 84 85For details about the error codes, see [Bundle Error Codes](errorcode-bundle.md). 86 87| ID| Error Message | 88| ------ | -------------------------------------- | 89| 17700002 | The specified module name is not found. | 90| 17700033 | The specified module is not an overlay module. | 91 92**Example** 93 94```ts 95import overlay from '@ohos.bundle.overlay'; 96import { BusinessError } from '@ohos.base'; 97let moduleName = "feature"; 98let isEnabled = false; 99 100try { 101 overlay.setOverlayEnabled(moduleName, isEnabled, (err, data) => { 102 if (err) { 103 console.info('setOverlayEnabled failed due to err code: ' + err.code + ' ' + 'message:' + err.message); 104 return; 105 } 106 console.info('setOverlayEnabled success'); 107 }); 108} catch (err) { 109 let code = (err as BusinessError).code; 110 let message = (err as BusinessError).message; 111 console.info('setOverlayEnabled failed due to err code: ' + code + ' ' + 'message:' + message); 112} 113``` 114 115## overlay.getOverlayModuleInfo 116 117getOverlayModuleInfo(moduleName: string): Promise\<OverlayModuleInfo> 118 119Obtains 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. 120 121**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 122 123**Parameters** 124 125| Name | Type | Mandatory | Description | 126| ----------- | ------ | ---- | ------------------------------------------ | 127| moduleName | string | Yes | Name of the module with the overlay feature. | 128 129**Return value** 130 131| Type | Description | 132| ------------------------- | ------------------ | 133| Promise\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | Promise used to return the result, which is an [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) object.| 134 135**Error codes** 136 137For details about the error codes, see [Bundle Error Codes](errorcode-bundle.md). 138 139| ID| Error Message | 140| ------ | -------------------------------------- | 141| 17700002 | The specified module name is not found. | 142| 17700032 | The specified bundle does not contain any overlay module. | 143| 17700033 | The specified module is not an overlay module. | 144 145**Example** 146 147```ts 148import overlay from '@ohos.bundle.overlay'; 149import { BusinessError } from '@ohos.base'; 150let moduleName = "feature"; 151 152(async() => { 153 try { 154 let overlayModuleInfo = await overlay.getOverlayModuleInfo(moduleName); 155 console.log('overlayModuleInfo is ' + JSON.stringify(overlayModuleInfo)); 156 } catch(err) { 157 let code = (err as BusinessError).code; 158 let message = (err as BusinessError).message; 159 console.log('getOverlayModuleInfo failed due to err code : ' + code + ' ' + 'message :' + message); 160 } 161})(); 162``` 163 164## overlay.getOverlayModuleInfo 165 166getOverlayModuleInfo(moduleName: string, callback: AsyncCallback\<OverlayModuleInfo>): void 167 168Obtains 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. 169 170**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 171 172**Parameters** 173 174| Name | Type | Mandatory | Description | 175| ----------- | ------ | ---- | --------------------------------------- | 176| moduleName | string | Yes | Name of the module with the overlay feature. | 177| 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. | 178 179**Error codes** 180 181For details about the error codes, see [Bundle Error Codes](errorcode-bundle.md). 182 183| ID| Error Message | 184| ------ | -------------------------------------- | 185| 17700002 | The specified module name is not found. | 186| 17700032 | The specified bundle does not contain any overlay module. | 187| 17700033 | The specified module is not an overlay module. | 188 189**Example** 190 191```ts 192import overlay from '@ohos.bundle.overlay'; 193import { BusinessError } from '@ohos.base'; 194let moduleName = "feature"; 195try { 196 overlay.getOverlayModuleInfo(moduleName, (err, data) => { 197 if (err) { 198 console.log('getOverlayModuleInfo failed due to err code : ' + err.code + ' ' + 'message :' + err.message); 199 return; 200 } 201 console.log('overlayModuleInfo is ' + JSON.stringify(data)); 202 }); 203} catch (err) { 204 let code = (err as BusinessError).code; 205 let message = (err as BusinessError).message; 206 console.log('getOverlayModuleInfo failed due to err code : ' + code + ' ' + 'message :' + message); 207} 208``` 209 210## overlay.getTargetOverlayModuleInfos 211 212getTargetOverlayModuleInfos(targetModuleName: string): Promise\<Array\<OverlayModuleInfo>> 213 214Obtains 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. 215 216**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 217 218**Parameters** 219 220| Name | Type | Mandatory | Description | 221| ----------- | ------ | ---- | --------------------------------------- | 222| targetModuleName | string | Yes | Name of the target module specified by modules with the overlay feature. | 223 224**Return value** 225 226| Type | Description | 227| ------------------------------------------------------------ | ------------------------------------------------------------ | 228| 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.| 229 230**Error codes** 231 232For details about the error codes, see [Bundle Error Codes](errorcode-bundle.md). 233 234| ID| Error Message | 235| ------ | -------------------------------------- | 236| 17700002 | The specified module name is not found. | 237| 17700034 | The specified module is an overlay module. | 238 239**Example** 240 241```ts 242import overlay from '@ohos.bundle.overlay'; 243import { BusinessError } from '@ohos.base'; 244let targetModuleName = "feature"; 245 246(async() => { 247 try { 248 let overlayModuleInfos = await overlay.getTargetOverlayModuleInfos(targetModuleName); 249 console.log('overlayModuleInfos are ' + JSON.stringify(overlayModuleInfos)); 250 } catch(err) { 251 let code = (err as BusinessError).code; 252 let message = (err as BusinessError).message; 253 console.log('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message); 254 } 255})(); 256``` 257 258## overlay.getTargetOverlayModuleInfos 259 260getTargetOverlayModuleInfos(targetModuleName: string, callback: AsyncCallback\<Array\<OverlayModuleInfo>>): void 261 262Obtains 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. 263 264**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 265 266**Parameters** 267 268| Name | Type | Mandatory | Description | 269| ----------- | ------ | ---- | --------------------------------------- | 270| targetModuleName | string | Yes | Name of the target module specified by modules with the overlay feature. | 271| 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. | 272 273**Error codes** 274 275For details about the error codes, see [Bundle Error Codes](errorcode-bundle.md). 276 277| ID| Error Message | 278| ------ | -------------------------------------- | 279| 17700002 | The specified module name is not found. | 280| 17700034 | The specified module is an overlay module. | 281 282**Example** 283 284```ts 285import overlay from '@ohos.bundle.overlay'; 286import { BusinessError } from '@ohos.base'; 287let targetModuleName = "feature"; 288try { 289 overlay.getTargetOverlayModuleInfos(targetModuleName, (err, data) => { 290 if (err) { 291 console.log('getTargetOverlayModuleInfos failed due to err code : ' + err.code + ' ' + 'message :' + err.message); 292 return; 293 } 294 console.log('overlayModuleInfo is ' + JSON.stringify(data)); 295 }); 296} catch (err) { 297 let code = (err as BusinessError).code; 298 let message = (err as BusinessError).message; 299 console.log('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message); 300} 301``` 302 303## Module with the Overlay Feature 304 305**Concept** 306 307A 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. 308 309**How do I identify a module with the overlay feature?** 310 311If 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. 312 313