harmony 鸿蒙UIAbilityContext

2025-06-12
浏览 (5)

UIAbilityContext

UIAbilityContext, inherited from Context, provides the context environment for UIAbility that needs to store its status. UIAbilityContext provides UIAbility-related configuration and APIs for operating UIAbilities and ServiceExtensionAbilities. For example, you can use the APIs to start a UIAbility, terminate a UIAbility to which the UIAbilityContext belongs, and start, terminate, connect to, or disconnect from a ServiceExtensionAbility.

Modules to Import

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

Properties

System capability: SystemCapability.Ability.AbilityRuntime.Core

Name	Type	Readable	Writable	Description
abilityInfo	AbilityInfo	Yes	No	UIAbility information. Atomic service API: This API can be used in atomic services since API version 11.
currentHapModuleInfo	HapModuleInfo	Yes	No	HAP information. Atomic service API: This API can be used in atomic services since API version 11.
config	Configuration	Yes	No	UIAbility configuration, such as the language and color mode. Atomic service API: This API can be used in atomic services since API version 11.
windowStage¹²⁺	window.WindowStage	Yes	No	WindowStage object. It can be called only by the main thread. Atomic service API: This API can be used in atomic services since API version 12.

UIAbilityContext.startAbility

startAbility(want: Want, callback: AsyncCallback<void>): void

