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 9本模块提供overlay特征应用的安装，overlay特征应用的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息的查询以及overlay特征应用的禁用使能的能力。 10 11overlay特征应用指应用中包含有[overlay特征](../../quick-start/resource-categories-and-access.md#overlay机制)的module。该特征module一般是为设备上存在的非overlay特征的module提供额外的资源文件，以便目标module在运行阶段可以使用这些额外的资源文件来展示不同的颜色、标签、主题等。 12 13在DevEco Studio中创建应用工程时，若module的配置文件module.json5中包含targetModuleName和targetPriority字段，该module将会在安装阶段被识别为overlay特征的module。 14 15> **说明：** 16> 17> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 18> 19> overlay特征仅适用于stage模型。 20 21 22## 导入模块 23 24``` ts 25import { overlay } from '@kit.AbilityKit'; 26``` 27 28## overlay.setOverlayEnabled 29 30setOverlayEnabled(moduleName:string, isEnabled: boolean): Promise\<void> 31 32设置当前应用中overlay特征module的禁用使能状态。使用Promise异步回调。 33 34**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 35 36**参数：** 37 38| 参数名 | 类型 | 必填 | 说明 | 39| ----------- | ------ | ---- | --------------------------------------- | 40| moduleName | string | 是 | overlay特征module的名称。 | 41| isEnabled | boolean | 是 | 值为true表示使能，值为false表示禁用。 | 42 43**返回值：** 44 45| 类型 | 说明 | 46| ------------------------- | ------------------ | 47| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 48 49**错误码：** 50 51以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 52 53| 错误码ID | 错误信息 | 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**示例：** 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 86设置当前应用中overlay module的禁用使能状态。使用callback异步回调。 87 88**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ----------- | ------ | ---- | --------------------------------------- | 94| moduleName | string | 是 | overlay特征module的名称。 | 95| isEnabled | boolean | 是 | 值为true表示使能，值为false表示禁用。| 96| callback | AsyncCallback\<void> | 是 | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，当设置指定module的overlay禁用使能状态成功时，err为null，否则为错误对象。 | 97 98**错误码：** 99 100以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 101 102| 错误码ID | 错误信息 | 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**示例：** 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 136获取当前应用中指定的module的overlayModuleInfo信息。使用promise异步回调。 137 138**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 139 140**参数：** 141 142| 参数名 | 类型 | 必填 | 说明 | 143| ----------- | ------ | ---- | ------------------------------------------ | 144| moduleName | string | 是 | 指定当前应用中的overlay module的名称。 | 145 146**返回值：** 147 148| 类型 | 说明 | 149| ------------------------- | ------------------ | 150| Promise\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | Promise对象，返回[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)。| 151 152**错误码：** 153 154以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 155 156| 错误码ID | 错误信息 | 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**示例：** 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 187获取当前应用中指定的module的overlayModuleInfo信息。使用callback异步回调。 188 189**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| ----------- | ------ | ---- | --------------------------------------- | 195| moduleName | string | 是 | 指定当前应用中的overlay特征module的名称。 | 196| callback | AsyncCallback\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | 是 | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，当获取当前应用中指定的module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息成功时，err返回null。否则回调函数返回具体错误对象。 | 197 198**错误码：** 199 200以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 201 202| 错误码ID | 错误信息 | 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**示例：** 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 236获取指定的目标module的OverlayModuleInfo。使用promise异步回调。 237 238**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 239 240**参数：** 241 242| 参数名 | 类型 | 必填 | 说明 | 243| ----------- | ------ | ---- | --------------------------------------- | 244| targetModuleName | string | 是 | 指定当前应用中的目标module的名称。 | 245 246**返回值：** 247 248| 类型 | 说明 | 249| ------------------------------------------------------------ | ------------------------------------------------------------ | 250| Promise\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Promise对象，返回\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>>。 | 251 252**错误码：** 253 254以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 255 256| 错误码ID | 错误信息 | 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**示例：** 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 286获取指定的目标module的OverlayModuleInfo。使用callback异步回调。 287 288**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 289 290**参数：** 291 292| 参数名 | 类型 | 必填 | 说明 | 293| ----------- | ------ | ---- | --------------------------------------- | 294| targetModuleName | string | 是 | 指定当前应用中的目标module的名称。 | 295| callback | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | 是 | [回调函数](../apis-basic-services-kit/js-apis-base.md#asynccallback)，当获取指定的目标module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)成功时，err返回null。否则回调函数返回具体错误对象。 | 296 297**错误码：** 298 299以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 300 301| 错误码ID | 错误信息 | 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**示例：** 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 334OverlayModuleInfo信息。 335 336**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 337 338| 类型 | 说明 | 339| ------------------------------------------------------------ | -------------- | 340| [_OverlayModuleInfo.OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md#overlaymoduleinfo-1) |OverlayModuleInfo信息。 | 341