openharmony 鸿蒙 js-apis-overlay-sys

2025-06-12 浏览 (1)

@ohos.bundle.overlay (overlay模块)(系统接口)

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

说明：

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

当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.bundle.overlay。

导入模块

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

overlay.setOverlayEnabledByBundleName

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

设置指定应用的overlay module的禁用使能状态。使用Promise异步回调，成功返回应用的处置状态，失败返回对应错误信息。

需要权限： ohos.permission.CHANGE_OVERLAY_ENABLED_STATE

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

系统接口： 此接口为系统接口。

参数：

参数名类型必填说明
bundleNamestring是指定应用的bundle名称。
moduleNamestring是指定应用的overlay module的名称。
isEnabledboolean是值为true表示使能，值为false表示禁用。

返回值：

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

错误码：

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

错误码ID错误信息
201Permission denied.
202Permission denied, non-system app called system api.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700001The specified bundleName is not found.
17700002The specified module name is not found.
17700032The specified bundle does not contain any overlay module.
17700033The specified module is not an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let bundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";
let isEnabled = false;

try {
    overlay.setOverlayEnabledByBundleName(bundleName, moduleName, isEnabled)
        .then((data) => {
            console.info('setOverlayEnabledByBundleName successfully');
        }).catch((err: BusinessError) => {
            console.error('setOverlayEnabledByBundleName 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('setOverlayEnabledByBundleName failed due to err code: ' + code + ' ' + 'message:' + message);
}

overlay.setOverlayEnabledByBundleName

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

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

需要权限： ohos.permission.CHANGE_OVERLAY_ENABLED_STATE

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

系统接口： 此接口为系统接口。

参数：

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

错误码：

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

错误码ID错误信息
201Permission denied.
202Permission denied, non-system app called system api.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700001The specified bundleName is not found.
17700002The specified module name is not found.
17700032The specified bundle does not contain any overlay module.
17700033The specified module is not an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let bundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";
let isEnabled = false;

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

overlay.getOverlayModuleInfoByBundleName

getOverlayModuleInfoByBundleName(bundleName: string, moduleName?: string): Promise<Array<OverlayModuleInfo>>

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

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

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

系统接口： 此接口为系统接口。

参数：

参数名类型必填说明
bundleNamestring是指定应用的bundle名称。
moduleNamestring否指定应用中的overlay module的名称。默认值：缺省该字段时，查询接口将查询指定应用中所有module的OverlayModuleInfo信息。

返回值：

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

错误码：

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

错误码ID错误信息
201Permission denied.
202Permission denied, non-system app called system api.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700001The specified bundleName is not found.
17700002The specified module name is not found.
17700032The specified bundle does not contain any overlay module.
17700033The specified module is not an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let bundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";

(async() => {
    try {
        let overlayModuleInfos = await overlay.getOverlayModuleInfoByBundleName(bundleName, moduleName);
        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.getOverlayModuleInfoByBundleName

getOverlayModuleInfoByBundleName(bundleName: string, moduleName: string, callback: AsyncCallback<Array<OverlayModuleInfo>>): void

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

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

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

系统接口： 此接口为系统接口。

参数：

参数名类型必填说明
bundleNamestring是指定应用的bundle名称。
moduleNamestring是指定应用中的overlay module的名称。缺省该字段时，查询接口将查询指定应用中所有module的OverlayModuleInfo信息。
callbackAsyncCallback<Array<OverlayModuleInfo>>是回调函数，当获取指定应用中指定module的OverlayModuleInfo信息成功时，err返回null。否则回调函数返回具体错误对象。

错误码：

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

错误码ID错误信息
201Permission denied.
202Permission denied, non-system app called system api.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700001The specified bundleName is not found.
17700002The specified module name is not found.
17700032The specified bundle does not contain any overlay module.
17700033The specified module is not an overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let bundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";

try {
    overlay.getOverlayModuleInfoByBundleName(bundleName, moduleName, (err, data) => {
        if (err) {
            console.error('getOverlayModuleInfoByBundleName 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('getOverlayModuleInfoByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
}

overlay.getOverlayModuleInfoByBundleName

getOverlayModuleInfoByBundleName(bundleName: string, callback: AsyncCallback<Array<OverlayModuleInfo>>): void

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

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

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

系统接口： 此接口为系统接口。

参数：

参数名类型必填说明
bundleNamestring是指定应用的bundle名称。
callbackAsyncCallback<Array<OverlayModuleInfo>>是回调函数，当获取指定应用中所有module的OverlayModuleInfo信息成功时，err返回null。否则回调函数返回具体错误对象。

错误码：

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

错误码ID错误信息
201Permission denied.
202Permission denied, non-system app called system api.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700001The specified bundleName is not found.
17700032The specified bundle does not contain any overlay module.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let bundleName = "com.example.myapplication_xxxxx";

try {
    overlay.getOverlayModuleInfoByBundleName(bundleName, (err, data) => {
        if (err) {
            console.error('getOverlayModuleInfoByBundleName 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('getOverlayModuleInfoByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
}

overlay.getTargetOverlayModuleInfosByBundleName

getTargetOverlayModuleInfosByBundleName(targetBundleName: string, moduleName?: string): Promise<Array<OverlayModuleInfo>>

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

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

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

系统接口： 此接口为系统接口。

参数：

参数名类型必填说明
targetBundleNamestring是指定目标应用的bundle名称。
moduleNamestring否指定应用中的目标module的名称。默认值：缺省该字段时，查询接口将查询指定应用中所有module所关联的OverlayModuleInfo信息。

返回值：

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

错误码：

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

错误码ID错误信息
201Permission denied.
202Permission denied, non-system app called system api.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700001The specified bundleName is not found.
17700002The specified module name is not found.
17700034The specified module is an overlay module.
17700035The specified bundle is an overlay bundle.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let targetBundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";

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

overlay.getTargetOverlayModuleInfosByBundleName

getTargetOverlayModuleInfosByBundleName(targetBundleName: string, moduleName: string, callback: AsyncCallback<Array<OverlayModuleInfo>>): void

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

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

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

系统接口： 此接口为系统接口。

参数：

参数名类型必填说明
targetBundleNamestring是指定目标应用的bundle名称。
moduleNamestring是指定应用中的目标module的名称。缺省该字段时，查询接口将查询指定应用中所有module所关联的OverlayModuleInfo信息。
callbackAsyncCallback<Array<OverlayModuleInfo>>是回调函数，当获取指定应用中指定module关联的所有OverlayModuleInfo信息成功时，err返回null。否则回调函数返回具体错误对象。

错误码：

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

错误码ID错误信息
201Permission denied.
202Permission denied, non-system app called system api.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700001The specified bundleName is not found.
17700002The specified module name is not found.
17700034The specified module is an overlay module.
17700035The specified bundle is an overlay bundle.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let targetBundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";

try {
    overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, moduleName, (err, data) => {
        if (err) {
            console.error('getTargetOverlayModuleInfosByBundleName 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('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
}

overlay.getTargetOverlayModuleInfosByBundleName

getTargetOverlayModuleInfosByBundleName(targetBundleName: string, callback: AsyncCallback<Array<OverlayModuleInfo>>): void

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

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

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

系统接口： 此接口为系统接口。

参数：

参数名类型必填说明
targetBundleNamestring是指定目标应用的bundle名称。
callbackAsyncCallback<Array<OverlayModuleInfo>>是回调函数，当获取指定应用中所有module关联的所有OverlayModuleInfo信息成功时，err返回null。否则回调函数返回具体错误对象。

错误码：

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

错误码ID错误信息
201Permission denied.
202Permission denied, non-system app called system api.
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
17700001The specified bundleName is not found.
17700035The specified bundle is an overlay bundle.

示例：

import { overlay } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let targetBundleName = "com.example.myapplication_xxxxx";

try {
    overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, (err, data) => {
        if (err) {
            console.error('getTargetOverlayModuleInfosByBundleName 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('getTargetOverlayModuleInfosByBundleName failed due to err code : ' + code + ' ' + 'message :' + message);
}

你可能感兴趣的鸿蒙文章

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

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/DiXQMh