Starts an ability. This API uses an asynchronous callback to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000018	Redirection to a third-party application is not allowed in API version 11 or later.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.startAbility(want, (err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbility succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.startAbility

startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void

Starts an ability. This API uses an asynchronous callback to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
options	StartOptions	Yes	Parameters used for starting the ability.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
801	Capability not support.
16000001	The specified ability does not exist.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000018	Redirection to a third-party application is not allowed in API version 11 or later.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000067	The StartOptions check failed.
16000068	The ability is already running.
16300003	The target application is not self application.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { UIAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0
    };

    try {
      this.context.startAbility(want, options, (err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbility succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.startAbility

startAbility(want: Want, options?: StartOptions): Promise<void>

Starts an ability. This API uses a promise to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
options	StartOptions	No	Parameters used for starting the ability.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
801	Capability not support.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000018	Redirection to a third-party application is not allowed in API version 11 or later.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000067	The StartOptions check failed.
16000068	The ability is already running.
16300003	The target application is not self application.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { UIAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0
    };

    try {
      this.context.startAbility(want, options)
        .then(() => {
          // Carry out normal service processing.
          console.info('startAbility succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.startAbilityForResult

startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void

Starts an ability. This API uses an asynchronous callback to return the result. It can be called only by the main thread.

The following situations may be possible for a started ability: - Normally, you can call terminateSelfWithResult to terminate the ability. The result is returned to the caller. - If an exception occurs, for example, the ability is killed, an error message, in which resultCode is -1, is returned to the caller. - If different applications call this API to start an ability that uses the singleton mode and then call terminateSelfWithResult to terminate the ability, the normal result is returned to the last caller, and an error message, in which resultCode is -1, is returned to others.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
callback	AsyncCallback<AbilityResult>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000018	Redirection to a third-party application is not allowed in API version 11 or later.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.startAbilityForResult(want, (err: BusinessError, result: common.AbilityResult) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbilityForResult succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.startAbilityForResult

startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void

Starts an ability with the start options specified. This API uses an asynchronous callback to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
options	StartOptions	Yes	Parameters used for starting the ability.
callback	AsyncCallback<AbilityResult>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000018	Redirection to a third-party application is not allowed in API version 11 or later.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { UIAbility, Want, common, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0
    };

    try {
      this.context.startAbilityForResult(want, options, (err: BusinessError, result: common.AbilityResult) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbilityForResult succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.startAbilityForResult

startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>

Starts an ability. This API uses a promise to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information about the target ability.
options	StartOptions	No	Parameters used for starting the ability.

Return value

Type	Description
Promise<AbilityResult>	Promise used to return the result.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000018	Redirection to a third-party application is not allowed in API version 11 or later.
16000019	No matching ability is found.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.
16200001	The caller has been released.

Example

import { UIAbility, Want, common, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0
    };

    try {
      this.context.startAbilityForResult(want, options)
        .then((result: common.AbilityResult) => {
          // Carry out normal service processing.
          console.info('startAbilityForResult succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void

Terminates this ability. This API uses an asynchronous callback to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.

Example

The following is an example of calling terminateSelf to terminate a UIAbility. By default, the application retains the snapshot in the recent tasks list.

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


export default class EntryAbility extends UIAbility {
  onForeground() {
    try {
      this.context.terminateSelf((err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('terminateSelf succeed');
      });
    } catch (err) {
      // Capture the synchronization parameter error.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`terminateSelf failed, code is ${code}, message is ${message}`);
    }
  }
}

(Optional) To remove the mission from Recents (that is, not to retain the snapshot in the recent tasks list) when terminating the UIAbility, set the removeMissionAfterTerminate field to true in the module.json5 file.
```
{ 
  "module": { 
    // ... 
    "abilities": [
      {
        // ...
        "removeMissionAfterTerminate": true
      }
    ]
  }
}
```

UIAbilityContext.terminateSelf

terminateSelf(): Promise<void>

Terminates this ability. This API uses a promise to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

For details about the error codes, see Ability Error Codes.

ID	Error Message
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.

Example

The following is an example of calling terminateSelf to terminate a UIAbility. By default, the application retains the snapshot in the recent tasks list.

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


export default class EntryAbility extends UIAbility {
  onForeground() {
    try {
      this.context.terminateSelf()
        .then(() => {
          // Carry out normal service processing.
          console.info('terminateSelf succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Capture the synchronization parameter error.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`terminateSelf failed, code is ${code}, message is ${message}`);
    }
  }
}

(Optional) To remove the mission from Recents (that is, not to retain the snapshot in the recent tasks list) when terminating the UIAbility, set the removeMissionAfterTerminate field to true in the module.json5 file.
```
{
  "module": {
    // ...
    "abilities": [
      {
        // ...
        "removeMissionAfterTerminate": true
      }
    ]
  }
}
```

UIAbilityContext.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void

Terminates this ability. This API uses an asynchronous callback to return the result. It can be called only by the main thread.

If the ability is started by calling startAbilityForResult, the result is returned to the caller when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
parameter	AbilityResult	Yes	Information returned to the caller.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let resultCode = 100;
    // AbilityResult information returned to the caller.
    let abilityResult: common.AbilityResult = {
      want,
      resultCode
    };

    try {
      this.context.terminateSelfWithResult(abilityResult, (err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('terminateSelfWithResult succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`terminateSelfWithResult failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise<void>

Terminates this ability. This API uses a promise to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
parameter	AbilityResult	Yes	Information returned to the caller.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let resultCode = 100;
    // AbilityResult information returned to the caller.
    let abilityResult: common.AbilityResult = {
      want,
      resultCode
    };

    try {
      this.context.terminateSelfWithResult(abilityResult)
        .then(() => {
          // Carry out normal service processing.
          console.info('terminateSelfWithResult succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`terminateSelfWithResult failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.connectServiceExtensionAbility

connectServiceExtensionAbility(want: Want, options: ConnectOptions): number

Connects this ability to a ServiceExtensionAbility. This API can be called only by the main thread.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information for connecting to the ServiceExtensionAbility.
options	ConnectOptions	Yes	Instance of the callback function after the connection to the ServiceExtensionAbility is set up.

Return value

Type	Description
number	Result code of the connection.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.

Example

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'ServiceExtensionAbility'
    };
    let commRemote: rpc.IRemoteObject;
    let options: common.ConnectOptions = {
      onConnect(elementName, remote) {
        commRemote = remote;
        console.info('onConnect...');
      },
      onDisconnect(elementName) {
        console.info('onDisconnect...');
      },
      onFailed(code) {
        console.info('onFailed...');
      }
    };
    let connection: number;

    try {
      connection = this.context.connectServiceExtensionAbility(want, options);
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number): Promise<void>

Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses a promise to return the result. It can be called only by the main thread.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
connection	number	Yes	Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by connectServiceExtensionAbility.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    // connection is the return value of connectServiceExtensionAbility.
    let connection = 1;
    let commRemote: rpc.IRemoteObject|null;

    try {
      this.context.disconnectServiceExtensionAbility(connection).then(() => {
        commRemote = null;
        // Carry out normal service processing.
        console.info('disconnectServiceExtensionAbility succeed');
      }).catch((err: BusinessError) => {
        // Process service logic errors.
        console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
      });
    } catch (err) {
      commRemote = null;
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`disconnectServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback<void>): void

Disconnects this ability from a ServiceExtensionAbility and after the successful disconnection, sets the remote object returned upon the connection to void. This API uses an asynchronous callback to return the result. It can be called only by the main thread.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
connection	number	Yes	Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by connectServiceExtensionAbility.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    // connection is the return value of connectServiceExtensionAbility.
    let connection = 1;
    let commRemote: rpc.IRemoteObject|null;

    try {
      this.context.disconnectServiceExtensionAbility(connection, (err: BusinessError) => {
        commRemote = null;
        if (err.code) {
          // Process service logic errors.
          console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('disconnectServiceExtensionAbility succeed');
      });
    } catch (err) {
      commRemote = null;
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`disconnectServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.startAbilityByCall

startAbilityByCall(want: Want): Promise<Caller>

Starts an ability in the foreground or background and obtains the caller object for communicating with the ability. This API uses a promise to return the result. It can be called only by the main thread.

This API cannot be used to start the UIAbility with the launch type set to specified.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Information about the ability to start, including abilityName, moduleName, bundleName, deviceId, and parameters (optional). If parameters is left blank or null, the ability is started in the background.

Return value

Type	Description
Promise<Caller>	Promise used to return the caller object to communicate with.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000018	Redirection to a third-party application is not allowed in API version 11 or later.
16000050	Internal error.
16000071	App clone is not supported.
16000072	App clone or multi-instance is not supported.
16000073	The app clone index is invalid.
16000076	The app instance key is invalid.
16000077	The number of app instances reaches the limit.
16000078	The multi-instance is not supported.
16000079	The APP_INSTANCE_KEY cannot be specified.
16000080	Creating a new instance is not supported.

Example

Start an ability in the background.

import { UIAbility, Caller, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let caller: Caller;
    // Start an ability in the background by not passing parameters.
    let wantBackground: Want = {
      bundleName: 'com.example.myapplication',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: ''
    };

    try {
      this.context.startAbilityByCall(wantBackground)
        .then((obj: Caller) => {
          // Carry out normal service processing.
          caller = obj;
          console.info('startAbilityByCall succeed');
        }).catch((err: BusinessError) => {
        // Process service logic errors.
        console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.message}`);
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbilityByCall failed, code is ${code}, message is ${message}`);
    }
  }
}

Start an ability in the foreground.

import { UIAbility, Caller, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let caller: Caller;
    // Start an ability in the foreground with 'ohos.aafwk.param.callAbilityToForeground' in parameters set to true.
    let wantForeground: Want = {
      bundleName: 'com.example.myapplication',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: '',
      parameters: {
        'ohos.aafwk.param.callAbilityToForeground': true
      }
    };

    try {
      this.context.startAbilityByCall(wantForeground)
        .then((obj: Caller) => {
          // Carry out normal service processing.
          caller = obj;
          console.info('startAbilityByCall succeed');
        }).catch((err: BusinessError) => {
        // Process service logic errors.
        console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.message}`);
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbilityByCall failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.setMissionLabel

setMissionLabel(label: string, callback: AsyncCallback<void>): void

Sets a label for this UIAbility in the mission. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
label	string	Yes	Label of the ability to set.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    this.context.setMissionLabel('test', (result: BusinessError) => {
      console.info(`setMissionLabel: ${JSON.stringify(result)}`);
    });
  }
}

UIAbilityContext.setMissionLabel

setMissionLabel(label: string): Promise<void>

Sets a label for this UIAbility in the mission. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
label	string	Yes	Label of the ability to set.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    this.context.setMissionLabel('test').then(() => {
      console.info('success');
    }).catch((err: BusinessError) => {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`setMissionLabel failed, code is ${code}, message is ${message}`);
    });
  }
}

UIAbilityContext.setMissionContinueState¹⁰⁺

setMissionContinueState(state: AbilityConstant.ContinueState, callback: AsyncCallback<void>): void

Sets the mission continuation state of this UIAbility. This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
state	AbilityConstant.ContinueState	Yes	Mission continuation state.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility, AbilityConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result: BusinessError) => {
      console.info(`setMissionContinueState: ${JSON.stringify(result)}`);
    });
  }
}

UIAbilityContext.setMissionContinueState¹⁰⁺

setMissionContinueState(state: AbilityConstant.ContinueState): Promise<void>

Sets the mission continuation state of this UIAbility. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
state	AbilityConstant.ContinueState	Yes	Mission continuation state.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility, AbilityConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE).then(() => {
      console.info('success');
    }).catch((err: BusinessError) => {
      console.error(`setMissionContinueState failed, code is ${err.code}, message is ${err.message}`);
    });
  }
}

UIAbilityContext.restoreWindowStage

restoreWindowStage(localStorage: LocalStorage): void

Restores the WindowStage data in the ability. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
localStorage	LocalStorage	Yes	Storage used to store the restored window stage.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011	The context does not exist.
16000050	Internal error.

Example

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

export default class EntryAbility extends UIAbility {
  onForeground() {
    let storage = new LocalStorage();
    this.context.restoreWindowStage(storage);
  }
}

UIAbilityContext.isTerminating

isTerminating(): boolean

Checks whether this ability is in the terminating state.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

Type	Description
boolean	The value true means that the ability is in the terminating state, and false means the opposite.

Error codes

For details about the error codes, see Ability Error Codes.

ID	Error Message
16000011	The context does not exist.

Example

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

export default class EntryAbility extends UIAbility {
  onForeground() {
    let isTerminating: boolean = this.context.isTerminating();
    console.info(`ability state is ${isTerminating}`);
  }
}

UIAbilityContext.requestDialogService

requestDialogService(want: Want, result: AsyncCallback<dialogRequest.RequestResult>): void

Starts a ServiceExtensionAbility that supports modal dialog boxes. After the ServiceExtensionAbility is started, the application displays a modal dialog box. You can call setRequestResult to obtain the result. This API uses an asynchronous callback to return the result. It can be called only by the main thread.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information for starting the ServiceExtensionAbility.
result	AsyncCallback<dialogRequest.RequestResult>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16200001	The caller has been released.

Example

import { UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'AuthAccountServiceExtension'
    };

    try {
      this.context.requestDialogService(want, (err: BusinessError, result: dialogRequest.RequestResult) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info(`requestDialogService succeed, result = ${JSON.stringify(result)}`);
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`requestDialogService failed, code is ${code}, message is ${message}`);
    }
  }
}

## UIAbilityContext.requestDialogService

requestDialogService(want: Want): Promise<dialogRequest.RequestResult>

Starts a ServiceExtensionAbility that supports modal dialog boxes. After the ServiceExtensionAbility is started, the application displays a modal dialog box. You can call setRequestResult to obtain the result. This API uses a promise to return the result. It can be called only by the main thread.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information for starting the ServiceExtensionAbility.

Return value

Type	Description
Promise<dialogRequest.RequestResult>	Promise used to return the result.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation and prepare continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16200001	The caller has been released.

Example

import { UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'AuthAccountServiceExtension'
    };

    try {
      this.context.requestDialogService(want)
        .then((result: dialogRequest.RequestResult) => {
          // Carry out normal service processing.
          console.info(`requestDialogService succeed, result = ${JSON.stringify(result)}`);
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`requestDialogService failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.reportDrawnCompleted¹⁰⁺

reportDrawnCompleted(callback: AsyncCallback<void>): void

Reports an event indicating that page loading is complete (loadContent is successfully called). This API uses an asynchronous callback to return the result.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to report that page loading is complete.

Error codes

For details about the error codes, see Ability Error Codes.

ID	Error Message
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        return;
      }

      try {
        this.context.reportDrawnCompleted((err) => {
          if (err.code) {
            // Process service logic errors.
            console.error(`reportDrawnCompleted failed, code is ${err.code}, message is ${err.message}`);
            return;
          }
          // Carry out normal service processing.
          console.info('reportDrawnCompleted succeed');
        });
      } catch (err) {
        // Capture the synchronization parameter error.
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(`reportDrawnCompleted failed, code is ${code}, message is ${message}`);
      }
    });
    console.log("MainAbility onWindowStageCreate");
  }
};

UIAbilityContext.startAbilityByType¹¹⁺

startAbilityByType(type: string, wantParam: Record, abilityStartCallback: AbilityStartCallback, callback: AsyncCallback<void>) : void

Implicitly starts a given type of UIExtensionAbility. This API uses an asynchronous callback to return the result. It can be called only in the main thread and by applications running in the foreground.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of the UIExtensionAbility to start. For details, see Starting an Application of the Specified Type.
wantParam	Record<string, Object>	Yes	Extended parameter.
abilityStartCallback	AbilityStartCallback	Yes	Callback used to return the result.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000050	Internal error.

Example

import { UIAbility, common } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let wantParam: Record<string, Object> = {
      'time': '2023-10-23 20:45'
    };
    let abilityStartCallback: common.AbilityStartCallback = {
      onError: (code: number, name: string, message: string) => {
        console.log(`code:` + code + `name:` + name + `message:` + message);
      },
      onResult: (abilityResult: common.AbilityResult) => {
        console.log(`resultCode:` + abilityResult.resultCode + `bundleName:` + abilityResult.want?.bundleName);
      }
    };

    this.context.startAbilityByType("photoEditor", wantParam, abilityStartCallback, (err) => {
      if (err) {
        console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`);
      } else {
        console.log(`success`);
      }
    });
  }
}

UIAbilityContext.startAbilityByType¹¹⁺

startAbilityByType(type: string, wantParam: Record, abilityStartCallback: AbilityStartCallback) : Promise<void>

Implicitly starts a given type of UIExtensionAbility. This API uses a promise to return the result. It can be called only in the main thread and by applications running in the foreground.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Type of the UIExtensionAbility to start. For details, see Starting an Application of the Specified Type.
wantParam	Record<string, Object>	Yes	Extended parameter.
abilityStartCallback	AbilityStartCallback	Yes	Callback used to return the result.

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000050	Internal error.

Example

import { UIAbility, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let wantParam: Record<string, Object> = {
      'time': '2023-10-23 20:45'
    };
    let abilityStartCallback: common.AbilityStartCallback = {
      onError: (code: number, name: string, message: string) => {
        console.log(`code:` + code + `name:` + name + `message:` + message);
      },
      onResult: (abilityResult: common.AbilityResult) => {
        console.log(`resultCode:` + abilityResult.resultCode + `bundleName:` + abilityResult.want?.bundleName);
      }
    };

    this.context.startAbilityByType("photoEditor", wantParam, abilityStartCallback).then(() => {
      console.log(`startAbilityByType success`);
    }).catch((err: BusinessError) => {
      console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`);
    });
  }
}

UIAbilityContext.showAbility¹²⁺

showAbility(): Promise<void>

Shows the current ability. This API uses a promise to return the result. It takes effect only on 2-in-1 devices and tablets. It can be called only by the main thread.

Before calling this API, ensure that the application has been added to the status bar.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

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

Error codes

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

ID	Error Message
801	Capability not support.
16000050	Internal error.
16000067	The StartOptions check failed.

Example

// Index.ets
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  @State showAbility: string = 'showAbility'

  build() {
    Row() {
      Column() {
        Text(this.showAbility)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

            context.showAbility().then(() => {
              console.log(`showAbility success`);
            }).catch((err: BusinessError) => {
              console.error(`showAbility fail, err: ${JSON.stringify(err)}`);
            });
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

// EntryAbility.ts
import { UIAbility, Want, StartOptions, contextConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0,
      processMode: contextConstant.ProcessMode.NEW_PROCESS_ATTACH_TO_STATUS_BAR_ITEM,
      startupVisibility: contextConstant.StartupVisibility.STARTUP_SHOW
    };

    try {
      this.context.startAbility(want, options, (err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbility succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.hideAbility¹²⁺

hideAbility(): Promise<void>

Hides the current ability. This API uses a promise to return the result. It takes effect only on 2-in-1 devices and tablets. It can be called only by the main thread.

Before calling this API, ensure that the application has been added to the status bar.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

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

Error codes

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

ID	Error Message
801	Capability not support.
16000050	Internal error.
16000067	The StartOptions check failed.

Example

// Index.ets
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  @State hideAbility: string = 'hideAbility'

  build() {
    Row() {
      Column() {
        Text(this.hideAbility)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

            context.hideAbility().then(() => {
              console.log(`hideAbility success`);
            }).catch((err: BusinessError) => {
              console.error(`hideAbility fail, err: ${JSON.stringify(err)}`);
            });
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

// EntryAbility.ts
import { UIAbility, Want, StartOptions, contextConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0,
      processMode: contextConstant.ProcessMode.NEW_PROCESS_ATTACH_TO_STATUS_BAR_ITEM,
      startupVisibility: contextConstant.StartupVisibility.STARTUP_HIDE
    };

    try {
      this.context.startAbility(want, options, (err: BusinessError) => {
        if (err.code) {
          // Process service logic errors.
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // Carry out normal service processing.
        console.info('startAbility succeed');
      });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.moveAbilityToBackground¹²⁺

moveAbilityToBackground(): Promise<void>

Moves this ability from the foreground to the background. This API uses a promise to return the result. It can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

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

Error codes

For details about the error codes, see Ability Error Codes.

ID	Error Message
16000011	The context does not exist.
16000050	Internal error.
16000061	Operation not supported.
16000065	The API can be called only when the ability is running in the foreground.
16000066	An ability cannot switch to the foreground or background in Wukong mode.

Example

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

@Entry
@Component
struct Index {
  @State moveAbilityToBackground: string = 'Move To Background'

  build() {
    Row() {
      Column() {
        Text(this.moveAbilityToBackground)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

            context.moveAbilityToBackground().then(() => {
              console.log(`moveAbilityToBackground success.`);
            }).catch((err: BusinessError) => {
              console.log(`moveAbilityToBackground error: ${JSON.stringify(err)}.`);
            });
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

UIAbilityContext.openAtomicService¹²⁺

openAtomicService(appId: string, options?: AtomicServiceOptions): Promise<AbilityResult>

Starts an EmbeddableUIAbility in jump-out mode and obtains the result. This API uses a promise to return the result. It can be called only by the main thread.

The following situations may be possible for a started EmbeddableUIAbility: - Normally, you can call terminateSelfWithResult to terminate the EmbeddableUIAbility. The result is returned to the caller. - If an exception occurs, for example, the EmbeddableUIAbility is killed, an error message, in which resultCode is -1, is returned to the caller. - If different applications call this API to start an EmbeddableUIAbility and then call terminateSelfWithResult to terminate the EmbeddableUIAbility, the normal result is returned to the last caller, and an exception message, in which resultCode is -1, is returned to others.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
appId	string	Yes	Unique ID of the application, which is allocated by the cloud.
options	AtomicServiceOptions	No	Parameter carried in the request for starting the atomic service in jump-out mode.

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000002	Incorrect ability type.
16000003	The specified ID does not exist.
16000004	Failed to start the invisible ability.
16000011	The context does not exist.
16000012	The application is controlled.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16200001	The caller has been released.

Example

import { UIAbility, common, AtomicServiceOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let appId: string = '6918661953712445909';
    let options: AtomicServiceOptions = {
      displayId: 0
    };

    try {
      this.context.openAtomicService(appId, options)
        .then((result: common.AbilityResult) => {
          // Carry out normal service processing.
          console.info('openAtomicService succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`openAtomicService failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Process input parameter errors.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`openAtomicService failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.openLink¹²⁺

openLink(link: string, options?: OpenLinkOptions, callback?: AsyncCallback<AbilityResult>): Promise<void>

Starts a UIAbility through App Linking. This API uses a promise to return the result. It can be called only by the main thread.

A URL in the standard format is passed in to the link field to start the target UIAbility based on the implicit Want matching rules. The target UIAbility must have the following filter characteristics to process links of App Linking: - The actions field contains ohos.want.action.viewData. - The entities field contains entity.system.browsable. - The uris field contains elements whose scheme is https and domainVerify is true.

If you want to obtain the result after the started UIAbility is terminated, set the callback parameter. For details about how to use this parameter, see startAbilityForResult. If an input parameter is invalid, for example, a mandatory parameter is not set or the URL set in link is not in the standard format, an exception is thrown. If the parameter verification is successful but an error occurs when starting the target UIAbility, the error information is returned through promise.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
link	string	Yes	URL to open, which must be in the standard format.
options	OpenLinkOptions	No	Options of the URL.
callback	AsyncCallback<AbilityResult>	No	Callback used to return the result.

Return value

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

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	The crowdtesting application expires.
16000009	An ability cannot be started or stopped in Wukong mode.
16000010	The call with the continuation flag is forbidden.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16200001	The caller has been released.
16000053	The ability is not on the top of the UI.

Example

import { common, OpenLinkOptions } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

const DOMAIN = 0xeeee;
const TAG: string = '[openLinkDemo]';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Button("Call StartAbilityForResult")
        .onClick(() => {
          let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
          let link: string = 'https://www.example.com';
          let openLinkOptions: OpenLinkOptions = {
            appLinkingOnly: true,
            parameters: { demo_key: 'demo_value' }
          };

          try {
            context.openLink(
              link,
              openLinkOptions,
              (err, result) => {
                hilog.error(DOMAIN, TAG, `openLink callback error.code: ${JSON.stringify(err)}`);
                hilog.info(DOMAIN, TAG, `openLink callback result: ${JSON.stringify(result.resultCode)}`);
                hilog.info(DOMAIN, TAG, `openLink callback result data: ${JSON.stringify(result.want)}`);
              }
            ).then(() => {
              hilog.info(DOMAIN, TAG, `open link success.`);
            }).catch((err: BusinessError) => {
              hilog.error(DOMAIN, TAG, `open link failed, errCode ${JSON.stringify(err.code)}`);
            });
          }
          catch (e) {
            hilog.error(DOMAIN, TAG, `exception occured, errCode ${JSON.stringify(e.code)}`);
          }
        })
    }
    .height('100%')
    .width('100%')
  }
}

UIAbilityContext.backToCallerAbilityWithResult¹²⁺

backToCallerAbilityWithResult(abilityResult: AbilityResult, requestCode: string): Promise<void>

Returns the startup result to the caller of startAbilityForResult or openLink. Different from terminateSelfWithResult, this API does not destroy the current ability (target ability) when it returns the result. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
abilityResult	AbilityResult	Yes	Result returned to the caller.
requestCode	string	Yes	Request code generated by the system when the target ability is started using startAbilityForResult or openLink. The value can be obtained from the CALLER_REQUEST_CODE field in want.

Return value

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

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000009	An ability cannot be started or stopped in Wukong mode.
16000011	The context does not exist.
16000050	Internal error.
16000074	The caller does not exist.
16000075	Not support back to caller.

Example The caller uses startAbilityForResult to start an ability, and the target ability calls backToCallerAbilityWithResult to return the result to the caller.

// Caller
// index.ets
import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@ohos.base';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)

        Button("Call StartAbilityForResult")
          .onClick(() => {
            let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
            let want: Want = {
              bundleName: 'com.example.demo2',
              abilityName: 'EntryAbility'
            };

            try {
              // Use startAbilityForResult to start the target ability.
              context.startAbilityForResult(want, (err: BusinessError, result: common.AbilityResult) => {
                if (err.code) {
                  // Process service logic errors.
                  hilog.error(0x0000, 'testTag', `startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
                  this.message = `startAbilityForResult failed: code is ${err.code}, message is ${err.message}`
                  return;
                }
                // Carry out normal service processing.
                hilog.info(0x0000, 'testTag', `startAbilityForResult succeed`);
                hilog.info(0x0000, 'testTag', `AbilityResult is ${JSON.stringify(result)}`);
                this.message = `AbilityResult.resultCode: ${JSON.stringify(result.resultCode)}`
              });
            } catch (err) {
              // Process input parameter errors.
              let code = (err as BusinessError).code;
              let message = (err as BusinessError).message;
              hilog.error(0x0000, 'testTag', `startAbilityForResult failed, code is ${code}, message is ${message}`);
              this.message = `startAbilityForResult failed, code is ${code}, message is ${message}`;
            }
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

// Target ability
// EntryAbility.ets
import { AbilityConstant, common, UIAbility, Want, wantConstant } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Obtain the CALLER_REQUEST_CODE of the caller from want and save it.
    let callerRequestCode: string = want?.parameters?.[wantConstant.Params.CALLER_REQUEST_CODE] as string;
    AppStorage.setOrCreate<string>("callerRequestCode", callerRequestCode)
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    let callerRequestCode: string = want?.parameters?.[wantConstant.Params.CALLER_REQUEST_CODE] as string;
    AppStorage.setOrCreate<string>("callerRequestCode", callerRequestCode)
  }

  onForeground(): void {
    // Obtain the saved CALLER_REQUEST_CODE.
    let callerRequestCode: string = AppStorage.get<string>("callerRequestCode") as string;
    hilog.info(0x0000, 'testTag', `callerRequestCode is ${callerRequestCode}`);
    let want: Want = {};
    let resultCode = 100;
    let abilityResult: common.AbilityResult = {
      want,
      resultCode
    };
    try {
      // Return the result to the caller.
      this.context.backToCallerAbilityWithResult(abilityResult, callerRequestCode)
        .then(() => {
          // Carry out normal service processing.
          hilog.info(0x0000, 'testTag', 'backToCallerAbilityWithResult succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          hilog.error(0x0000, 'testTag', `backToCallerAbilityWithResult failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // Capture the synchronization parameter error.
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      hilog.error(0x0000, 'testTag', `backToCallerAbilityWithResult failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.setRestoreEnabled¹⁴⁺

setRestoreEnabled(enabled: boolean): void

Sets whether to enable backup and restore for this UIAbility.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
enabled	boolean	Yes	Whether to enable backup and restore. The value true means to enable backup and restore, and false means the opposite.

Error codes

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

ID	Error Message
401	If the input parameter is not valid parameter.
16000011	The context does not exist.

Example

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    let enabled = true;
    try {
      this.context.setRestoreEnabled(enabled);
    } catch (paramError) {
      let code = (paramError as BusinessError).code;
      let message = (paramError as BusinessError).message;
      console.error(`setRestoreEnabled failed, err code: ${code}, err msg: ${message}`);
    }
  }
}

UIAbilityContext.startUIServiceExtensionAbility¹⁴⁺

startUIServiceExtensionAbility(want: Want): Promise<void>

Starts a UIServiceExtensionAbility. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information required for startup.

Return value

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

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000012	The application is controlled.
16000013	The application is controlled by EDM.
16000019	No matching ability is found.
16000050	Internal error.
16200001	The caller has been released.

Example

import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    Column() {
      Row() {
        // Create a Start button.
        Button('start ability')
          .enabled(true)
          .onClick(() => {
            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
            let startWant: Want = {
              bundleName: 'com.acts.uiserviceextensionability',
              abilityName: 'UiServiceExtAbility',
            };
            try {
              // Start the UIServiceExtensionAbility.
              context.startUIServiceExtensionAbility(startWant).then(() => {
                console.log('startUIServiceExtensionAbility success');
              }).catch((error: BusinessError) => {
                console.log('startUIServiceExtensionAbility error', JSON.stringify(error));
              })
            } catch (err) {
              console.log('startUIServiceExtensionAbility failed', JSON.stringify(err));
            }
          })
      }
    }
  }
}

UIAbilityContext.connectUIServiceExtensionAbility¹⁴⁺

connectUIServiceExtensionAbility(want: Want, callback: UIServiceExtensionConnectCallback) : Promise<UIServiceProxy>

Connects to a UIServiceExtensionAbility. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information required for connection.
callback	UIServiceExtensionConnectCallback	Yes	Callback for connecting to the UIServiceExtensionAbility.

Return value

Type	Description
Promise<UIServiceProxy>	Promise used to return a UIServiceProxy object.

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
801	Capability not supported.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
16000004	Failed to start the invisible ability.
16000005	The specified process does not have the permission.
16000008	The crowdtesting application expires.
16000011	The context does not exist.
16000013	The application is controlled by EDM.
16000050	Internal error.
16000055	Installation-free timed out.

Example

import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

const TAG: string = '[Extension] ';

@Entry
@Component
struct UIServiceExtensionAbility {
  dataCallBack : common.UIServiceExtensionConnectCallback = {
    // Receive data
    onData: (data: Record<string, Object>) => {
      console.log(`dataCallBack received data`, JSON.stringify(data));
    },
    // Disconnect from the UIServiceExtensionAbility.
    onDisconnect: () => {
      console.log(`dataCallBack onDisconnect`);
    }
  }

  async myConnect() {
    // Obtain the context.
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    let startWant: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'UiServiceExtAbility'
    };

    try {
      // Connect to the UIServiceExtensionAbility.
      context.connectUIServiceExtensionAbility(startWant, this.dataCallBack)
        .then((proxy: common.UIServiceProxy) => {
          console.log(TAG + `try to connectUIServiceExtensionAbility`, JSON.stringify(proxy));
        }).catch((err: Error) => {
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.log(TAG + `connectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`);
      });
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.log(TAG + `connectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    };
  }

  build() {
    RelativeContainer() {
      // Create a Connect button.
      Button('connectServiceExtensionAbility', { type: ButtonType.Capsule, stateEffect: true })
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
        .onClick(() => {
          this.myConnect()
        });
    }
    .height('100%')
    .width('100%')
  }
}

UIAbilityContext.disconnectUIServiceExtensionAbility¹⁴⁺

disconnectUIServiceExtensionAbility(proxy: UIServiceProxy): Promise<void>

Disconnects from a UIServiceExtensionAbility. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
proxy	UIServiceProxy	Yes	Proxy returned after connectUIServiceExtensionAbility is called.

Return value

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

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16000011	The context does not exist.
16000050	Internal error.

Example

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

const TAG: string = '[Extension] ';

@Entry
@Component
struct UIServiceExtensionAbility {
  comProxy: common.UIServiceProxy|null = null;

  build() {
    Scroll() {
      Column() {
        // Create a Disconnect button.
        Button('disconnectUIServiceExtensionAbility', { type: ButtonType.Capsule, stateEffect: true })
          .margin({
            top: 5,
            left: 10,
            right: 10,
            bottom: 5
          })
          .alignRules({
            center: { anchor: '__container__', align: VerticalAlign.Center },
            middle: { anchor: '__container__', align: HorizontalAlign.Center }
          })
          .onClick(() => {
            this.myDisconnectUIServiceExtensionAbility()
          });
      }
      .width('100%')
    }
    .height('100%')
  }

  myDisconnectUIServiceExtensionAbility() {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

    try {
      // Disconnect from the UIServiceExtensionAbility.
      context.disconnectUIServiceExtensionAbility(this.comProxy)
        .then(() => {
          console.log(TAG + `disconnectUIServiceExtensionAbility succeed ${this.comProxy}}`);
        }).catch((err: Error) => {
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.log(TAG + `disconnectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`);
      });
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.log(TAG + `disconnectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.setAbilityInstanceInfo¹⁵⁺

setAbilityInstanceInfo(label: string, icon: image.PixelMap) : Promise<void>

Sets the icon and label for this UIAbility. The icon and label can be displayed in Recents and the shortcut bar. This API uses a promise to return the result.

Required permissions: ohos.permission.SET_ABILITY_INSTANCE_INFO

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
label	string	Yes	Label. The label cannot be an empty string, and can contain a maximum of 1024 bytes.
icon	image.PixelMap	Yes	Icon. The recommended icon size is 512 px * 512 px.

Return value

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

Error codes

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

ID	Error Message
201	The application does not have permission to call the interface.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801	Capability not supported.
16000011	The context does not exist.
16000050	Internal error.

Example

import { UIAbility } from '@kit.AbilityKit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', async (err, data) => {
      if (err.code) {
        console.error(`loadContent failed, code is ${err.code}`);
        return;
      }

      let newLabel: string = 'instance label';
      let color = new ArrayBuffer(0);
      let imagePixelMap: image.PixelMap = await image.createPixelMap(color, {
        size: {
          height: 100,
          width: 100
        }
      });
      this.context.setAbilityInstanceInfo(newLabel, imagePixelMap)
        .then(() => {
          console.info('setAbilityInstanceInfo success');
        }).catch((err: BusinessError) => {
          console.error(`setAbilityInstanceInfo failed, code is ${err.code}, message is ${err.message}`);
        });
      });
  }
}

UIAbilityContext.revokeDelegator¹⁷⁺

revokeDelegator() : Promise<void>

When the first UIAbility launched under a module needs to redirect to another UIAbility, the target UIAbility is known as the DelegatorAbility. For details about how to set up the DelegatorAbility, see step 1 in the example provided for this API.

Once the DelegatorAbility has completed its specific operations, you can use this API to revert to the first UIAbility. This API uses a promise to return the result.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Return value

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

Error codes

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

ID	Error Message
801	Capability not support.
16000011	The context does not exist.
16000050	Internal error.
16000065	The API can be called only when the ability is running in the foreground.
16000084	Only allow DelegatorAbility to call the method once.
16000085	The interaction process between Ability and Window encountered an error.

Example

Set a DelegatorAbility.

Configure abilitySrcEntryDelegator and abilityStageSrcEntryDelegator in the module.json5 file. When the first UIAbility of the module is cold started, the system preferentially starts the UIAbility specified by abilitySrcEntryDelegator. > NOTE > > - If the UIAbility is started by calling startAbilityByCall, the system ignores abilitySrcEntryDelegator and abilityStageSrcEntryDelegator configured in the module.json5 file. > - The module name specified by abilityStageSrcEntryDelegator must be different from the current module name.
```
{
  "module": {
    // ...
    "abilityStageSrcEntryDelegator": "xxxModuleName",
    "abilitySrcEntryDelegator": "xxxAbilityName",
    // ...
  }
}
```

Revoke the DelegatorAbility.

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


export default class DelegatorAbility extends UIAbility {
  onForeground() {
    // After the DelegatorAbility completes the specific operation, call revokeDelegator to revert to the first UIAbility.
    this.context.revokeDelegator().then(() => {
      console.info('revokeDelegator success');
    }).catch((err: BusinessError) => {
      console.error(`revokeDelegator failed, code is ${err.code}, message is ${err.message}`);
    });
  }
}

UIAbilityContext.setColorMode¹⁸⁺

setColorMode(colorMode: ConfigurationConstant.ColorMode): void

Sets the color mode for this UIAbility. Before calling this API, ensure that the page corresponding to the UIAbility has been loaded. This API can be called only by the main thread.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Name	Type	Mandatory	Description
colorMode	ConfigurationConstant.ColorMode	Yes	Color mode. The options are as follows: - COLOR_MODE_DARK: dark mode. - COLOR_MODE_LIGHT: light mode. - COLOR_MODE_NOT_SET: not set (following the system or application).

Error codes

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

ID	Error Message
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011	The context does not exist.

Example

import { UIAbility, ConfigurationConstant } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class MyAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content.');
        return;
      }
      let uiAbilityContext = this.context;
      uiAbilityContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK);
    });
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit

harmony 鸿蒙AbilityAccessControl

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_access_control.h

harmony 鸿蒙ability_base_common.h

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/louQ8v

harmony 鸿蒙UIAbilityContext

UIAbilityContext

Modules to Import

Properties

UIAbilityContext.startAbility

UIAbilityContext.startAbility

UIAbilityContext.startAbility

UIAbilityContext.startAbilityForResult

UIAbilityContext.startAbilityForResult

UIAbilityContext.startAbilityForResult

UIAbilityContext.terminateSelf

UIAbilityContext.terminateSelf

UIAbilityContext.terminateSelfWithResult

UIAbilityContext.terminateSelfWithResult

UIAbilityContext.connectServiceExtensionAbility

UIAbilityContext.disconnectServiceExtensionAbility

UIAbilityContext.disconnectServiceExtensionAbility

UIAbilityContext.startAbilityByCall

UIAbilityContext.setMissionLabel

UIAbilityContext.setMissionLabel

UIAbilityContext.setMissionContinueState10+

UIAbilityContext.setMissionContinueState10+

UIAbilityContext.restoreWindowStage

UIAbilityContext.isTerminating

UIAbilityContext.requestDialogService

UIAbilityContext.reportDrawnCompleted10+

UIAbilityContext.startAbilityByType11+

UIAbilityContext.startAbilityByType11+

UIAbilityContext.showAbility12+

UIAbilityContext.hideAbility12+

UIAbilityContext.moveAbilityToBackground12+

UIAbilityContext.openAtomicService12+

UIAbilityContext.openLink12+

UIAbilityContext.backToCallerAbilityWithResult12+

UIAbilityContext.setRestoreEnabled14+

UIAbilityContext.startUIServiceExtensionAbility14+

UIAbilityContext.connectUIServiceExtensionAbility14+

UIAbilityContext.disconnectUIServiceExtensionAbility14+

UIAbilityContext.setAbilityInstanceInfo15+

UIAbilityContext.revokeDelegator17+

UIAbilityContext.setColorMode18+

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

UIAbilityContext.setMissionContinueState¹⁰⁺

UIAbilityContext.setMissionContinueState¹⁰⁺

UIAbilityContext.reportDrawnCompleted¹⁰⁺

UIAbilityContext.startAbilityByType¹¹⁺

UIAbilityContext.startAbilityByType¹¹⁺

UIAbilityContext.showAbility¹²⁺

UIAbilityContext.hideAbility¹²⁺

UIAbilityContext.moveAbilityToBackground¹²⁺

UIAbilityContext.openAtomicService¹²⁺

UIAbilityContext.openLink¹²⁺

UIAbilityContext.backToCallerAbilityWithResult¹²⁺

UIAbilityContext.setRestoreEnabled¹⁴⁺

UIAbilityContext.startUIServiceExtensionAbility¹⁴⁺

UIAbilityContext.connectUIServiceExtensionAbility¹⁴⁺

UIAbilityContext.disconnectUIServiceExtensionAbility¹⁴⁺

UIAbilityContext.setAbilityInstanceInfo¹⁵⁺

UIAbilityContext.revokeDelegator¹⁷⁺

UIAbilityContext.setColorMode¹⁸⁺