UIExtensionContext (System API)

UIExtensionContext, inherited from ExtensionContext, provides the context environment for UIExtensionAbility. It provides UIExtensionAbility-related configuration and APIs for operating the UIExtensionAbility. For example, you can use the APIs to start a UIExtensionAbility.

NOTE

• The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• The APIs of this module can be used only in the stage model.
• The APIs provided by this module are system APIs.

Modules to Import

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

UIExtensionContext.startAbilityForResultAsCaller

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

Starts an ability with the caller information specified. This API uses a promise to return the result.

The caller information is carried in want and identified at the system service layer. The ability can obtain the caller information from the want parameter in the onCreate lifecycle callback.

When this API is used to start an ability, the caller information carried in want is not overwritten by the current application information. The system service layer can obtain the initial caller information.

• 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 exception message, in which resultCode is -1, is returned to others.

NOTE

For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

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);
    });
  }
}

UIExtensionContext.startServiceExtensionAbility¹⁸⁺

startServiceExtensionAbility(want: Want): Promise<void>

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

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

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(() => {
          // Carry out normal service processing.
          console.info('startServiceExtensionAbility succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`startServiceExtensionAbility 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(`startServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

UIExtensionContext.startServiceExtensionAbilityWithAccount¹⁸⁺

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

Starts a ServiceExtensionAbility under a specified system account. This API uses a promise to return the result.

NOTE

For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).

Permission verification is not required when accountId specifies the current user.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Required permissions: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Return value

Error codes

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

Example

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(() => {
          // Carry out normal service processing.
          console.info('startServiceExtensionAbilityWithAccount succeed');
        })
        .catch((err: BusinessError) => {
          // Process service logic errors.
          console.error(`startServiceExtensionAbilityWithAccount 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(`startServiceExtensionAbilityWithAccount failed, code is ${code}, message is ${message}`);
    }
  }
}

UIExtensionContext.setHostPageOverlayForbidden¹⁵⁺

setHostPageOverlayForbidden(isForbidden: boolean) : void

Sets whether the page started by the UIExtensionAbility can be overlaid by the page of the user.

NOTE

For details about the startup rules for the components in the stage model, see Component Startup Rules (Stage Model).

This API must be called before a window is created. You are advised to call it within the onCreate lifecycle of the UIExtensionAbility.

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

System capability: SystemCapability.Ability.AbilityRuntime.Core

Parameters

Error codes

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

Example

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

export default class UIExtAbility extends UIExtensionAbility {
  OnCreate() {
    try {
      this.context.setHostPageOverlayForbidden(true)
    } catch (err) {
      // Process input parameter errors.
      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 鸿蒙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