鸿蒙5.0开发进阶：ArkTS API-UIExtensionContext

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

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

UIExtensionContext

UIExtensionContext是UIExtensionAbility的上下文环境，继承自ExtensionContext，提供UIExtensionAbility的相关配置信息以及操作UIAbility的方法，如启动UIAbility等。

说明

• 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
• 本模块接口仅可在Stage模型下使用。
• 本模块接口需要在主线程中使用，不要在Worker、TaskPool等子线程中使用。

导入模块

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

UIExtensionContext.startAbility

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

启动Ability。使用callback异步回调。

说明

组件启动规则详见：组件启动规则（Stage模型）。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
want	Want	是	启动Ability的want信息。
callback	AsyncCallback<void>	是	回调函数。当启动Ability成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍。

错误码ID	错误信息
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	Can not start invisible component.
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.
16000018	The application is not allow jumping to other applications.
16000019	Can not match any component.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000069	The extension cannot start the third party application.
16000070	The extension cannot start the service.
16200001	The caller has been released.
16000073	The app clone index is invalid.

示例：

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

export default class EntryAbility extends UIExtensionAbility {

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

try {
this.context.startAbility(want, (err: BusinessError) => {
if (err.code) {
// 处理业务逻辑错误
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
return;
}
// 执行正常业务
console.info('startAbility succeed');
});
} catch (err) {
// 处理入参错误异常
let code = (err as BusinessError).code;
let message = (err as BusinessError).message;
console.error(`startAbility failed, code is ${code}, message is ${message}`);
}
}
}

UIExtensionContext.startAbility

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

启动Ability。使用callback异步回调。

说明

组件启动规则详见：组件启动规则（Stage模型）。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
want	Want	是	启动Ability的want信息。
options	StartOptions	是	启动Ability所携带的参数。
callback	AsyncCallback<void>	是	回调函数。当启动Ability成功，err为undefined，否则为错误对象。

错误码：

以下错误码详细介绍。

错误码ID	错误信息
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	Can not start invisible component.
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	The application is not allow jumping to other applications.
16000019	Can not match any component.
16000050	Internal error.
16000053	The ability is not on the top of the UI.
16000055	Installation-free timed out.
16000069	The extension cannot start the third party application.
16000070	The extension cannot start the service.
16200001	The caller has been released.
16000073	The app clone index is invalid.

示例：

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

export default class EntryAbility extends UIExtensionAbility {
  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) {
          // 处理业务逻辑错误
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('startAbility succeed');
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIExtensionContext.startAbility

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

启动Ability。使用Promise异步回调。

说明

组件启动规则详见：组件启动规则（Stage模型）。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

参数：

参数名	类型	必填	说明
want