@ohos.bundle.overlay (overlay Module)

The module provides APIs for querying the OverlayModuleInfo of an application with the overlay feature, and disabling and enabling the feature.

An application with the overlay feature contains an overlay resource package. For details about this package, see Overlay Mechanism.

NOTE

The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.

The APIs provided by this module apply only to the stage model and static overlay mode.

Modules to Import

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

overlay.setOverlayEnabled

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

Enables or disables a module with the overlay feature in the current application. This API uses a promise to return the result.

System capability: SystemCapability.BundleManager.BundleFramework.Overlay

Parameters

Name	Type	Mandatory	Description
moduleName	string	Yes	Name of the module with the overlay feature.
isEnabled	boolean	Yes	Whether to enable the module with the overlay feature. true to enable, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
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.

Example

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

Enables or disables a module with the overlay feature in the current application. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.BundleManager.BundleFramework.Overlay

Parameters

Name	Type	Mandatory	Description
moduleName	string	Yes	Name of the module with the overlay feature.
isEnabled	boolean	Yes	Whether to enable the module with the overlay feature. true to enable, false otherwise.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is null; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
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.

Example

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>

Obtains the OverlayModuleInfo about a module with the overlay feature in the current application. This API uses a promise to return the result.

System capability: SystemCapability.BundleManager.BundleFramework.Overlay

Parameters

Name	Type	Mandatory	Description
moduleName	string	Yes	Name of the module with the overlay feature.

Return value

Type	Description
Promise<OverlayModuleInfo>	Promise used to return the result, which is an OverlayModuleInfo object.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
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.

Example

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

let moduleName = "feature";

(async () => {
  try {
    let overlayModuleInfo = await overlay.getOverlayModuleInfo(moduleName);
    console.info('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

Obtains the OverlayModuleInfo about a module with the overlay feature in the current application. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.BundleManager.BundleFramework.Overlay

Parameters

Name	Type	Mandatory	Description
moduleName	string	Yes	Name of the module with the overlay feature.
callback	AsyncCallback<OverlayModuleInfo>	Yes	Callback used to return the result, which is an OverlayModuleInfo object. If the operation is successful, err is null; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
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.

Example

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.info('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>>

Obtains the OverlayModuleInfo associated with the specified target module. Modules with the overlay feature generally provide an overlay resource file for other modules (target module) on the device. This API uses a promise to return the result.

System capability: SystemCapability.BundleManager.BundleFramework.Overlay

Parameters

Name	Type	Mandatory	Description
targetModuleName	string	Yes	Name of the target module specified by modules with the overlay feature.

Return value

Type	Description
Promise<Array<OverlayModuleInfo>>	Promise used to return the result, which is an array of OverlayModuleInfo objects.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
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.

Example

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

let targetModuleName = "feature";

(async () => {
  try {
    let overlayModuleInfos = await overlay.getTargetOverlayModuleInfos(targetModuleName);
    console.info('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

Obtains the OverlayModuleInfo associated with the specified target module. Modules with the overlay feature generally provide an overlay resource file for other modules (target module) on the device. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.BundleManager.BundleFramework.Overlay

Parameters

Name	Type	Mandatory	Description
targetModuleName	string	Yes	Name of the target module specified by modules with the overlay feature.
callback	AsyncCallback<Array<OverlayModuleInfo>>	Yes	Callback used to return the result, which is an OverlayModuleInfo object. If the operation is successful, err is null; otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Bundle Error Codes.

ID	Error Message
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.

Example

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.info('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

Defines the information about a module with the overlay feature.

System capability: SystemCapability.BundleManager.BundleFramework.Overlay

Type	Description
_OverlayModuleInfo.OverlayModuleInfo	Information about a module with the overlay feature.