1# @ohos.bundle.overlay (overlay模块) 2 3本模块提供[overlay特征应用](#overlay特征应用介绍)的安装，overlay特征应用的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息的查询以及overlay特征应用的禁用使能的能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11``` ts 12import overlay from '@ohos.bundle.overlay'; 13``` 14 15## overlay.setOverlayEnabled 16 17setOverlayEnabled(moduleName:string, isEnabled: boolean): Promise\<void> 18 19以异步方法设置当前应用中overlay特征module的禁用使能状态。使用Promise异步回调。成功返回null，失败返回对应错误信息。 20 21**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 22 23**参数：** 24 25| 参数名 | 类型 | 必填 | 说明 | 26| ----------- | ------ | ---- | --------------------------------------- | 27| moduleName | string | 是 | overlay特征module的名称。 | 28| isEnabled | boolean | 是 | 值为true表示使能，值为false表示禁用。 | 29 30**返回值：** 31 32| 类型 | 说明 | 33| ------------------------- | ------------------ | 34| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 35 36**错误码：** 37 38以下错误码的详细介绍请参见[ohos.bundle错误码](errorcode-bundle.md)。 39 40| 错误码ID | 错误信息 | 41| ------ | -------------------------------------- | 42| 17700002 | The specified module name is not found. | 43| 17700033 | The specified module is not an overlay module. | 44 45**示例：** 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 71以异步方法设置当前应用中overlay module的禁用使能状态。使用callback异步回调。成功返回null，失败返回对应错误信息。 72 73**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 74 75**参数：** 76 77| 参数名 | 类型 | 必填 | 说明 | 78| ----------- | ------ | ---- | --------------------------------------- | 79| moduleName | string | 是 | overlay特征module的名称。 | 80| isEnabled | boolean | 是 | 值为true表示使能，值为false表示禁用。| 81| callback | AsyncCallback\<void> | 是 | 回调函数，当设置指定module的overlay禁用使能状态成功时，err为null，否则为错误对象。 | 82 83**错误码：** 84 85以下错误码的详细介绍请参见[ohos.bundle错误码](errorcode-bundle.md)。 86 87| 错误码ID | 错误信息 | 88| ------ | -------------------------------------- | 89| 17700002 | The specified module name is not found. | 90| 17700033 | The specified module is not an overlay module. | 91 92**示例：** 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 119以异步方法获取当前应用中指定的module的overlayModuleInfo信息。使用promise异步回调，成功返回null，失败返回对应错误信息。 120 121**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 122 123**参数：** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ----------- | ------ | ---- | ------------------------------------------ | 127| moduleName | string | 是 | 指定当前应用中的overlay module的名称。 | 128 129**返回值：** 130 131| 类型 | 说明 | 132| ------------------------- | ------------------ | 133| Promise\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | Promise对象，返回[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)。| 134 135**错误码：** 136 137以下错误码的详细介绍请参见[ohos.bundle错误码](errorcode-bundle.md)。 138 139| 错误码ID | 错误信息 | 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**示例：** 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 168以异步方法获取当前应用中指定的module的overlayModuleInfo信息。使用callback异步回调，成功返回null，失败返回对应错误信息。 169 170**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| ----------- | ------ | ---- | --------------------------------------- | 176| moduleName | string | 是 | 指定当前应用中的overlay特征module的名称。 | 177| callback | AsyncCallback\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)> | 是 | 回调函数，当获取当前应用中指定的module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)信息成功时，err返回null。否则回调函数返回具体错误对象。 | 178 179**错误码：** 180 181以下错误码的详细介绍请参见[ohos.bundle错误码](errorcode-bundle.md)。 182 183| 错误码ID | 错误信息 | 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**示例：** 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 214以异步方法获取指定的目标module的OverlayModuleInfo。使用promise异步回调，成功返回null，失败返回对应错误信息。 215 216**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 217 218**参数：** 219 220| 参数名 | 类型 | 必填 | 说明 | 221| ----------- | ------ | ---- | --------------------------------------- | 222| targetModuleName | string | 是 | 指定当前应用中的目标module的名称。 | 223 224**返回值：** 225 226| 类型 | 说明 | 227| ------------------------------------------------------------ | ------------------------------------------------------------ | 228| Promise\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | Promise对象，返回\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>>。 | 229 230**错误码：** 231 232以下错误码的详细介绍请参见[ohos.bundle错误码](errorcode-bundle.md)。 233 234| 错误码ID | 错误信息 | 235| ------ | -------------------------------------- | 236| 17700002 | The specified module name is not found. | 237| 17700034 | The specified module is an overlay module. | 238 239**示例：** 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 262以异步方法获取指定的目标module的OverlayModuleInfo。使用callback异步回调，成功返回null，失败返回对应错误信息。 263 264**系统能力：** SystemCapability.BundleManager.BundleFramework.Overlay 265 266**参数：** 267 268| 参数名 | 类型 | 必填 | 说明 | 269| ----------- | ------ | ---- | --------------------------------------- | 270| targetModuleName | string | 是 | 指定当前应用中的目标module的名称。 | 271| callback | AsyncCallback\<Array\<[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)>> | 是 | 回调函数，当获取指定的目标module的[OverlayModuleInfo](js-apis-bundleManager-overlayModuleInfo.md)成功时，err返回null。否则回调函数返回具体错误对象。 | 272 273**错误码：** 274 275以下错误码的详细介绍请参见[ohos.bundle错误码](errorcode-bundle.md)。 276 277| 错误码ID | 错误信息 | 278| ------ | -------------------------------------- | 279| 17700002 | The specified module name is not found. | 280| 17700034 | The specified module is an overlay module. | 281 282**示例：** 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## overlay特征应用介绍 304 305**概念** 306overlay特征应用指的是应用中包含有overlay特征的module。该特征module一般是为设备上存在的非overlay特征的module提供额外的资源文件，以便于目标module在运行阶段可以使用这些额外的资源文件来展示不同的颜色，标签，主题等等。overlay特征仅适用于stage模型。 307 308**如何识别overlay特征的module** 309在IDE中创建应用工程时, module的配置文件module.json5中包含targetModuleName和targetPriority字段时，该module将会在安装阶段被识别为overlay特征的module。 310