1# @ohos.bundle.overlay (overlay) (System API) 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](js-apis-overlay.md), querying the [module information](js-apis-bundleManager-overlayModuleInfo.md), and disabling and enabling the module. 10 11> **NOTE** 12> 13> 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. 14> 15> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.bundle.overlay](js-apis-overlay.md). 16 17## Modules to Import 18 19``` ts 20import { overlay } from '@kit.AbilityKit'; 21``` 22 23## overlay.setOverlayEnabledByBundleName 24 25setOverlayEnabledByBundleName(bundleName: string, moduleName: string, isEnabled: boolean): Promise\<void> 26 27Enables or disables a module with the overlay feature in another application. This API uses a promise to return the result. 28 29No permission is required when the specified application is the caller itself. 30 31**Required permissions**: ohos.permission.CHANGE_OVERLAY_ENABLED_STATE 32 33**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 34 35**System API**: This is a system API. 36 37**Parameters** 38 39| Name | Type | Mandatory | Description | 40| ----------- | ------ | ---- | --------------------------------------- | 41| bundleName | string | Yes | Bundle name of the application. | 42| moduleName | string | Yes | Name of the module with the overlay feature. | 43| isEnabled | boolean | Yes | Whether to enable the module with the overlay feature. **true** to enable, **false** otherwise.| 44 45**Return value** 46 47| Type | Description | 48| ------------------------- | ------------------ | 49| Promise\<void> | Promise that returns no value.| 50 51**Error codes** 52 53For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 54 55| ID| Error Message | 56| ------ | -------------------------------------- | 57| 201 | Permission denied. | 58| 202 | Permission denied, non-system app called system api. | 59| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 60| 17700001 | The specified bundleName is not found. | 61| 17700002 | The specified module name is not found. | 62| 17700032 | The specified bundle does not contain any overlay module. | 63| 17700033 | The specified module is not an overlay module. | 64 65**Example** 66 67```ts 68import { overlay } from '@kit.AbilityKit'; 69import { BusinessError } from '@kit.BasicServicesKit'; 70let bundleName = "com.example.myapplication_xxxxx"; 71let moduleName = "feature"; 72let isEnabled = false; 73 74try { 75 overlay.setOverlayEnabledByBundleName(bundleName, moduleName, isEnabled) 76 .then((data) => { 77 console.info('setOverlayEnabledByBundleName successfully'); 78 }).catch((err: BusinessError) => { 79 console.error('setOverlayEnabledByBundleName failed due to err code: ' + err.code + ' ' + 'message:' + err.message); 80 }); 81} catch (err) { 82 let code = (err as BusinessError).code; 83 let message = (err as BusinessError).message; 84 console.error('setOverlayEnabledByBundleName failed due to err code: ' + code + ' ' + 'message:' + message); 85} 86``` 87 88## overlay.setOverlayEnabledByBundleName 89 90setOverlayEnabledByBundleName(bundleName: string, moduleName: string, isEnabled: boolean, callback: AsyncCallback\<void>): void 91 92Enables or disables a module with the overlay feature in another application. This API uses an asynchronous callback to return the result. 93 94No permission is required when the specified application is the caller itself. 95 96**Required permissions**: ohos.permission.CHANGE_OVERLAY_ENABLED_STATE 97 98**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 99 100**System API**: This is a system API. 101 102**Parameters** 103 104| Name | Type | Mandatory | Description | 105| ----------- | ------ | ---- | --------------------------------------- | 106| bundleName | string | Yes | Bundle name of the application. | 107| moduleName | string | Yes | Name of the module with the overlay feature. | 108| isEnabled | boolean | Yes | Whether to enable the module with the overlay feature. **true** to enable, **false** otherwise.| 109| 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. | 110 111**Error codes** 112 113For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 114 115| ID| Error Message | 116| ------ | -------------------------------------- | 117| 201 | Permission denied. | 118| 202 | Permission denied, non-system app called system api. | 119| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 120| 17700001 | The specified bundleName is not found. | 121| 17700002 | The specified module name is not found. | 122| 17700032 | The specified bundle does not contain any overlay module. | 123| 17700033 | The specified module is not an overlay module. | 124 125**Example** 126 127```ts 128import { overlay } from '@kit.AbilityKit'; 129import { BusinessError } from '@kit.BasicServicesKit'; 130let bundleName = "com.example.myapplication_xxxxx"; 131let moduleName = "feature"; 132let isEnabled = false; 133 134try { 135 overlay.setOverlayEnabledByBundleName(bundleName, moduleName, isEnabled, (err, data) => { 136 if (err) { 137 console.error('setOverlayEnabledByBundleName failed due to err code: ' + err.code + ' ' + 'message:' + err.message); 138 return; 139 } 140 console.info('setOverlayEnabledByBundleName successfully'); 141 }); 142} catch (err) { 143 let code = (err as BusinessError).code; 144 let message = (err as BusinessError).message; 145 console.error('setOverlayEnabledByBundleName failed due to err code: ' + code + ' ' + 'message:' + message); 146} 147``` 148 149## overlay.getOverlayModuleInfoByBundleName 150 151getOverlayModuleInfoByBundleName(bundleName: string, moduleName?: string): Promise\<Array\<OverlayModuleInfo>> 152 153Obtains the information about a module with the overlay feature in another application. This API uses a promise to return the result. 154 155No permission is required when the specified application is the caller itself. 156 157**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 158 159**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 160 161**System API**: This is a system API. 162 163**Parameters** 164 165| Name | Type | Mandatory | Description | 166| ----------- | ------ | ---- | --------------------------------------- | 167| bundleName | string | Yes | Bundle name of the application. | 168| moduleName | string | No | Name of the module with the overlay feature. By default, no value is passed, and the API obtains the information of all modules with the overlay feature in that application. | 169 170**Return value** 171 172| Type | Description | 173| ------------------------------------------------------------ | ------------------------------------------------------------ | 174| 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.| 175 176**Error codes** 177 178For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 179 180| ID| Error Message | 181| ------ | -------------------------------------- | 182| 201 | Permission denied. | 183| 202 | Permission denied, non-system app called system api. | 184| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 185| 17700001 | The specified bundleName is not found. | 186| 17700002 | The specified module name is not found. | 187| 17700032 | The specified bundle does not contain any overlay module. | 188| 17700033 | The specified module is not an overlay module. | 189 190**Example** 191 192```ts 193import { overlay } from '@kit.AbilityKit'; 194import { BusinessError } from '@kit.BasicServicesKit'; 195let bundleName = "com.example.myapplication_xxxxx"; 196let moduleName = "feature"; 197 198(async() => { 199 try { 200 let overlayModuleInfos = await overlay.getOverlayModuleInfoByBundleName(bundleName, moduleName); 201 console.info('overlayModuleInfos are ' + JSON.stringify(overlayModuleInfos)); 202 } catch(err) { 203 let code = (err as BusinessError).code; 204 let message = (err as BusinessError).message; 205 console.error('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message); 206 } 207})(); 208``` 209 210## overlay.getOverlayModuleInfoByBundleName 211 212getOverlayModuleInfoByBundleName(bundleName: string, moduleName: string, callback: AsyncCallback\<Array\<OverlayModuleInfo>>): void 213 214Obtains the information about a module with the overlay feature in another application. This API uses an asynchronous callback to return the result. 215 216No permission is required when the specified application is the caller itself. 217 218**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 219 220**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 221 222**System API**: This is a system API. 223 224**Parameters** 225 226| Name | Type | Mandatory | Description | 227| ----------- | ------ | ---- | --------------------------------------- | 228| bundleName | string | Yes | Bundle name of the application. | 229| moduleName | string | Yes | Name of the module with the overlay feature. If this parameter is not specified, the API obtains the information of all modules with the overlay feature in that application. | 230| 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 array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. If the operation is successful, **err** is **null**; otherwise, **err** is an error object. | 231 232**Error codes** 233 234For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 235 236| ID| Error Message | 237| ------ | -------------------------------------- | 238| 201 | Permission denied. | 239| 202 | Permission denied, non-system app called system api. | 240| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 241| 17700001 | The specified bundleName is not found. | 242| 17700002 | The specified module name is not found. | 243| 17700032 | The specified bundle does not contain any overlay module. | 244| 17700033 | The specified module is not an overlay module. | 245 246**Example** 247 248```ts 249import { overlay } from '@kit.AbilityKit'; 250import { BusinessError } from '@kit.BasicServicesKit'; 251let bundleName = "com.example.myapplication_xxxxx"; 252let moduleName = "feature"; 253 254try { 255 overlay.getOverlayModuleInfoByBundleName(bundleName, moduleName, (err, data) => { 256 if (err) { 257 console.error('getOverlayModuleInfoByBundleName failed due to err code : ' + err.code + ' ' + 'message :' + err.message); 258 return; 259 } 260 console.info('overlayModuleInfo is ' + JSON.stringify(data)); 261 }); 262} catch (err) { 263 let code = (err as BusinessError).code; 264 let message = (err as BusinessError).message; 265 console.error('getOverlayModuleInfoByBundleName failed due to err code : ' + code + ' ' + 'message :' + message); 266} 267``` 268 269## overlay.getOverlayModuleInfoByBundleName 270 271getOverlayModuleInfoByBundleName(bundleName: string, callback: AsyncCallback\<Array\<OverlayModuleInfo>>): void 272 273Obtains the information about all modules with the overlay feature in another application. This API uses an asynchronous callback to return the result. 274 275No permission is required when the specified application is the caller itself. 276 277**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 278 279**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 280 281**System API**: This is a system API. 282 283**Parameters** 284 285| Name | Type | Mandatory | Description | 286| ----------- | ------ | ---- | --------------------------------------- | 287| bundleName | string | Yes | Bundle name of the application. | 288| 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 array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. If the operation is successful, **err** is **null**; otherwise, **err** is an error object. | 289 290**Error codes** 291 292For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 293 294| ID| Error Message | 295| ------ | -------------------------------------- | 296| 201 | Permission denied. | 297| 202 | Permission denied, non-system app called system api. | 298| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 299| 17700001 | The specified bundleName is not found. | 300| 17700032 | The specified bundle does not contain any overlay module. | 301 302**Example** 303 304```ts 305import { overlay } from '@kit.AbilityKit'; 306import { BusinessError } from '@kit.BasicServicesKit'; 307let bundleName = "com.example.myapplication_xxxxx"; 308 309try { 310 overlay.getOverlayModuleInfoByBundleName(bundleName, (err, data) => { 311 if (err) { 312 console.error('getOverlayModuleInfoByBundleName failed due to err code : ' + err.code + ' ' + 'message :' + err.message); 313 return; 314 } 315 console.info('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.error('getOverlayModuleInfoByBundleName failed due to err code : ' + code + ' ' + 'message :' + message); 321} 322``` 323 324## overlay.getTargetOverlayModuleInfosByBundleName 325 326getTargetOverlayModuleInfosByBundleName(targetBundleName: string, moduleName?: string): Promise\<Array\<OverlayModuleInfo>> 327 328Obtains the information about modules with the overlay feature in another application based on the target module name. This API uses a promise to return the result. 329 330No permission is required when the specified application is the caller itself. 331 332**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 333 334**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 335 336**System API**: This is a system API. 337 338**Parameters** 339 340| Name | Type | Mandatory | Description | 341| ----------- | ------ | ---- | --------------------------------------- | 342| targetBundleName | string | Yes | Bundle name of the application. | 343| moduleName | string | No | Name of the target module. By default, no value is passed, and the API obtains the information associated with all modules in that application. | 344 345**Return value** 346 347| Type | Description | 348| ------------------------- | ------------------ | 349| 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.| 350 351**Error codes** 352 353For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 354 355| ID| Error Message | 356| ------ | -------------------------------------- | 357| 201 | Permission denied. | 358| 202 | Permission denied, non-system app called system api. | 359| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 360| 17700001 | The specified bundleName is not found. | 361| 17700002 | The specified module name is not found. | 362| 17700034 | The specified module is an overlay module. | 363| 17700035 | The specified bundle is an overlay bundle. | 364 365**Example** 366 367```ts 368import { overlay } from '@kit.AbilityKit'; 369import { BusinessError } from '@kit.BasicServicesKit'; 370let targetBundleName = "com.example.myapplication_xxxxx"; 371let moduleName = "feature"; 372 373(async() => { 374 try { 375 let overlayModuleInfos = await overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, moduleName); 376 console.info('overlayModuleInfos are ' + JSON.stringify(overlayModuleInfos)); 377 } catch(err) { 378 let code = (err as BusinessError).code; 379 let message = (err as BusinessError).message; 380 console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + code + ' ' + 'message :' + message); 381 } 382})(); 383``` 384 385## overlay.getTargetOverlayModuleInfosByBundleName 386 387getTargetOverlayModuleInfosByBundleName(targetBundleName: string, moduleName: string, callback: AsyncCallback<Array<OverlayModuleInfo>>): void 388 389Obtains the information about modules with the overlay feature in another application based on the target module name. This API uses an asynchronous callback to return the result. 390 391No permission is required when the specified application is the caller itself. 392 393**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 394 395**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 396 397**System API**: This is a system API. 398 399**Parameters** 400 401| Name | Type | Mandatory | Description | 402| ----------- | ------ | ---- | --------------------------------------- | 403| targetBundleName | string | Yes | Bundle name of the application. | 404| moduleName | string | Yes | Name of the target module. If this parameter is not specified, the API obtains the information associated with all modules in that application. | 405| 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 array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. If the operation is successful, **err** is **null**; otherwise, **err** is an error object. | 406 407**Error codes** 408 409For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 410 411| ID| Error Message | 412| ------ | -------------------------------------- | 413| 201 | Permission denied. | 414| 202 | Permission denied, non-system app called system api. | 415| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 416| 17700001 | The specified bundleName is not found. | 417| 17700002 | The specified module name is not found. | 418| 17700034 | The specified module is an overlay module. | 419| 17700035 | The specified bundle is an overlay bundle. | 420 421**Example** 422 423```ts 424import { overlay } from '@kit.AbilityKit'; 425import { BusinessError } from '@kit.BasicServicesKit'; 426let targetBundleName = "com.example.myapplication_xxxxx"; 427let moduleName = "feature"; 428 429try { 430 overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, moduleName, (err, data) => { 431 if (err) { 432 console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + err.code + ' ' + 'message :' + err.message); 433 return; 434 } 435 console.info('overlayModuleInfo is ' + JSON.stringify(data)); 436 }); 437} catch (err) { 438 let code = (err as BusinessError).code; 439 let message = (err as BusinessError).message; 440 console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + code + ' ' + 'message :' + message); 441} 442``` 443 444## overlay.getTargetOverlayModuleInfosByBundleName 445 446getTargetOverlayModuleInfosByBundleName(targetBundleName: string, callback: AsyncCallback<Array<OverlayModuleInfo>>): void 447 448Obtains the information about all modules with the overlay feature in another application. This API uses an asynchronous callback to return the result. 449 450No permission is required when the specified application is the caller itself. 451 452**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 453 454**System capability**: SystemCapability.BundleManager.BundleFramework.Overlay 455 456**System API**: This is a system API. 457 458**Parameters** 459 460| Name | Type | Mandatory | Description | 461| ----------- | ------ | ---- | --------------------------------------- | 462| targetBundleName | string | Yes | Bundle name of the application. | 463| 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 array of [OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md) objects. If the operation is successful, **err** is **null**; otherwise, **err** is an error object. | 464 465**Error codes** 466 467For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bundle Error Codes](errorcode-bundle.md). 468 469| ID| Error Message | 470| ------ | -------------------------------------- | 471| 201 | Permission denied. | 472| 202 | Permission denied, non-system app called system api. | 473| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.| 474| 17700001 | The specified bundleName is not found. | 475| 17700035 | The specified bundle is an overlay bundle. | 476 477**Example** 478 479```ts 480import { overlay } from '@kit.AbilityKit'; 481import { BusinessError } from '@kit.BasicServicesKit'; 482let targetBundleName = "com.example.myapplication_xxxxx"; 483 484try { 485 overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, (err, data) => { 486 if (err) { 487 console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + err.code + ' ' + 'message :' + err.message); 488 return; 489 } 490 console.info('overlayModuleInfo is ' + JSON.stringify(data)); 491 }); 492} catch (err) { 493 let code = (err as BusinessError).code; 494 let message = (err as BusinessError).message; 495 console.error('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + code + ' ' + 'message :' + message); 496} 497``` 498