@ohos.bundle.overlay (overlay模块)

本模块提供overlay特征应用的安装，overlay特征应用的OverlayModuleInfo信息的查询以及overlay特征应用的禁用使能的能力。

overlay特征应用指应用中包含有overlay特征的module。该特征module一般是为设备上存在的非overlay特征的module提供额外的资源文件，以便目标module在运行阶段可以使用这些额外的资源文件来展示不同的颜色、标签、主题等。

在DevEco Studio中创建应用工程时，若module的配置文件module.json5中包含targetModuleName和targetPriority字段，该module将会在安装阶段被识别为overlay特征的module。

说明：

本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

overlay特征仅适用于stage模型。

导入模块

import { overlay } from '@kit.AbilityKit';

overlay.setOverlayEnabled

setOverlayEnabled(moduleName:string, isEnabled: boolean): Promise<void>

设置当前应用中overlay特征module的禁用使能状态。使用Promise异步回调。成功返回null，失败返回对应错误信息。

系统能力： SystemCapability.BundleManager.BundleFramework.Overlay

参数：

参数名	类型	必填	说明
moduleName	string	是	overlay特征module的名称。
isEnabled	boolean	是	值为true表示使能，值为false表示禁用。

返回值：

类型	说明
Promise<void>	Promise对象。无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见通用错误码和ohos.bundle错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700002	The specified module name is not found.
17700033	The specified module is not an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let moduleName = "feature";
let isEnabled = false;

try {
  overlay.setOverlayEnabled(moduleName, isEnabled)
    .then(() => {
      console.info('setOverlayEnabled success');
    }).catch((err: BusinessError) => {
      console.error('setOverlayEnabled failed due to err code: ' + err.code + ' ' + 'message:' + err.message);
    });
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error('setOverlayEnabled failed due to err code: ' + code + ' ' + 'message:' + message);
}

overlay.setOverlayEnabled

setOverlayEnabled(moduleName: string, isEnabled: boolean, callback: AsyncCallback<void>): void

设置当前应用中overlay module的禁用使能状态。使用callback异步回调。成功返回null，失败返回对应错误信息。

系统能力： SystemCapability.BundleManager.BundleFramework.Overlay

参数：

参数名	类型	必填	说明
moduleName	string	是	overlay特征module的名称。
isEnabled	boolean	是	值为true表示使能，值为false表示禁用。
callback	AsyncCallback<void>	是	回调函数，当设置指定module的overlay禁用使能状态成功时，err为null，否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和ohos.bundle错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700002	The specified module name is not found.
17700033	The specified module is not an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let moduleName = "feature";
let isEnabled = false;

try {
  overlay.setOverlayEnabled(moduleName, isEnabled, (err, data) => {
    if (err) {
      console.error('setOverlayEnabled failed due to err code: ' + err.code + ' ' + 'message:' + err.message);
      return;
    }
    console.info('setOverlayEnabled success');
  });
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error('setOverlayEnabled failed due to err code: ' + code + ' ' + 'message:' + message);
}

overlay.getOverlayModuleInfo

getOverlayModuleInfo(moduleName: string): Promise<OverlayModuleInfo>

获取当前应用中指定的module的overlayModuleInfo信息。使用promise异步回调，成功返回null，失败返回对应错误信息。

系统能力： SystemCapability.BundleManager.BundleFramework.Overlay

参数：

参数名	类型	必填	说明
moduleName	string	是	指定当前应用中的overlay module的名称。

返回值：

类型	说明
Promise<OverlayModuleInfo>	Promise对象，返回OverlayModuleInfo。

错误码：

以下错误码的详细介绍请参见通用错误码和ohos.bundle错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700002	The specified module name is not found.
17700032	The specified bundle does not contain any overlay module.
17700033	The specified module is not an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let moduleName = "feature";

(async () => {
  try {
    let overlayModuleInfo = await overlay.getOverlayModuleInfo(moduleName);
    console.log('overlayModuleInfo is ' + JSON.stringify(overlayModuleInfo));
  } catch (err) {
    let code = (err as BusinessError).code;
    let message = (err as BusinessError).message;
    console.error('getOverlayModuleInfo failed due to err code : ' + code + ' ' + 'message :' + message);
  }
})();

