鸿蒙5.0开发进阶：@ohos.bundle.overlay (overlay模块)

最新推荐文章于 2025-05-10 19:27:43 发布

原创最新推荐文章于 2025-05-10 19:27:43 发布 · 987 阅读

17 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #华为 #android #前端 #鸿蒙系统 #ArkUI #ArkTS

鸿蒙开发同时被 3 个专栏收录

1065 篇文章

订阅专栏

ArkUI

762 篇文章

订阅专栏

ArkTS

556 篇文章

订阅专栏

往期鸿蒙全套实战文章必看：（文中附带全栈鸿蒙学习资料）

@ohos.bundle.overlay (overlay模块)

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

说明

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

导入模块

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对象。

错误码：

以下错误码的详细介绍。

错误码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.info('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.info('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，否则为错误对象。

错误码：

以下错误码的详细介绍。

错误码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.info('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.info('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。

错误码：

以下错误码的详细介绍。

错误码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.log('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。否则回调函数返回具体错误对象。

错误码：

以下错误码的详细介绍。

错误码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.log('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.log('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>>。

错误码：

以下错误码的详细介绍。

错误码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.log('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。否则回调函数返回具体错误对象。

错误码：

以下错误码的详细介绍。

错误码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.log('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.log('getTargetOverlayModuleInfos failed due to err code : ' + code + ' ' + 'message :' + message);
}