@ohos.bundle.overlay (overlay模块)

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

说明：

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

导入模块

import overlay from '@ohos.bundle.overlay';

overlay.setOverlayEnabled

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

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

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

参数：

返回值：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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

参数：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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.setOverlayEnabledByBundleName

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

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

需要权限： ohos.permission.CHANGE_OVERLAY_ENABLED_STATE

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

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

参数：

返回值：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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.info('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.info('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

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

参数：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
let bundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";
let isEnabled = false;

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

overlay.getOverlayModuleInfo

getOverlayModuleInfo(moduleName: string): Promise<OverlayModuleInfo>

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

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

参数：

返回值：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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

参数：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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

参数：

返回值：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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

参数：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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);
}

overlay.getOverlayModuleInfoByBundleName

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

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

需要权限： ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

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

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

参数：

返回值：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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.log('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

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

参数：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
let bundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";

try {
    overlay.getOverlayModuleInfoByBundleName(bundleName, moduleName, (err, data) => {
        if (err) {
            console.log('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.log('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

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

参数：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
let bundleName = "com.example.myapplication_xxxxx";

try {
    overlay.getOverlayModuleInfoByBundleName(bundleName, (err, data) => {
        if (err) {
            console.log('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.log('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

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

参数：

返回值：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
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.log('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

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

参数：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
let targetBundleName = "com.example.myapplication_xxxxx";
let moduleName = "feature";

try {
    overlay.getTargetOverlayModuleInfosByBundleName(targetBundleName, moduleName, (err, data) => {
        if (err) {
            console.log('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.log('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

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

参数：

错误码：

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

示例：

import overlay from '@ohos.bundle.overlay';
import { BusinessError } from '@ohos.base';
let targetBundleName = "com.example.myapplication_xxxxx";

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

overlay特征应用介绍

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

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