1# @ohos.bundle.overlay (overlay模块) 2 3本模块提供overlay特征应用的安装，overlay特征应用的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息的查询以及overlay特征应用的禁用使能的能力。 4 5overlay特征应用指应用中包含有[overlay特征](../../quick-start/resource-categories-and-access.md#overlay机制)的module。该特征module一般是为设备上存在的非overlay特征的module提供额外的资源文件，以便目标module在运行阶段可以使用这些额外的资源文件来展示不同的颜色、标签、主题等。 6 7在DevEco Studio中创建应用工程时，若module的配置文件module.json5中包含targetModuleName和targetPriority字段，该module将会在安装阶段被识别为overlay特征的module。 8 9> **说明：** 10> 11> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> 13> overlay特征仅适用于stage模型。 14 15 16## 导入模块 17 18``` ts 19import { overlay } from '@kit.AbilityKit'; 20``` 21 22## overlay.setOverlayEnabled 23 24setOverlayEnabled(moduleName:string, isEnabled: boolean): Promise\<void> 25 26设置当前应用中overlay特征module的禁用使能状态。使用Promise异步回调。成功返回null，失败返回对应错误信息。 27 28**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 29 30**参数：** 31 32| 参数名 | 类型 | 必填 | 说明 | 33| ----------- | ------ | ---- | --------------------------------------- | 34| moduleName | string | 是 | overlay特征module的名称。 | 35| isEnabled | boolean | 是 | 值为true表示使能，值为false表示禁用。 | 36 37**返回值：** 38 39| 类型 | 说明 | 40| ------------------------- | ------------------ | 41| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 42 43**错误码：** 44 45以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 46 47| 错误码ID | 错误信息 | 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**示例：** 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 80设置当前应用中overlay module的禁用使能状态。使用callback异步回调。成功返回null，失败返回对应错误信息。 81 82**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 说明 | 87| ----------- | ------ | ---- | --------------------------------------- | 88| moduleName | string | 是 | overlay特征module的名称。 | 89| isEnabled | boolean | 是 | 值为true表示使能，值为false表示禁用。| 90| callback | AsyncCallback\<void> | 是 | 回调函数，当设置指定module的overlay禁用使能状态成功时，err为null，否则为错误对象。 | 91 92**错误码：** 93 94以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 95 96| 错误码ID | 错误信息 | 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**示例：** 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 130获取当前应用中指定的module的overlayModuleInfo信息。使用promise异步回调，成功返回null，失败返回对应错误信息。 131 132**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| ----------- | ------ | ---- | ------------------------------------------ | 138| moduleName | string | 是 | 指定当前应用中的overlay module的名称。 | 139 140**返回值：** 141 142| 类型 | 说明 | 143| ------------------------- | ------------------ | 144| Promise\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | Promise对象，返回[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)。| 145 146**错误码：** 147 148以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 149 150| 错误码ID | 错误信息 | 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**示例：** 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 181获取当前应用中指定的module的overlayModuleInfo信息。使用callback异步回调，成功返回null，失败返回对应错误信息。 182 183**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ----------- | ------ | ---- | --------------------------------------- | 189| moduleName | string | 是 | 指定当前应用中的overlay特征module的名称。 | 190| callback | AsyncCallback\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | 是 | 回调函数，当获取当前应用中指定的module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息成功时，err返回null。否则回调函数返回具体错误对象。 | 191 192**错误码：** 193 194以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 195 196| 错误码ID | 错误信息 | 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**示例：** 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 230获取指定的目标module的OverlayModuleInfo。使用promise异步回调，成功返回null，失败返回对应错误信息。 231 232**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 233 234**参数：** 235 236| 参数名 | 类型 | 必填 | 说明 | 237| ----------- | ------ | ---- | --------------------------------------- | 238| targetModuleName | string | 是 | 指定当前应用中的目标module的名称。 | 239 240**返回值：** 241 242| 类型 | 说明 | 243| ------------------------------------------------------------ | ------------------------------------------------------------ | 244| Promise\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Promise对象，返回\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>>。 | 245 246**错误码：** 247 248以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 249 250| 错误码ID | 错误信息 | 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**示例：** 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 280获取指定的目标module的OverlayModuleInfo。使用callback异步回调，成功返回null，失败返回对应错误信息。 281 282**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 283 284**参数：** 285 286| 参数名 | 类型 | 必填 | 说明 | 287| ----------- | ------ | ---- | --------------------------------------- | 288| targetModuleName | string | 是 | 指定当前应用中的目标module的名称。 | 289| callback | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | 是 | 回调函数，当获取指定的目标module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)成功时，err返回null。否则回调函数返回具体错误对象。 | 290 291**错误码：** 292 293以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.bundle错误码](errorcode-bundle.md)。 294 295| 错误码ID | 错误信息 | 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**示例：** 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 328OverlayModuleInfo信息。 329 330**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 331 332| 类型 | 说明 | 333| ------------------------------------------------------------ | -------------- | 334| [_OverlayModuleInfo.OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md#overlaymoduleinfo-1) |OverlayModuleInfo信息。 | 335