overlay.getOverlayModuleInfo

getOverlayModuleInfo(moduleName: string, callback: AsyncCallback<OverlayModuleInfo>): void

获取当前应用中指定的module的overlayModuleInfo信息。使用callback异步回调，成功返回null，失败返回对应错误信息。

系统能力： SystemCapability.BundleManager.BundleFramework.Overlay

参数：

参数名	类型	必填	说明
moduleName	string	是	指定当前应用中的overlay特征module的名称。
callback	AsyncCallback<OverlayModuleInfo>	是	回调函数，当获取当前应用中指定的module的OverlayModuleInfo信息成功时，err返回null。否则回调函数返回具体错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和ohos.bundle错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700002	The specified module name is not found.
17700032	The specified bundle does not contain any overlay module.
17700033	The specified module is not an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let moduleName = "feature";

try {
  overlay.getOverlayModuleInfo(moduleName, (err, data) => {
    if (err) {
      console.error('getOverlayModuleInfo failed due to err code : ' + err.code + ' ' + 'message :' + err.message);
      return;
    }
    console.log('overlayModuleInfo is ' + JSON.stringify(data));
  });
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error('getOverlayModuleInfo failed due to err code : ' + code + ' ' + 'message :' + message);
}

overlay.getTargetOverlayModuleInfos

getTargetOverlayModuleInfos(targetModuleName: string): Promise<Array<OverlayModuleInfo>>

获取指定的目标module的OverlayModuleInfo。使用promise异步回调，成功返回null，失败返回对应错误信息。

系统能力： SystemCapability.BundleManager.BundleFramework.Overlay

参数：

参数名	类型	必填	说明
targetModuleName	string	是	指定当前应用中的目标module的名称。

返回值：

类型	说明
Promise<Array<OverlayModuleInfo>>	Promise对象，返回<Array<OverlayModuleInfo>>。

错误码：

以下错误码的详细介绍请参见通用错误码和ohos.bundle错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700002	The specified module name is not found.
17700034	The specified module is an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let targetModuleName = "feature";

(async () => {
  try {
    let overlayModuleInfos = await overlay.getTargetOverlayModuleInfos(targetModuleName);
    console.log('overlayModuleInfos are ' + JSON.stringify(overlayModuleInfos));
  } catch (err) {
    let code = (err as BusinessError).code;
    let message = (err as BusinessError).message;
    console.error('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message);
  }
})();

overlay.getTargetOverlayModuleInfos

getTargetOverlayModuleInfos(targetModuleName: string, callback: AsyncCallback<Array<OverlayModuleInfo>>): void

获取指定的目标module的OverlayModuleInfo。使用callback异步回调，成功返回null，失败返回对应错误信息。

系统能力： SystemCapability.BundleManager.BundleFramework.Overlay

参数：

参数名	类型	必填	说明
targetModuleName	string	是	指定当前应用中的目标module的名称。
callback	AsyncCallback<Array<OverlayModuleInfo>>	是	回调函数，当获取指定的目标module的OverlayModuleInfo成功时，err返回null。否则回调函数返回具体错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码和ohos.bundle错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700002	The specified module name is not found.
17700034	The specified module is an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let targetModuleName = "feature";

try {
  overlay.getTargetOverlayModuleInfos(targetModuleName, (err, data) => {
    if (err) {
      console.error('getTargetOverlayModuleInfos failed due to err code : ' + err.code + ' ' + 'message :' + err.message);
      return;
    }
    console.log('overlayModuleInfo is ' + JSON.stringify(data));
  });
} catch (err) {
  let code = (err as BusinessError).code;
  let message = (err as BusinessError).message;
  console.error('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message);
}

OverlayModuleInfo

type OverlayModuleInfo = _OverlayModuleInfo.OverlayModuleInfo

OverlayModuleInfo信息。

系统能力： SystemCapability.BundleManager.BundleFramework.Overlay

类型	说明
_OverlayModuleInfo.OverlayModuleInfo	OverlayModuleInfo信息。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit（程序框架服务）

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_base_common.h

harmony 鸿蒙ability_runtime_common.h

harmony 鸿蒙application_context.h