HarmonyOS实战开发：ServiceExtensionContext

最新推荐文章于 2024-06-18 15:33:58 发布
最新推荐文章于 2024-06-18 15:33:58 发布
阅读量690 收藏 11
点赞数 17
分类专栏： 鸿蒙 文章标签： harmonyos 华为 鸿蒙 鸿蒙系统 android
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/2401_84194030/article/details/139158671
版权

ServiceExtensionContext模块是ServiceExtensionAbility的上下文环境，继承自ExtensionContext。

ServiceExtensionContext模块提供ServiceExtensionAbility具有的能力，包括启动、停止、绑定、解绑Ability。

说明：

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

导入模块

import common from '@ohos.app.ability.common';

使用说明

在使用ServiceExtensionContext的功能前，需要通过ServiceExtensionAbility子类实例获取。

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import rpc from '@ohos.rpc';

let commRemote: rpc.IRemoteObject; // 断开连接时需要释放
class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
      let context = this.context; // 获取ServiceExtensionContext
  }
}

ServiceExtensionContext.startAbility

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

启动Ability。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。
callbackAsyncCallback<void>是回调函数，返回接口调用是否成功的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapp',
      abilityName: 'MyAbility'
    };

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

ServiceExtensionContext.startAbility

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

启动Ability，结果以Promise的形式返回。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。
optionsStartOptions否启动Ability所携带的参数。

返回值：

类型说明
Promise<void>返回一个Promise，包含启动的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapp',
      abilityName: 'MyAbility'
    };
    let options: StartOptions = {
      windowMode: 0,
    };

    try {
      this.context.startAbility(want, options)
        .then((data: void) => {
          // 执行正常业务
          console.log('startAbility succeed');
        })
        .catch((error: BusinessError) => {
          // 处理业务逻辑错误
          console.error('startAbility failed, error.code: ${error.code}, error.message: ${error.message}');
        });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.startAbility

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

启动Ability，结果以Callback的形式返回。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
optionsStartOptions是启动Ability所携带的参数。
callbackAsyncCallback<void>是callback形式返回启动结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      windowMode: 0
    };

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

ServiceExtensionContext.startAbilityWithAccount

startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback<void>): void;

根据account启动Ability（callback形式）。

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

需要权限：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
accountIdnumber是系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。
callbackAsyncCallback<void>是启动Ability的回调函数。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

    try {
      this.context.startAbilityWithAccount(want, accountId, (error: BusinessError) => {
        if (error.code) {
          // 处理业务逻辑错误
          console.error('startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}');
          return;
        }
        // 执行正常业务
        console.log('startAbilityWithAccount succeed');
      });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.startAbilityWithAccount

startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback<void>): void;

根据account启动Ability（callback形式）。

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

需要权限：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
accountIdnumber是系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。
optionsStartOptions是启动Ability所携带的参数。
callbackAsyncCallback<void>是启动Ability的回调函数。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;
    let options: StartOptions = {
      windowMode: 0
    };

    try {
      this.context.startAbilityWithAccount(want, accountId, options, (error: BusinessError) => {
        if (error.code) {
          // 处理业务逻辑错误
          console.error('startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}');
          return;
        }
        // 执行正常业务
        console.log('startAbilityWithAccount succeed');
      });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.startAbilityWithAccount

startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise<void>;

根据account启动Ability（Promise形式）。

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

需要权限：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
accountIdnumber是系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。。
optionsStartOptions否启动Ability所携带的参数。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;
    let options: StartOptions = {
      windowMode: 0
    };

    try {
      this.context.startAbilityWithAccount(want, accountId, options)
        .then((data: void) => {
          // 执行正常业务
          console.log('startAbilityWithAccount succeed');
        })
        .catch((error: BusinessError) => {
          // 处理业务逻辑错误
          console.error('startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}');
        });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.startServiceExtensionAbility

startServiceExtensionAbility(want: Want, callback: AsyncCallback<void>): void;

启动一个新的ServiceExtensionAbility（callback形式）。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
callbackAsyncCallback<void>是启动Ability的回调函数。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

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

ServiceExtensionContext.startServiceExtensionAbility

startServiceExtensionAbility(want: Want): Promise<void>;

启动一个新的ServiceExtensionAbility（Promise形式）。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

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

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback<void>): void;

启动一个新的ServiceExtensionAbility（callback形式）。

说明：

当accountId为当前用户时，不需要校验该权限。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
accountIdnumber是系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。
callbackAsyncCallback<void>是启动Ability的回调函数。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

    try {
      this.context.startServiceExtensionAbilityWithAccount(want, accountId, (error: BusinessError) => {
        if (error.code) {
          // 处理业务逻辑错误
          console.error('startServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}');
          return;
        }
        // 执行正常业务
        console.log('startServiceExtensionAbilityWithAccount succeed');
      });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

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

启动一个新的ServiceExtensionAbility（Promise形式）。

说明：

当accountId为当前用户时，不需要校验该权限。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
accountIdnumber是系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

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

ServiceExtensionContext.startAbilityAsCaller10+

startAbilityAsCaller(want: Want, callback: AsyncCallback<void>): void;

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

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

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

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

错误码详细介绍请参考元能力子系统错误码

示例：

import extension from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';

export default class EntryAbility extends extension {
  onCreate(want: Want) {
    // want包含启动该应用的Caller信息
    let localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    // 使用启动方的Caller身份信息启动新Ability
    this.context.startAbilityAsCaller(localWant, (err) => {
      if (err && err.code != 0) {
        console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err));
      } else {
        console.log('startAbilityAsCaller success.');
      }
    })
  }
}

