UIExtensionContext (系统接口)

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

说明：

• 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
• 本模块接口仅可在Stage模型下使用。
• 本模块接口为系统接口。

导入模块

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

UIExtensionContext

startAbilityForResultAsCaller

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

使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用Promise异步回调。

• 正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用方。
• 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。
• 如果被启动的Ability模式是单实例模式，不同应用多次调用该接口启动这个Ability，当这个Ability调用terminateSelfWithResult接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息，异常信息中resultCode为-1。

说明：

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

模型约束：此接口仅可在Stage模型下使用。

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

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

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

export default class UIExtension extends UIExtensionAbility {
  onForeground() {
    this.context.startAbilityForResultAsCaller({
      bundleName: 'com.example.startabilityforresultascaller',
      abilityName: 'EntryAbility',
      moduleName: 'entry'
    }).then((data) => {
      console.log('=======>startAbilityForResultAsCaller data Promise ======>' + JSON.stringify(data));
    }).catch((error: BusinessError) => {
      console.log('=======>startAbilityForResultAsCaller error.code Promise ======>' + error.code);
    });
  }
}

startServiceExtensionAbility¹⁸⁺

startServiceExtensionAbility(want: Want): Promise<void>

启动一个ServiceExtensionAbility。使用Promise异步回调。

模型约束：此接口仅可在Stage模型下使用。

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

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

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

export default class UIExtAbility extends UIExtensionAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      moduleName: 'entry',
      abilityName: 'ServiceExtensionAbility'
    };

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

startServiceExtensionAbilityWithAccount¹⁸⁺

startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise<void>

启动一个指定系统账号下的ServiceExtensionAbility。使用Promise异步回调。

说明：

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

当accountId为当前用户时，无需进行权限校验。

模型约束：此接口仅可在Stage模型下使用。

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

需要权限：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

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

export default class UIExtAbility extends UIExtensionAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      moduleName: 'entry',
      abilityName: 'ServiceExtensionAbility'
    };
    let accountId = 100;

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

setHostPageOverlayForbidden¹⁵⁺

setHostPageOverlayForbidden(isForbidden: boolean) : void

是否允许UIExtensionAbility拉起的页面被使用方的页面覆盖。

说明：

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

该接口需要在窗口创建之前调用。建议在UIExtensionAbility的onCreate生命周期内调用。

模型约束：此接口仅可在Stage模型下使用。

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

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码。

示例：

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

export default class UIExtAbility extends UIExtensionAbility {
  OnCreate() {
    try {
      this.context.setHostPageOverlayForbidden(true)
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`setHostPageOverlayForbidden failed, code is ${code}, message is ${message}`);
    }
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit（程序框架服务）

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_base_common.h

harmony 鸿蒙ability_runtime_common.h

harmony 鸿蒙application_context.h