• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# UIExtensionContext (系统接口)
2
3UIExtensionContext是[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)的上下文环境，继承自[ExtensionContext](js-apis-inner-application-extensionContext.md)，提供UIExtensionAbility的相关配置信息以及操作UIAbility的方法，如启动UIAbility等。
4
5> **说明：**
6>
7>  - 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>  - 本模块接口仅可在Stage模型下使用。
9>  - 本模块接口为系统接口。
10
11## 导入模块
12
13```ts
14import { common } from '@kit.AbilityKit';
15```
16
17## UIExtensionContext.startAbilityForResultAsCaller
18
19startAbilityForResultAsCaller(want: Want, options?: StartOptions): Promise<AbilityResult>
20
21使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用Promise异步回调。
22
23 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用方。
24 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。
25 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。
26
27> **说明：**
28>
29> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。
30
31**模型约束**：此接口仅可在Stage模型下使用。
32
33**系统接口**：此接口为系统接口。
34
35**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
36
37**参数：**
38
39| 参数名  | 类型                                                | 必填 | 说明                      |
40| ------- | --------------------------------------------------- | ---- | ------------------------- |
41| want    | [Want](js-apis-app-ability-want.md)                 | 是   | 启动Ability的want信息。   |
42| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否   | 启动Ability所携带的参数。 |
43
44**返回值：**
45
46| 类型                                                         | 说明                      |
47| ------------------------------------------------------------ | ------------------------- |
48| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise对象，返回Ability结果对象。 |
49
50**错误码：**
51
52以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
53
54| 错误码ID | 错误信息                                                |
55| -------- | ------------------------------------------------------- |
56| 401| Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
57| 16000001 | The specified ability does not exist.                   |
58| 16000004 | Failed to start the invisible ability.                      |
59| 16000050 | Internal error.                                         |
60| 16000073 | The app clone index is invalid. |
61
62**示例：**
63
64```ts
65import { UIExtensionAbility } from '@kit.AbilityKit';
66import { BusinessError } from '@kit.BasicServicesKit';
67
68export default class UIExtension extends UIExtensionAbility {
69  onForeground() {
70    this.context.startAbilityForResultAsCaller({
71      bundleName: 'com.example.startabilityforresultascaller',
72      abilityName: 'EntryAbility',
73      moduleName: 'entry'
74    }).then((data) => {
75      console.log('=======>startAbilityForResultAsCaller data Promise ======>' + JSON.stringify(data));
76    }).catch((error: BusinessError) => {
77      console.log('=======>startAbilityForResultAsCaller error.code Promise ======>' + error.code);
78    });
79  }
80}
81```
82
83## UIExtensionContext.setHostPageOverlayForbidden<sup>15+</sup>
84
85setHostPageOverlayForbidden(isForbidden: boolean) : void
86
87是否允许[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)拉起的页面被使用方的页面覆盖。
88
89> **说明：**
90>
91> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。
92>
93> 该接口需要在窗口创建之前调用。建议在[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)的[onCreate](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#uiextensionabilityoncreate)生命周期内调用。
94
95**模型约束**：此接口仅可在Stage模型下使用。
96
97**系统接口**：此接口为系统接口。
98
99**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
100
101**参数**：
102
103| 参数名 | 类型 | 必填 | 说明 |
104| ------ | ------ | ------ | ------ |
105| isForbidden | boolean | 是 | 是否允许[UIExtensionAbility](../apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md)拉起的页面被使用方的页面覆盖。true表示不允许，false表示允许。 |
106
107
108**错误码**：
109
110以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。
111
112| 错误码ID | 错误信息 |
113| ------ | ------ |
114| 202 | The application is not system-app, can not use system-api. |
115| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
116
117**示例**：
118
119```ts
120import { UIExtensionAbility } from '@kit.AbilityKit';
121import { BusinessError } from '@kit.BasicServicesKit';
122
123export default class UIExtAbility extends UIExtensionAbility {
124  OnCreate() {
125    try {
126      this.context.setHostPageOverlayForbidden(true)
127    } catch (err) {
128      // 处理入参错误异常
129      let code = (err as BusinessError).code;
130      let message = (err as BusinessError).message;
131      console.error(`setHostPageOverlayForbidden failed, code is ${code}, message is ${message}`);
132    }
133  }
134}
135```