ServiceExtensionContext.startAbilityAsCaller10+

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

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

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

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

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

错误码详细介绍请参考元能力子系统错误码

示例：

import extension from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';

export default class EntryAbility extends extension {
  onCreate(want: Want) {
    // want包含启动该应用的Caller信息
    let localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    let option: StartOptions = {
      displayId: 0
    }

    // 使用启动方的Caller身份信息启动新Ability
    this.context.startAbilityAsCaller(localWant, option, (err) => {
      if (err && err.code != 0) {
        console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err));
      } else {
        console.log('startAbilityAsCaller success.');
      }
    })
  }
}

ServiceExtensionContext.startAbilityAsCaller10+

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

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

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
optionsStartOptions否启动Ability所携带的参数。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

错误码详细介绍请参考元能力子系统错误码

示例：

import extension from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';

export default class EntryAbility extends extension {
  onCreate(want: Want) {
    // want包含启动该应用的Caller信息
    let localWant: Want = want;
    localWant.bundleName = 'com.example.demo';
    localWant.moduleName = 'entry';
    localWant.abilityName = 'TestAbility';

    let option: StartOptions = {
      displayId: 0
    }

    // 使用启动方的Caller身份信息启动新Ability
    this.context.startAbilityAsCaller(localWant, option)
      .then(() => {
        console.log('startAbilityAsCaller success.');
      })
      .catch((err: BusinessError) => {
        console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err));
      })
  }
}

ServiceExtensionContext.stopServiceExtensionAbility

stopServiceExtensionAbility(want: Want, callback: AsyncCallback<void>): void;

停止同一应用程序内的服务（callback形式）。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是停止Ability的want信息。
callbackAsyncCallback<void>是停止Ability的回调函数。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000011The context does not exist.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

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

ServiceExtensionContext.stopServiceExtensionAbility

stopServiceExtensionAbility(want: Want): Promise<void>;

停止同一应用程序内的服务（Promise形式）。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是停止Ability的want信息。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000011The context does not exist.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

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

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback<void>): void;

使用帐户停止同一应用程序内的服务（callback形式）。

说明：

当accountId为当前用户时，不需要校验该权限。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是停止Ability的want信息。
accountIdnumber是需要停止的系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。
callbackAsyncCallback<void>是停止Ability的回调函数。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000011The context does not exist.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

    try {
      this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (error: BusinessError) => {
        if (error.code) {
          // 处理业务逻辑错误
          console.error('stopServiceExtensionAbilityWithAccount failed, error.code: ${error.code, error.message: ${error.message}');
          return;
        }
        // 执行正常业务
        console.log('stopServiceExtensionAbilityWithAccount succeed');
      });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

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

使用帐户停止同一应用程序内的服务（Promise形式）。

说明：

当accountId为当前用户时，不需要校验该权限。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是停止Ability的want信息。
accountIdnumber是需要停止的系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000011The context does not exist.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;

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

ServiceExtensionContext.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void;

停止Ability自身。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
callbackAsyncCallback<void>是回调函数，返回接口调用是否成功的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    this.context.terminateSelf((error: BusinessError) => {
      if (error.code) {
        // 处理业务逻辑错误
        console.error('terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}');
        return;
      }
      // 执行正常业务
      console.log('terminateSelf succeed');
    });
  }
}

ServiceExtensionContext.terminateSelf

terminateSelf(): Promise<void>;

