UIAbilityContext


UIAbilityContext

UIAbilityContext是UIAbility的上下文环境,继承自Context,提供UIAbility的相关配置信息以及操作UIAbility和ServiceExtensionAbility的方法,如启动UIAbility,停止当前UIAbilityContext所属的UIAbility,启动、停止、连接、断开连接ServiceExtensionAbility等。

说明:

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

属性

系统能力:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core

名称 类型 可读 可写 说明
abilityInfo AbilityInfo UIAbility的相关信息。
currentHapModuleInfo HapModuleInfo 当前HAP的信息。
config Configuration 与UIAbility相关的配置信息,如语言、颜色模式等。

关于示例代码的说明:

在本文档的示例中,通过this.context来获取UIAbilityContext,其中this代表继承自UIAbilityUIAbility实例。如需要在页面中使用UIAbilityContext提供的能力,请参见获取UIAbility的上下文信息

UIAbilityContext.startAbility

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

启动Ability(callback形式)。

使用规则:

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
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 = {
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};

try {
this.context.startAbility(want, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startAbility succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`startAbility failed failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

UIAbilityContext.startAbility

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

启动Ability(callback形式)。

使用规则:

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

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

参数:

参数名 类型 必填 说明
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, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startAbility succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`startAbility failed failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

UIAbilityContext.startAbility

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

启动Ability(promise形式)。

使用规则:

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
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.myapplication',
abilityName: 'EntryAbility'
};
let options = {
windowMode: 0,
};

try {
this.context.startAbility(want, options)
  .then(() => {
    // 执行正常业务
    console.info('startAbility succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

UIAbilityContext.startAbilityForResult

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

启动一个Ability。Ability被启动后,有如下情况(callback形式):

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

使用规则:

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
callback AsyncCallback<AbilityResult> 执行结果回调函数。

错误码:

错误码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'
};

try {
this.context.startAbilityForResult(want, (err, result) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startAbilityForResult succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

UIAbilityContext.startAbilityForResult

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

启动一个Ability。Ability被启动后,有如下情况(callback形式):

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

使用规则:

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
options StartOptions 启动Ability所携带的参数。
callback AsyncCallback<AbilityResult> 执行结果回调函数。

错误码:

错误码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.startAbilityForResult(want, options, (err, result) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startAbilityForResult succeed');
});
} catch (paramError) {
// 处理入参错误异常
console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

UIAbilityContext.startAbilityForResult

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

启动一个Ability。Ability被启动后,有如下情况(promise形式):

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

使用规则:

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
options StartOptions 启动Ability所携带的参数。

返回值:

类型 说明
Promise<AbilityResult> 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.myapplication',
abilityName: 'EntryAbility'
};
let options = {
windowMode: 0,
};

try {
this.context.startAbilityForResult(want, options)
  .then((result) => {
    // 执行正常业务
    console.info('startAbilityForResult succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

UIAbilityContext.startAbilityForResultWithAccount

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

启动一个Ability并在该Ability销毁时返回执行结果(callback形式)。

使用规则:

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

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

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
callback AsyncCallback<AbilityResult> 启动Ability的回调函数,返回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.startAbilityForResultWithAccount(want, accountId, (err, result) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startAbilityForResultWithAccount succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

UIAbilityContext.startAbilityForResultWithAccount

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

启动一个Ability并在该Ability销毁时返回执行结果(callback形式)。

使用规则:

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

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

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
options StartOptions 启动Ability所携带的参数。
callback AsyncCallback<void> 启动Ability后,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.startAbilityForResultWithAccount(want, accountId, options, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startAbilityForResultWithAccount succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.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

UIAbilityContext.startAbilityForResultWithAccount

startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise<AbilityResult>;

启动一个Ability并在该Ability销毁时返回执行结果(promise形式)。

使用规则:

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

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

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

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

参数:

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

返回值:

类型 说明
Promise<AbilityResult> Ability被销毁时的回调函数,包含AbilityResult参数。

错误码:

错误码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.startAbilityForResultWithAccount(want, accountId, options)
  .then((result) => {
    // 执行正常业务
    console.info('startAbilityForResultWithAccount succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityForResultWithAccount failed, code is ${err.code}, message is ${err.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

UIAbilityContext.startServiceExtensionAbility

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

启动一个新的ServiceExtensionAbility(callback形式)。

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

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

参数:

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

错误码:

错误码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: 'ServiceExtensionAbility'
};

try {
this.context.startServiceExtensionAbility(want)
  .then(() => {
    // 执行正常业务
    console.info('startServiceExtensionAbility succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

UIAbilityContext.startServiceExtensionAbility

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

启动一个新的ServiceExtensionAbility(Promise形式)。

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

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

参数:

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

错误码:

错误码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: 'ServiceExtensionAbility'
};

try {
this.context.startServiceExtensionAbility(want)
  .then(() => {
    // 执行正常业务
    console.info('startServiceExtensionAbility succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (paramError) {
// 处理入参错误异常
console.error(`startServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

UIAbilityContext.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 启动ServiceExtensionAbility的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
callback AsyncCallback<void> 启动ServiceExtensionAbility的回调函数。

错误码:

错误码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: 'ServiceExtensionAbility'
};
let accountId = 100;

try {
this.context.startServiceExtensionAbilityWithAccount(want, accountId, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startServiceExtensionAbilityWithAccount succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

UIAbilityContext.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

错误码:

错误码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: 'ServiceExtensionAbility'
};
let accountId = 100;

try {
this.context.startServiceExtensionAbilityWithAccount(want, accountId)
  .then(() => {
    // 执行正常业务
    console.info('startServiceExtensionAbilityWithAccount succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`startServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

UIAbilityContext.stopServiceExtensionAbility

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

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

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

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

参数:

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

错误码:

错误码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: 'ServiceExtensionAbility'
};

try {
this.context.stopServiceExtensionAbility(want, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('stopServiceExtensionAbility succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

UIAbilityContext.stopServiceExtensionAbility

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

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

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

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

参数:

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

错误码:

错误码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: 'ServiceExtensionAbility'
};

try {
this.context.stopServiceExtensionAbility(want)
  .then(() => {
    // 执行正常业务
    console.info('stopServiceExtensionAbility succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`stopServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

UIAbilityContext.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 停止ServiceExtensionAbility的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
callback AsyncCallback<void> 停止ServiceExtensionAbility的回调函数。

错误码:

错误码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: 'ServiceExtensionAbility'
};
let accountId = 100;

try {
this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('stopServiceExtensionAbilityWithAccount succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

UIAbilityContext.stopServiceExtensionAbilityWithAccount

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

停止同一应用程序内指定账户的服务(Promise形式)。

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

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

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

参数:

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

错误码:

错误码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: 'ServiceExtensionAbility'
};
let accountId = 100;

try {
this.context.stopServiceExtensionAbilityWithAccount(want, accountId)
  .then(() => {
    // 执行正常业务
    console.info('stopServiceExtensionAbilityWithAccount succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`stopServiceExtensionAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

UIAbilityContext.terminateSelf

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

停止Ability自身(callback形式)。

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

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 停止Ability自身的回调函数。

错误码:

错误码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

示例:

try {
  this.context.terminateSelf((err) => {
    if (err.code) {
      // 处理业务逻辑错误
      console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
      return;
    }
    // 执行正常业务
    console.info('terminateSelf succeed');
  });
} catch (err) {
  // 捕获同步的参数错误
  console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

UIAbilityContext.terminateSelf

terminateSelf(): Promise<void>;

停止Ability自身(promise形式)。

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

返回值:

类型 说明
Promise<void> 停止Ability自身的回调函数。

错误码:

错误码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

示例:

try {
  this.context.terminateSelf()
    .then(() => {
      // 执行正常业务
      console.info('terminateSelf succeed');
    })
    .catch((err) => {
      // 处理业务逻辑错误
      console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
    });
} catch (error) {
  // 捕获同步的参数错误
  console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

UIAbilityContext.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void;

停止当前的Ability。如果该Ability是通过调用startAbilityForResult接口被拉起的,调用terminateSelfWithResult接口时会将结果返回给调用者,如果该Ability不是通过调用startAbilityForResult接口被拉起的,调用terminateSelfWithResult接口时不会有结果返回给调用者(callback形式)。

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

参数:

参数名 类型 必填 说明
parameter AbilityResult 返回给调用startAbilityForResult 接口调用方的相关信息。
callback AsyncCallback<void> callback形式返回停止结果。

错误码:

错误码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

示例:

let want = {
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let resultCode = 100;
// 返回给接口调用方AbilityResult信息
let abilityResult = {
want,
resultCode
};

try {
this.context.terminateSelfWithResult(abilityResult, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('terminateSelfWithResult succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.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

UIAbilityContext.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise<void>;

停止当前的Ability。如果该Ability是通过调用startAbilityForResult接口被拉起的,调用terminateSelfWithResult接口时会将结果返回给调用者,如果该Ability不是通过调用startAbilityForResult接口被拉起的,调用terminateSelfWithResult接口时不会有结果返回给调用者(promise形式)。

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

参数:

参数名 类型 必填 说明
parameter AbilityResult 返回给startAbilityForResult 调用方的信息。

返回值:

类型 说明
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

示例:

let want = {
bundleName: 'com.example.myapplication',
abilityName: 'EntryAbility'
};
let resultCode = 100;
// 返回给接口调用方AbilityResult信息
let abilityResult = {
want,
resultCode
};

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

UIAbilityContext.connectServiceExtensionAbility

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

将当前Ability连接到一个使用AbilityInfo.AbilityType.SERVICE模板的Ability。

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

参数:

参数名 类型 必填 说明
want Want 连接ServiceExtensionAbility的want信息。
options ConnectOptions 与ServiceExtensionAbility建立连接后回调函数的实例。

返回值:

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

错误码:

错误码ID 错误信息
16000001 The specified ability 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: 'ServiceExtensionAbility'
};
let options = {
onConnect(elementName, remote) {
  commRemote = remote;
  console.info('onConnect...')
},
onDisconnect(elementName) {
  console.info('onDisconnect...')
},
onFailed(code) {
  console.info('onFailed...')
}
};

let connection = null;
try {
connection = this.context.connectServiceExtensionAbility(want, options);
} catch (err) {
// 处理入参错误异常
console.error(`connectServiceExtensionAbility failed, code is ${err.code}, message is ${err.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

UIAbilityContext.connectServiceExtensionAbilityWithAccount

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

将当前Ability连接到一个使用AbilityInfo.AbilityType.SERVICE模板的指定account的Ability。

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

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
options ConnectOptions 与ServiceExtensionAbility建立连接后回调函数的实例。。

返回值:

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

错误码:

错误码ID 错误信息
16000001 The specified ability 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: 'ServiceExtensionAbility'
};
let accountId = 100;
let options = {
onConnect(elementName, remote) {
  commRemote = remote;
  console.info('onConnect...')
},
onDisconnect(elementName) {
  console.info('onDisconnect...')
},
onFailed(code) {
  console.info('onFailed...')
}
};

let connection = null;
try {
connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options);
} catch (err) {
// 处理入参错误异常
console.error(`connectServiceExtensionAbility failed, code is ${err.code}, message is ${err.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

UIAbilityContext.disconnectServiceExtensionAbility

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

断开与ServiceExtensionAbility的连接,断开连接之后需要将连接成功时返回的remote对象置空(promise形式)。

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

参数:

参数名 类型 必填 说明
connection number 连接的ServiceExtensionAbility的数字代码,即connectServiceExtensionAbility返回的connectionId。

返回值:

类型 说明
Promise<void> 返回执行结果。

错误码:

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

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

示例:

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

try {
this.context.disconnectServiceExtensionAbility(connection, (err) => {
  commRemote = null;
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('disconnectServiceExtensionAbility succeed');
});
} catch (err) {
commRemote = null;
// 处理入参错误异常
console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

UIAbilityContext.disconnectServiceExtensionAbility

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

断开与ServiceExtensionAbility的连接,断开连接之后需要将连接成功时返回的remote对象置空(callback形式)。

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

参数:

参数名 类型 必填 说明
connection number 连接的ServiceExtensionAbility的数字代码,即connectServiceExtensionAbility返回的connectionId。
callback AsyncCallback<void> callback形式返回断开连接的结果。

错误码:

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

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

示例:

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

try {
this.context.disconnectServiceExtensionAbility(connection, (err) => {
  commRemote = null;
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('disconnectServiceExtensionAbility succeed');
});
} catch (err) {
commRemote = null;
// 处理入参错误异常
console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

UIAbilityContext.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

参数:

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

返回值:

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

错误码:

错误码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.
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.myapplication',
moduleName: 'entry',
abilityName: 'EntryAbility',
deviceId: ''
};

try {
this.context.startAbilityByCall(wantBackground)
  .then((obj) => {
    // 执行正常业务
    caller = obj;
    console.info('startAbilityByCall succeed');
  }).catch((err) => {
  // 处理业务逻辑错误
  console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.message}`);
});
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.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.myapplication',
moduleName: 'entry',
abilityName: 'EntryAbility',
deviceId: '',
parameters: {
  'ohos.aafwk.param.callAbilityToForeground': true
}
};

try {
this.context.startAbilityByCall(wantForeground)
  .then((obj) => {
    // 执行正常业务
    caller = obj;
    console.info('startAbilityByCall succeed');
  }).catch((error) => {
  // 处理业务逻辑错误
  console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.message}`);
});
} catch (paramError) {
// 处理入参错误异常
console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.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

UIAbilityContext.startAbilityWithAccount

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

根据want和accountId启动Ability(callback形式)。

使用规则:

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

需要权限: 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.
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, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startAbilityWithAccount succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

UIAbilityContext.startAbilityWithAccount

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

根据want、accountId及startOptions启动Ability(callback形式)。

使用规则:

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

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

系统能力: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, (err) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('startAbilityWithAccount succeed');
});
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.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

UIAbilityContext.startAbilityWithAccount

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

根据want、accountId和startOptions启动Ability(Promise形式)。

使用规则:

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

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

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

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

参数:

参数名 类型 必填 说明
want Want 启动Ability的want信息。
accountId number 系统帐号的帐号ID,详情参考getCreatedOsAccountsCount
options StartOptions 启动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)
  .then(() => {
    // 执行正常业务
    console.info('startAbilityWithAccount succeed');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`startAbilityWithAccount failed, code is ${err.code}, message is ${err.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

UIAbilityContext.setMissionLabel

setMissionLabel(label: string, callback:AsyncCallback<void>): void;

设置UIAbility在任务中显示的名称(callback形式)。

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

参数:

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

错误码:

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

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

示例:

this.context.setMissionLabel('test', (result) => {
  console.info(`setMissionLabel: ${JSON.stringify(result)}`);
});
1
2
3

UIAbilityContext.setMissionLabel

setMissionLabel(label: string): Promise<void>;

设置UIAbility在任务中显示的名称(promise形式)。

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

参数:

参数名 类型 必填 说明
label string 显示名称。

返回值:

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

错误码:

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

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

示例:

this.context.setMissionLabel('test').then(() => {
  console.info('success');
}).catch((err) => {
  console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`);
});
1
2
3
4
5

UIAbilityContext.setMissionIcon

setMissionIcon(icon: image.PixelMap, callback:AsyncCallback<void>): void;

设置当前ability在任务中显示的图标, 图标大小最大为600M(callback形式)。

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

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

参数:

参数名 类型 必填 说明
icon image.PixelMap 在最近的任务中显示的ability图标。
callback AsyncCallback<void> 指定的回调函数的结果。

错误码:

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

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

示例:

import image from '@ohos.multimedia.image';

let imagePixelMap;
let color = new ArrayBuffer(0);
let initializationOptions = {
  size: {
    height: 100,
    width: 100
  }
};
image.createPixelMap(color, initializationOptions)
  .then((data) => {
    imagePixelMap = data;
  })
  .catch((err) => {
    console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`);
  });
this.context.setMissionIcon(imagePixelMap, (err) => {
  console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`);
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

UIAbilityContext.setMissionIcon

setMissionIcon(icon: image.PixelMap): Promise<void>;

设置当前ability在任务中显示的图标, 图标大小最大为600M(promise形式)。

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

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

参数:

参数名 类型 必填 说明
icon image.PixelMap 在最近的任务中显示的ability图标。

返回值:

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

错误码:

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

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

示例:

let imagePixelMap;
let color = new ArrayBuffer(0);
let initializationOptions = {
  size: {
    height: 100,
    width: 100
  }
};
image.createPixelMap(color, initializationOptions)
  .then((data) => {
    imagePixelMap = data;
  })
  .catch((err) => {
    console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`);
  });
this.context.setMissionIcon(imagePixelMap)
  .then(() => {
    console.info('setMissionIcon succeed');
  })
  .catch((err) => {
    console.error(`setMissionLabel failed, code is ${err.code}, message is ${err.message}`);
  });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

UIAbilityContext.restoreWindowStage

restoreWindowStage(localStorage: LocalStorage) : void;

恢复UIAbility中的WindowStage数据。

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

参数:

参数名 类型 必填 说明
localStorage image.LocalStorage 用于恢复window stage的存储数据。

错误码:

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

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

示例:

let storage = new LocalStorage();
this.context.restoreWindowStage(storage);
1
2

UIAbilityContext.isTerminating

isTerminating(): boolean;

查询UIAbility是否在terminating状态。

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

返回值:

类型 说明
bool true:ability当前处于terminating状态;false:不处于terminating状态。

错误码:

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

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

示例:

let isTerminating = this.context.isTerminating();
console.info(`ability state is ${isTerminating}`);
1
2

UIAbilityContext.requestDialogService

requestDialogService(want: Want, result: AsyncCallback<dialogRequest.RequestResult>): void;

启动一个支持模态弹框的ServiceExtensionAbility。ServiceExtensionAbility被启动后,应用弹出模态弹框,通过调用setRequestResult接口返回结果给调用者。

使用规则:

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

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

参数:

参数名 类型 必填 说明
want Want 启动ServiceExtensionAbility的want信息。
result AsyncCallback<dialogRequest.RequestResult> 执行结果回调函数。

错误码:

错误码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

示例:

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

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

try {
this.context.requestDialogService(want, (err, result) => {
  if (err.code) {
    // 处理业务逻辑错误
    console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`);
    return;
  }
  // 执行正常业务
  console.info('requestDialogService succeed, result = ${JSON.stringify(result)}');
});
} catch (err) {
// 处理入参错误异常
console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

UIAbilityContext.requestDialogService

requestDialogService(want: Want): Promise<dialogRequest.RequestResult>;

启动一个支持模态弹框的ServiceExtensionAbility。ServiceExtensionAbility被启动后,应用弹出模态弹框,通过调用setRequestResult接口返回结果给调用者(promise形式)。

使用规则:

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

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

参数:

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

返回值:

类型 说明
Promise<dialogRequest.RequestResult> 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

示例:

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

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

try {
this.context.requestDialogService(want)
  .then((result) => {
    // 执行正常业务
    console.info('requestDialogService succeed, result = ${JSON.stringify(result)}');
  })
  .catch((err) => {
    // 处理业务逻辑错误
    console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`);
  });
} catch (err) {
// 处理入参错误异常
console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21