ServiceExtensionContext

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

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

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块接口仅可在Stage模型下使用。

使用说明

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

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

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

1
2
3
4
5
6
7
8
9

ServiceExtensionContext.startAbility

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

启动Ability。

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

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

参数：

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

错误码：

错误码ID	错误信息
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.
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.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  bundleName: 'com.example.myapp',
  abilityName: 'MyAbility'
};

try {
  this.context.startAbility(want, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

ServiceExtensionContext.startAbility

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

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

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

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

参数：

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

返回值：

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

错误码：

错误码ID	错误信息
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.
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.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  bundleName: 'com.example.myapp',
  abilityName: 'MyAbility'
};
let options = {
	windowMode: 0,
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

ServiceExtensionContext.startAbility

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

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

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

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

参数：

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

错误码：

错误码ID	错误信息
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.
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.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let options = {
  windowMode: 0
};

try {
  this.context.startAbility(want, options, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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模型）

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

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

参数：

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

错误码：

错误码ID	错误信息
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.
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.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let accountId = 100;

try {
  this.context.startAbilityWithAccount(want, accountId, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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模型）

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

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

参数：

参数名	类型	必填	说明
want	Want	是	启动Ability的want信息。
accountId	number	是	系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。
options	StartOptions	否	启动Ability所携带的参数。
callback	AsyncCallback<void>	是	启动Ability的回调函数。

错误码：

错误码ID	错误信息
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.
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.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let accountId = 100;
let options = {
  windowMode: 0
};

try {
  this.context.startAbilityWithAccount(want, accountId, options, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

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模型）

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

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

参数：

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

返回值：

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

错误码：

错误码ID	错误信息
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.
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.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let accountId = 100;
let options = {
  windowMode: 0
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

ServiceExtensionContext.startServiceExtensionAbility

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

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

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

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

参数：

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

错误码：

错误码ID	错误信息
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
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.
16200001	The caller has been released.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};

try {
  this.context.startServiceExtensionAbility(want, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

ServiceExtensionContext.startServiceExtensionAbility

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

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

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

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

参数：

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

返回值：

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

错误码：

错误码ID	错误信息
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
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.
16200001	The caller has been released.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

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

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

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS，当accountId为当前用户时，不需要校验该权限。

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

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

参数：

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

错误码：

错误码ID	错误信息
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
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.
16200001	The caller has been released.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let accountId = 100;

try {
  this.context.startServiceExtensionAbilityWithAccount(want, accountId, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

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

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

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS，当accountId为当前用户时，不需要校验该权限。

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

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

参数：

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

返回值：

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

错误码：

错误码ID	错误信息
16000001	The specified ability does not exist.
16000002	Incorrect ability type.
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.
16200001	The caller has been released.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let accountId = 100;

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

ServiceExtensionContext.stopServiceExtensionAbility

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

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

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

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

参数：

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

错误码：

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

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};

try {
  this.context.stopServiceExtensionAbility(want, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

ServiceExtensionContext.stopServiceExtensionAbility

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

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

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

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

参数：

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

返回值：

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

错误码：

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

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

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

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

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS，当accountId为当前用户时，不需要校验该权限。

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

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

参数：

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

错误码：

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

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let accountId = 100;

try {
  this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

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

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

需要权限: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS，当accountId为当前用户时，不需要校验该权限。

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

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

参数：

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

返回值：

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

错误码：

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

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let accountId = 100;

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

ServiceExtensionContext.terminateSelf

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

停止Ability自身。

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

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

参数：

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

错误码：

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

以上错误码详细介绍请参考errcode-ability。

示例：

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

1
2
3
4
5
6
7
8
9

ServiceExtensionContext.terminateSelf

terminateSelf(): Promise<void>;

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

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

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

返回值：

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

错误码：

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

以上错误码详细介绍请参考errcode-ability。

示例：

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

1
2
3
4
5
6
7

ServiceExtensionContext.connectServiceExtensionAbility

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

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

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

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

参数：

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

返回值：

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

错误码：

错误码ID	错误信息
16000001	Input error. The specified ability name does not exist.
16000005	The specified process does not have the permission.
16000011	The context does not exist.
16000050	Internal Error.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  bundleName: 'com.example.myapp',
  abilityName: 'MyAbility'
};
let options = {
  onConnect(elementName, remote) { 
    commRemote = remote;
    console.log('----------- onConnect -----------'); 
  },
  onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
  onFailed(code) { console.error('----------- onFailed -----------') }
};

let connection = null;
try {
  connection = this.context.connectServiceExtensionAbility(want, options);
} catch (paramError) {
  // 处理入参错误异常
  console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

ServiceExtensionContext.connectServiceExtensionAbilityWithAccount

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

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

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

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

参数：

参数名	类型	必填	说明
want	Want	是	启动Ability的want信息。
accountId	number	是	系统帐号的帐号ID，详情参考getCreatedOsAccountsCount。
options	ConnectOptions	否	远端对象实例。

返回值：

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

错误码：

错误码ID	错误信息
16000001	Input error. The specified ability name does not exist.
16000005	The specified process does not have the permission.
16000011	The context does not exist.
16000050	Internal Error.

以上错误码详细介绍请参考errcode-ability。

示例：

let want = {
  deviceId: '',
  bundleName: 'com.example.myapplication',
  abilityName: 'EntryAbility'
};
let accountId = 100;
let options = {
  onConnect(elementName, remote) { 
    commRemote = remote;
    console.log('----------- onConnect -----------');
  },
  onDisconnect(elementName) { console.log('----------- onDisconnect -----------'); },
  onFailed(code) { console.log('----------- onFailed -----------'); }
};

let connection = null;
try {
  connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options);
} catch (paramError) {
  // 处理入参错误异常
  console.error('error.code: ${paramError.code}, error.message: ${paramError.message}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

ServiceExtensionContext.disconnectServiceExtensionAbility

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

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

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

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

参数：

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

错误码：

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

以上错误码详细介绍请参考errcode-ability。

示例：

// connection为connectServiceExtensionAbility中的返回值
let connection = 1;

try {
  this.context.disconnectServiceExtensionAbility(connection, (error) => {
    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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

ServiceExtensionContext.disconnectServiceExtensionAbility

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

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

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

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

参数：

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

返回值：

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

错误码：

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

以上错误码详细介绍请参考errcode-ability。

示例：

// connection为connectServiceExtensionAbility中的返回值
let connection = 1;

try {
  this.context.disconnectServiceExtensionAbility(connection)
    .then((data) => {
      commRemote = null;
      // 执行正常业务
      console.log('disconnectServiceExtensionAbility succeed');
    })
    .catch((error) => {
      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}');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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模型）

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

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

参数：

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

返回值：

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

错误码：

错误码ID	错误信息
16000001	Input error. The specified ability name does not exist.
16000002	Incorrect ability type.
16000004	Visibility verification failed.
16000005	Static permission denied. The specified process does not have the permission.
16000006	Cross-user operations are not allowed.
16000008	Crowdtest App Expiration.
16000011	The context does not exist.
16000050	Internal Error.
16200001	The caller has been released.

以上错误码详细介绍请参考errcode-ability。

示例：

后台启动：

let caller;

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

前台启动：

let caller;

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

ServiceExtensionContext

ServiceExtensionContext

使用说明

ServiceExtensionContext.startAbility

ServiceExtensionContext.startAbility

ServiceExtensionContext.startAbility

ServiceExtensionContext.startAbilityWithAccount

ServiceExtensionContext.startAbilityWithAccount

ServiceExtensionContext.startAbilityWithAccount

ServiceExtensionContext.startServiceExtensionAbility

ServiceExtensionContext.startServiceExtensionAbility

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

ServiceExtensionContext.startServiceExtensionAbilityWithAccount

ServiceExtensionContext.stopServiceExtensionAbility

ServiceExtensionContext.stopServiceExtensionAbility

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

ServiceExtensionContext.stopServiceExtensionAbilityWithAccount

ServiceExtensionContext.terminateSelf

ServiceExtensionContext.terminateSelf

ServiceExtensionContext.connectServiceExtensionAbility

ServiceExtensionContext.connectServiceExtensionAbilityWithAccount

ServiceExtensionContext.disconnectServiceExtensionAbility

ServiceExtensionContext.disconnectServiceExtensionAbility

ServiceExtensionContext.startAbilityByCall

Description