停止ability自身。通过Promise返回结果。

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

系统API: 此接口为系统接口，三方应用不支持调用。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    this.context.terminateSelf().then(() => {
      // 执行正常业务
      console.log('terminateSelf succeed');
    }).catch((error: BusinessError) => {
      // 处理业务逻辑错误
      console.error('terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}');
    });
  }
}

ServiceExtensionContext.connectServiceExtensionAbility

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

将一个Ability与服务类型的Ability绑定。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。
optionsConnectOptions是ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。

返回值：

类型说明
number返回一个number，后续根据这个number去断开连接。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16000011The context does not exist.
16000050Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import rpc from '@ohos.rpc';
import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

let commRemote: rpc.IRemoteObject; // 断开连接时需要释放
class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapp',
      abilityName: 'MyAbility'
    };
    let options: common.ConnectOptions = {
      onConnect(elementName, remote) {
        commRemote = remote;
        console.log('----------- onConnect -----------');
      },
      onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
      onFailed(code) { console.error('----------- onFailed -----------') }
    };
    let connection: number;
    try {
      connection = this.context.connectServiceExtensionAbility(want, options);
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.connectServiceExtensionAbilityWithAccount

connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number;

使用AbilityInfo.AbilityType.SERVICE模板和account将当前能力连接到一个能力。

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
accountIdnumber是系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。
optionsConnectOptions是远端对象实例。

返回值：

类型说明
number返回Ability连接的结果code。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16000011The context does not exist.
16000050Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import rpc from '@ohos.rpc';
import common from '@ohos.app.ability.common';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

let commRemote: rpc.IRemoteObject; // 断开连接时需要释放
class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;
    let options: common.ConnectOptions = {
      onConnect(elementName, remote) {
        commRemote = remote;
        console.log('----------- onConnect -----------');
      },
      onDisconnect(elementName) { console.log('----------- onDisconnect -----------'); },
      onFailed(code) { console.log('----------- onFailed -----------'); }
    };
    let connection: number;
    try {
      connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options);
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.disconnectServiceExtensionAbility

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

将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
connectionnumber是在connectServiceExtensionAbility中返回的number。
callbackAsyncCallback<void>是回调函数，返回接口调用是否成功的结果。

错误码：

错误码ID错误信息
16000011The context does not exist.
16000050Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import rpc from '@ohos.rpc';
import { BusinessError } from '@ohos.base';

let commRemote: rpc.IRemoteObject; // 断开连接时需要释放
class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    // connection为connectServiceExtensionAbility中的返回值
    let connection = 1;
    try {
      this.context.disconnectServiceExtensionAbility(connection, (error: BusinessError) => {
        commRemote = null;
        if (error.code) {
          // 处理业务逻辑错误
          console.error('disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}');
          return;
        }
        // 执行正常业务
        console.log('disconnectServiceExtensionAbility succeed');
      });
    } catch (paramError) {
      commRemote = null;
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number): Promise<void>;

将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空(Promise形式返回结果)。

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
connectionnumber是在connectServiceExtensionAbility中返回的number。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

错误码ID错误信息
16000011The context does not exist.
16000050Internal error.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import rpc from '@ohos.rpc';
import { BusinessError } from '@ohos.base';

let commRemote: rpc.IRemoteObject; // 断开连接时需要释放
class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    // connection为connectServiceExtensionAbility中的返回值
    let connection = 1;
    try {
      this.context.disconnectServiceExtensionAbility(connection)
        .then(() => {
          commRemote = null;
          // 执行正常业务
          console.log('disconnectServiceExtensionAbility succeed');
        })
        .catch((error: BusinessError) => {
          commRemote = null;
          // 处理业务逻辑错误
          console.error('disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}');
        });
    } catch (paramError) {
      commRemote = null;
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.startAbilityByCall

startAbilityByCall(want: Want): Promise<Caller>;

启动指定Ability至前台或后台，同时获取其Caller通信接口，调用方可使用Caller与被启动的Ability进行通信。

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 同设备与跨设备场景下，该接口的使用规则存在差异，详见：组件启动规则（Stage模型）

需要权限: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是传入需要启动的Ability的信息，包含abilityName、moduleName、bundleName、deviceId(可选)、parameters(可选)，其中deviceId缺省或为空表示启动本地Ability，parameters缺省或为空表示后台启动Ability。

返回值：

类型说明
Promise<Caller>获取要通讯的caller对象。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005Static permission denied. The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

后台启动：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let caller: Caller;

    // 后台启动Ability，不配置parameters
    let wantBackground: Want = {
      bundleName: 'com.example.myservice',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: ''
    };

    try {
      this.context.startAbilityByCall(wantBackground)
        .then((obj: Caller) => {
          // 执行正常业务
          caller = obj;
          console.log('startAbilityByCall succeed');
        }).catch((error: BusinessError) => {
        // 处理业务逻辑错误
        console.error('startAbilityByCall failed, error.code: ${error.code}, error.message: ${error.message}');
      });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

前台启动：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let caller: Caller;

    // 前台启动Ability，将parameters中的'ohos.aafwk.param.callAbilityToForeground'配置为true
    let wantForeground: Want = {
      bundleName: 'com.example.myservice',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: '',
      parameters: {
        'ohos.aafwk.param.callAbilityToForeground': true
      }
    };

    try {
      this.context.startAbilityByCall(wantForeground)
        .then((obj: Caller) => {
          // 执行正常业务
          caller = obj;
          console.log('startAbilityByCall succeed');
        }).catch((error: BusinessError) => {
        // 处理业务逻辑错误
        console.error('startAbilityByCall failed, error.code: ${error.code}, error.message: ${error.message}');
      });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

ServiceExtensionContext.startRecentAbility

startRecentAbility(want: Want, callback: AsyncCallback<void>): void;

启动一个指定的Ability，如果这个Ability有多个实例，将拉起最近启动的那个实例。启动结果以callback的形式返回开发者。

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是需要启动Ability的want信息。
callbackAsyncCallback<void>是指定的回调函数的结果。

错误码：

以下错误码的详细介绍请参见元能力子系统错误码。

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

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

ServiceExtensionContext.startRecentAbility

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

启动一个指定的Ability，如果这个Ability有多个实例，将拉起最近启动的那个实例。启动结果以callback的形式返回开发者。 当开发者需要携带启动参数时可以选择此API。

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是需要启动Ability的want信息。
optionsStartOptions是启动Ability所携带的参数。
callbackAsyncCallback<void>是指定的回调函数的结果。

错误码：

以下错误码的详细介绍请参见元能力子系统错误码。

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      windowMode: 0
    };

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

ServiceExtensionContext.startRecentAbility

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

启动一个指定的Ability，如果这个Ability有多个实例，将拉起最近启动的那个实例。 当开发者期望启动结果以Promise形式返回时可以选择此API。

使用规则：

  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 组件启动规则详见：组件启动规则（Stage模型）

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

系统API: 此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是需要启动Ability的want信息。
optionsStartOptions否启动Ability所携带的参数。

错误码：

以下错误码的详细介绍请参见元能力子系统错误码。

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      windowMode: 0,
    };

    try {
      this.context.startRecentAbility(want, options)
        .then(() => {
          // 执行正常业务
          console.info('startRecentAbility succeed');
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          console.error(`startRecentAbility 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(`startRecentAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

ServiceExtensionContext.startAbilityByCallWithAccount10+

startAbilityByCallWithAccount(want: Want, accountId: number): Promise<Caller>;

根据accountId对指定的Ability进行call调用，并且可以使用返回的Caller通信接口与被调用方进行通信。

使用规则：

  • 跨用户场景下，Call调用目标Ability时，调用方应用需同时申请与权限ohos.permission.ABILITY_BACKGROUND_COMMUNICATIONohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS
  • 调用方应用位于后台时，使用该接口启动Ability需申请权限ohos.permission.START_ABILITIES_FROM_BACKGROUND
  • 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请权限ohos.permission.START_INVISIBLE_ABILITY
  • 同设备与跨设备场景下，该接口的使用规则存在差异，详见：组件启动规则（Stage模型）

需要权限: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION, ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS

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

系统API：此接口为系统接口，三方应用不支持调用。

参数：

参数名类型必填说明
wantWant是传入需要启动的Ability的信息，包含abilityName、moduleName、bundleName、deviceId(可选)、parameters(可选)，其中deviceId缺省或为空表示启动本地Ability，parameters缺省或为空表示后台启动Ability。
accountIdnumber是系统帐号的帐号ID，-1表示当前活动用户，详情参考getCreatedOsAccountsCount。

返回值：

类型说明
Promise<Caller>获取要通讯的caller对象。

错误码：

错误码ID错误信息
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005Static permission denied. The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16200001The caller has been released.

以上错误码详细介绍请参考元能力子系统错误码。

示例：

import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import StartOptions from '@ohos.app.ability.StartOptions';
import { BusinessError } from '@ohos.base';

class EntryAbility extends ServiceExtensionAbility {
  onCreate() {
    let caller: Caller;
    // 系统账号的账号ID, -1表示当前激活用户
    let accountId = -1;
    // 指定启动的Ability
    let want: Want = {
      bundleName: 'com.acts.actscalleeabilityrely',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: '',
      parameters: {
        // 'ohos.aafwk.param.callAbilityToForeground' 值设置为true时为前台启动, 设置false或不设置为后台启动
        'ohos.aafwk.param.callAbilityToForeground': true
      }
    };

    try {
      this.context.startAbilityByCallWithAccount(want, accountId)
        .then((obj: Caller) => {
          // 执行正常业务
          caller = obj;
          console.log('startAbilityByCallWithAccount succeed');
        }).catch((error: BusinessError) => {
        // 处理业务逻辑错误
        console.error('startAbilityByCallWithAccount failed, error.code: ${error.code}, error.message: ${error.message}');
      });
    } catch (paramError) {
      // 处理入参错误异常
      console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
    }
  }
}

最后

有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以有一份实用的鸿蒙（HarmonyOS NEXT）资料用来跟着学习是非常有必要的。 

这份鸿蒙（HarmonyOS NEXT）资料包含了鸿蒙开发必掌握的核心知识要点，内容包含了（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、Harmony南向开发、鸿蒙项目实战等等）鸿蒙（HarmonyOS NEXT）技术知识点。

希望这一份鸿蒙学习资料能够给大家带来帮助，有需要的小伙伴自行领取，限时开源，先到先得~无套路领取！！

获取这份完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS学习资料

鸿蒙（HarmonyOS NEXT）最新学习路线

  •  HarmonOS基础技能

  • HarmonOS就业必备技能 
  •  HarmonOS多媒体技术

  • 鸿蒙NaPi组件进阶

  • HarmonOS高级技能

  • 初识HarmonOS内核 
  • 实战就业级设备开发

有了路线图，怎么能没有学习资料呢，小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙（OpenHarmony ）学习手册（共计1236页）与鸿蒙（OpenHarmony ）开发入门教学视频，内容包含：ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。

获取以上完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS学习资料

《鸿蒙 (OpenHarmony)开发入门教学视频》

《鸿蒙生态应用开发V2.0白皮书》

图片

《鸿蒙 (OpenHarmony)开发基础到实战手册》

OpenHarmony北向、南向开发环境搭建

图片

 《鸿蒙开发基础》

  • ArkTS语言
  • 安装DevEco Studio
  • 运用你的第一个ArkTS应用
  • ArkUI声明式UI开发
  • .……

图片

 《鸿蒙开发进阶》

  • Stage模型入门
  • 网络管理
  • 数据管理
  • 电话服务
  • 分布式应用开发
  • 通知与窗口管理
  • 多媒体技术
  • 安全技能
  • 任务管理
  • WebGL
  • 国际化开发
  • 应用测试
  • DFX面向未来设计
  • 鸿蒙系统移植和裁剪定制
  • ……

图片

《鸿蒙进阶实战》

  • ArkTS实践
  • UIAbility应用
  • 网络案例
  • ……

图片

 获取以上完整鸿蒙HarmonyOS学习资料，请点击→纯血版全套鸿蒙HarmonyOS学习资料

总结

总的来说，华为鸿蒙不再兼容安卓，对中年程序员来说是一个挑战，也是一个机会。只有积极应对变化，不断学习和提升自己，他们才能在这个变革的时代中立于不败之地。

蜀道衫QAQ
关注
  • 17
    点赞
  • 踩
  • 11
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
HarmonyOS云开发基础认证自刷题库
09-13
包括：Serverless基础、快速构建用户认证系统、云函数入门指南、云数据库入门指南、云存储入门指南、HarmonyOS云开发、HarmonyOS云开发基础认证，内容为本人穷举法刷过的所有题目
HarmonyOS移动应用开发
04-07
通过该课程的学习，您将掌握HarmonyOS基本概念及原理、HarmonyOS技术架构、HarmonyOS应用开发流程、Ability与UI开发知识，具备HarmonyOS功能开发、调试与发布的能力，能够胜任HarmonyOS应用开发工程师岗位。
HarmonyOS实战开发：ServiceExtensionAbility
2401_84194030的博客
04-24 888
ServiceExtensionAbility是SERVICE类型的ExtensionAbility组件.........
HarmonyOS实战开发：ExtensionContext
2401_84194030的博客
05-22 618
ExtensionContext是Extension的上下文环境，继承自Context。
HarmonyOS实战开发：应用上下文Context
2401_84194030的博客
04-26 676
Context是应用中对象的上下文.........
HarmonyOS实战开发：UIAbility组件间交互（设备内）
2401_84194030的博客
04-23 991
UIAbility是系统调度的最小单元.........
鸿蒙HarmonyOS实战-Stage模型（应用上下文Context）_鸿蒙 page 里获取 context
2401_84160361的博客
04-18 901
ApplicationContext在基类Context的基础上提供了订阅应用内Ability的生命周期的变化、订阅系统内存变化和订阅应用内系统环境的变化的能力，在UIAbility、ExtensionAbility、AbilityStage中均可以获取。通过模块上下文对象，可以获取到模块的配置信息、上下文等相关的资源。if (this.context.area === 1) { // 获取area。if (this.context.area === 0) { // 获取area。
HarmonyOS实战开发-Stage模型、Stage和FA模型的区别
m0_70749039的博客
04-13 890
Stage模型 的设计，主要是为了解决FA模型无法解决的开发场景问题，方便开发者更加方便地开发出分布式环境下的复杂应用。
HarmonyOS实战开发-如何实现一个仿桌面应用。
2401_82546228的博客
04-08 647
本示例实现了一个简单桌面应用，实现了以下几点功能：
HarmonyOS实战开发-如何实现跨任务链返回功能。
2401_82546228的博客
04-08 763
本示例为一个仿桌面应用测试demo，使用@ohos.app.ability.ServiceExtensionAbility接口中ServiceExtensionContext类的startRecentAbility能力（系统能力：SystemCapability.Ability.AbilityRuntime.Core），实现了跨任务链返回的功能。
鸿蒙 HarmonyOS应用开发之API：Context_鸿蒙os getcontext(4)
AUZKAY的博客
04-11 684
大，这里只是将部分目录大纲截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新**
HCIA-HarmonyOS应用开发工程师 V2.0 模拟考试
10-13
在“HCIA-HarmonyOS应用开发工程师 V2.0 模拟考试”中，我们可以学习到关于HarmonyOS应用开发的关键知识点。这个初级认证主要涉及HarmonyOS的基础架构、组件使用、页面跳转、权限管理、应用结构以及开发工具的使用。...
Harmony OS物联网应用开发实战
10-02
Harmony OS物联网应用开发实战
华为harmonyos公测-HarmonyOS-examples:鸿蒙示例
07-01
HarmonyOS应用开发的各种示例，项目及开发教程汇总，帮助初学者快速掌握HarmonyOS应用开发。 没有人能熄灭满天的星光，每一位开发者，让我们在此汇集，一起点亮整个星空。 记得给仓库点个 Star 哟:winking_face: 一...
【HarmonyOS NEXT】鸿蒙App开发抓包指导-以Charles工具为例
wu1004019946的博客
06-12 629
三、 PC端Charles导出证书，点击 Help--->SSL Proxying--->Install Charles Root Certificate on a Mobile Device or Remote Browser。点击 Help--->SSL Proxying--->Install Charles Root Certificate--->安装证书--->选择证书存储路径为：受信任的根证书颁发机构。1) 通过手机浏览器下载charles提供的网址下载证书，在浏览器下载之后要另存到下载目录。
HarmonyOS角落里的知识：一杯冰美式的时间 -- DragView
m0_64422261的博客
06-18 817
在学习API9的时候就写了一个DragView,用于展示某个页面的悬浮可拖动的入口，特意丰富了许多的功能，今天分享给大家～。Demo基于API11。
HarmonyOS角落里的知识：一杯冰美式的时间 -- 之打字机
最新发布
m0_64422261的博客
06-18 743
模拟编辑器或者模拟输入框中文字啪啦啪啦输入的效果，往往能够吸引人们的眼球，让用户的注意力聚焦在输入的内容上，本文将和大家探讨打字机效果的实现方式以及应用。Demo基于API12。
HarmonyOS(33) @LocalStorageProp使用指南
菜鸟博客
06-12 429
HarmonyOS @LocalStorageProp使用指南
harmonyos iot设备开发实战 pdf
05-13
华为发布了一本名为《HarmonyOS IoT设备开发实战》的PDF文档。这个文档主要是介绍了如何使用华为自己研发的鸿蒙操作系统来开发物联网设备。作为一个全新的操作系统，HarmonyOS可以在不同的设备之间进行无缝连接和...

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值