1# UIServiceExtensionContext (系统接口)
2
3UIServiceExtensionContext模块是[UIServiceExtension](js-apis-app-ability-uiServiceExtensionAbility-sys.md)的上下文环境，继承自[ExtensionContext](js-apis-inner-application-extensionContext.md)。
4
5UIServiceExtensionContext模块提供访问[UIServiceExtension](js-apis-app-ability-uiServiceExtensionAbility-sys.md)特定资源以及具有的能力，包括启动、停止、绑定、解绑Ability。
6
7> **说明：**
8>
9>  - 本模块首批接口从API version 13开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
10>  - 本模块接口仅可在Stage模型下使用。
11>  - 本模块接口需要在主线程中使用，不要在Worker、TaskPool等子线程中使用。
12>  - 本模块接口为系统接口。
13
14## 导入模块
15
16```ts
17import { common } from '@kit.AbilityKit';
18```
19
20## 使用说明
21
22在使用UIServiceExtensionContext的功能前，需要通过[UIServiceExtension](js-apis-app-ability-uiServiceExtensionAbility-sys.md)子类实例获取上下文环境。
23
24**示例：**
25
26```ts
27import { common, UIServiceExtensionAbility } from '@kit.AbilityKit';
28
29class UIServiceExtAbility extends UIServiceExtensionAbility {
30  onCreate() {
31    let context:common.UIServiceExtensionContext = this.context ; // 获取UIServiceExtensionContext
32  }
33}
34```
35
36
37## UIServiceExtensionContext.startAbility<sup>13+<sup>
38
39startAbility(want: Want, options?: StartOptions): Promise&lt;void&gt;
40
41启动Ability，结果以Promise的形式返回。
42
43> **说明：**
44>
45> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。
46
47**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
48
49**系统接口**：此接口为系统接口。
50
51**参数：**
52
53| 参数名 | 类型 | 只读 | 可选 | 说明 |
54| -------- | -------- | -------- | -------- | -------- |
55| want | [Want](js-apis-app-ability-want.md)  | 是 | 否 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 |
56| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 |是 | 启动Ability所携带的参数。 |
57
58**返回值：**
59
60| 类型 | 说明 |
61| -------- | -------- |
62| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
63
64**错误码：**
65
66以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
67
68| 错误码ID | 错误信息 |
69| ------- | -------- |
70| 201 | The application does not have permission to call the interface. |
71| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
72| 16000001 | The specified ability does not exist. |
73| 16000002 | Incorrect ability type. |
74| 16000004 | Failed to start the invisible ability. |
75| 16000005 | The specified process does not have the permission. |
76| 16000006 | Cross-user operations are not allowed. |
77| 16000008 | The crowdtesting application expires. |
78| 16000009 | An ability cannot be started or stopped in Wukong mode. |
79| 16000010 | The call with the continuation flag is forbidden.        |
80| 16000011 | The context does not exist.        |
81| 16000012 | The application is controlled.        |
82| 16000013 | The application is controlled by EDM.       |
83| 16000019 | Can not match any component.       |
84| 16000050 | Internal error. |
85| 16000053 | The ability is not on the top of the UI. |
86| 16000055 | Installation-free timed out. |
87| 16200001 | The caller has been released. |
88
89**示例：**
90
91```ts
92import { UIServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit';
93import { BusinessError } from '@kit.BasicServicesKit';
94
95class UIEntryAbility extends UIServiceExtensionAbility {
96  onCreate() {
97    let want: Want = {
98      bundleName: 'com.example.myapp',
99      abilityName: 'MyAbility'
100    };
101    let options: StartOptions = {
102      windowMode: 0,
103    };
104
105    try {
106      this.context.startAbility(want, options)
107        .then((data: void) => {
108          // 执行正常业务
109          console.log('startAbility succeed');
110        })
111        .catch((error: BusinessError) => {
112          // 处理业务逻辑错误
113          console.error(`startAbility failed, error.code: ${error.code}, error.message: ${error.message}`);
114        });
115    } catch (paramError) {
116      // 处理入参错误异常
117      console.error(`error.code: ${paramError.code}, error.message: ${paramError.message}`);
118    }
119  }
120}
121```
122
123
124## UIServiceExtensionContext.terminateSelf<sup>13+<sup>
125
126terminateSelf(): Promise&lt;void&gt;
127
128销毁[UIServiceExtension](js-apis-app-ability-uiServiceExtensionAbility-sys.md)。
129
130**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
131
132**系统接口**：此接口为系统接口。
133
134**返回值：**
135
136| 类型 | 说明 |
137| -------- | -------- |
138| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
139
140**错误码：**
141
142无。
143
144**示例：**
145
146```ts
147import { UIServiceExtensionAbility } from '@kit.AbilityKit';
148import { BusinessError } from '@kit.BasicServicesKit';
149
150class UIEntryAbility extends UIServiceExtensionAbility {
151  onCreate() {
152    this.context.terminateSelf().then(() => {
153      // 执行正常业务
154      console.log('terminateSelf succeed');
155    }).catch((error: BusinessError) => {
156      // 处理业务逻辑错误
157      console.error(`terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}`);
158    });
159  }
160}
161```
162
163## UIServiceExtensionContext.startAbilityByType<sup>13+<sup>
164
165startAbilityByType(type: string, wantParam: Record&lt;string, Object&gt;,
166    abilityStartCallback: AbilityStartCallback): Promise&lt;void&gt;
167
168按目标ability的类型启动[UIAbility](js-apis-app-ability-uiAbility.md)或[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)。仅支持处于前台的应用调用。
169
170
171> **说明：**
172>
173> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。
174
175**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
176
177**系统接口**：此接口为系统接口。
178
179**参数：**
180
181| 参数名 | 类型 | 只读 | 可选 | 说明 |
182| -------- | -------- | -------- | -------- |  -------- |
183| type | string  | 是 | 否 |  目标ability类型。 |
184| wantParam | Record&lt;string, Object&gt;| 是 | 否 | want 参数。 |
185| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md)| 是 | 否| 回调。 |
186
187**返回值：**
188
189| 类型 | 说明 |
190| -------- | -------- |
191| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
192
193**错误码：**
194
195以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
196
197| 错误码ID | 错误信息 |
198| ------- | -------- |
199| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
200| 16000050  | Internal error.                                                                                         |
201
202**示例：**
203
204```ts
205import { common } from '@kit.AbilityKit';
206import { BusinessError } from '@kit.BasicServicesKit';
207
208const TAG: string = '[Extension_Sub] ';
209
210@Entry
211@Component
212struct SubIndex {
213  build() {
214    Row() {
215      Column() {
216        Button("startAbilityByType")
217          .fontSize(10)
218          .fontWeight(FontWeight.Bold)
219          .onClick(() => {
220            let context = getContext(this) as common.UIServiceExtensionContext;
221            let startWant: Record<string, Object> = {
222              'sceneType': 1,
223              'email': [encodeURI('xxx@example.com'), encodeURI('xxx@example.com')], // 收件人邮箱地址，多值以逗号分隔，对数组内容使用encodeURI()方法进行url编码
224              'cc': [encodeURI('xxx@example.com'), encodeURI('xxx@example.com')], // 抄收人邮箱地址，多值以逗号分隔，对数组内容使用encodeURI()方法进行url编码
225              'bcc': [encodeURI('xxx@example.com'), encodeURI('xxx@example.com')], // 密送人邮箱地址，多值以逗号分隔，对数组内容使用encodeURI()方法进行url编码
226              'subject': encodeURI('邮件主题'), // 邮件主题，对内容使用encodeURI()方法进行url编码
227              'body': encodeURI('邮件正文'), // 邮件正文，对内容使用encodeURI()方法进行url编码
228              'ability.params.stream': [encodeURI('附件uri1'), encodeURI('附件uri2')], // 附件uri，多值以逗号分隔，对数组内容使用encodeURI()方法进行url编码
229              'ability.want.params.uriPermissionFlag': 1
230            };
231            let abilityStartCallback: common.AbilityStartCallback = {
232              onError: (code: number, name: string, message: string) => {
233                console.log(TAG + `code: ${code}  name:${name}  message:${message}`);
234              }
235            };
236            try {
237              // 按目标ability的类型启动UIAbility或UIExtensionAbility
238              context.startAbilityByType("mail", startWant, abilityStartCallback)
239                .then(() => {
240                  console.log(TAG + `Successed in windows starting ability`);
241                }).catch((err: BusinessError) => {
242                console.log(TAG + `Failed to windows starting ability, Code is ${err.code}, message is ${err.message}`);
243              })
244            } catch (err) {
245              console.log(TAG + `Failed to windows starting ability, Code is ${err.code}, message is ${err.message}`);
246            }
247          })
248      }
249      .width('100%')
250    }
251    .height('100%')
252  }
253}
254```
255
256## UIServiceExtensionContext.connectServiceExtensionAbility<sup>13+<sup>
257
258connectServiceExtensionAbility(want: Want, options: ConnectOptions): number
259
260连接到[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)，返回连接id。
261
262
263> **说明：**
264>
265> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。
266
267**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
268
269**系统接口**：此接口为系统接口。
270
271**参数：**
272
273| 参数名               | 类型                     | 只读 | 可选 | 说明              |
274| -------------------- | ------------------------ | ---- | ---- |----------------- |
275| want                 | [Want](js-apis-app-ability-want.md) | 是  | 否 | Want 参数。       |
276| options              | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 |是   | 连接选项。 |
277
278**返回值：**
279
280| 类型 | 说明 |
281| -------- | -------- |
282| number | 返回连接id。 |
283
284**错误码：**
285
286以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
287
288| 错误码ID | 错误信息  |
289| -------- | --- |
290| 201     | Not system application.   |
291| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
292| 16000001  | The specified ability does not exist.         |
293| 16000002   | Incorrect ability type.         |
294| 16000004   | Failed to start the invisible ability.         |
295| 16000005   | The specified process does not have the permission.         |
296| 16000006   | Cross-user operations are not allowed.         |
297| 16000008   | The crowdtesting application expires.        |
298| 16000011   | The context does not exist.         |
299| 16000050   | Internal error.        |
300| 16000053   | The ability is not on the top of the UI.        |
301| 16000055   | Installation-free timed out.         |
302
303
304**示例：**
305
306```ts
307import { common, Want } from '@kit.AbilityKit';
308import { rpc } from '@kit.IPCKit';
309import { promptAction } from '@kit.ArkUI';
310import { hilog } from '@kit.PerformanceAnalysisKit';
311// The client needs to import idl_service_ext_proxy.ts provided by the server to the local project.
312import IdlServiceExtProxy from '../IdlServiceExt/idl_service_ext_proxy';
313
314const TAG: string = '[Page_ServiceExtensionAbility]';
315const DOMAIN_NUMBER: number = 0xFF00;
316
317let connectionId: number;
318let want: Want = {
319  deviceId: '',
320  bundleName: 'com.samples.stagemodelabilitydevelop',
321  abilityName: 'ServiceExtAbility'
322};
323
324let options: common.ConnectOptions = {
325  onConnect(elementName, remote: rpc.IRemoteObject): void {
326    hilog.info(DOMAIN_NUMBER, TAG, 'onConnect callback');
327    if (remote === null) {
328      hilog.info(DOMAIN_NUMBER, TAG, `onConnect remote is null`);
329      return;
330    }
331    let serviceExtProxy: IdlServiceExtProxy = new IdlServiceExtProxy(remote);
332    // Communication is carried out by API calling, without exposing RPC details.
333    serviceExtProxy.processData(1, (errorCode: number, retVal: number) => {
334      hilog.info(DOMAIN_NUMBER, TAG, `processData, errorCode: ${errorCode}, retVal: ${retVal}`);
335    });
336    serviceExtProxy.insertDataToMap('theKey', 1, (errorCode: number) => {
337      hilog.info(DOMAIN_NUMBER, TAG, `insertDataToMap, errorCode: ${errorCode}`);
338    })
339  },
340  onDisconnect(elementName): void {
341    hilog.info(DOMAIN_NUMBER, TAG, 'onDisconnect callback');
342  },
343  onFailed(code: number): void {
344    hilog.info(DOMAIN_NUMBER, TAG, 'onFailed callback', JSON.stringify(code));
345  }
346};
347@Entry
348@Component
349struct Page_UIServiceExtensionAbility {
350  build() {
351    Column() {
352      //...
353      List({ initialIndex: 0 }) {
354        ListItem() {
355          Row() {
356            //...
357          }
358          .onClick(() => {
359            let context: common.UIServiceExtensionContext = getContext(this) as common.UIServiceExtensionContext;
360            // The ID returned after the connection is set up must be saved. The ID will be used for disconnection.
361            connectionId = context.connectServiceExtensionAbility(want, options);
362            // The background service is connected.
363            promptAction.showToast({
364              message: $r('app.string.SuccessfullyConnectBackendService')
365            });
366            // connectionId = context.connectAbility(want, options);
367            hilog.info(DOMAIN_NUMBER, TAG, `connectionId is : ${connectionId}`);
368          })
369        }
370        //...
371      }
372      //...
373    }
374    //...
375  }
376}
377```
378
379## UIServiceExtensionContext.disconnectServiceExtensionAbility<sup>13+<sup>
380
381disconnectServiceExtensionAbility(connectionId: number): Promise&lt;void&gt;
382
383断开与[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)的连接, 与[connectServiceExtensionAbility](#uiserviceextensioncontextconnectserviceextensionability13)功能相反。
384
385
386**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
387
388**系统接口**：此接口为系统接口。
389
390**参数：**
391
392| 参数名                | 类型                     | 只读 | 可选 | 说明              |
393| -------------------- | ------------------------ | ---- | ----------------- | ----------------- |
394| connectionId         | number                   | 是  | 否 | 从[connectServiceExtensionAbility](#uiserviceextensioncontextconnectserviceextensionability13)接口返回的连接Id。 |
395
396
397**返回值：**
398
399| 类型                | 说明                              |
400| ------------------- | ---------------------------------|
401| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
402
403**错误码：**
404
405以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。
406
407| 错误码ID | 错误信息 |
408| -------- | --------------------- |
409| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
410| 16000011  | The context does not exist.      |
411| 16000050 | Internal error.      |
412
413**示例：**
414
415```ts
416import { common } from '@kit.AbilityKit';
417import { promptAction } from '@kit.ArkUI';
418import { hilog } from '@kit.PerformanceAnalysisKit';
419import { BusinessError } from '@kit.BasicServicesKit';
420
421const TAG: string = '[Page_ServiceExtensionAbility]';
422const DOMAIN_NUMBER: number = 0xFF00;
423
424let connectionId: number;
425@Entry
426@Component
427struct Page_UIServiceExtensionAbility {
428  build() {
429    Column() {
430      //...
431      List({ initialIndex: 0 }) {
432        ListItem() {
433          Row() {
434            //...
435          }
436          .onClick(() => {
437            let context: common.UIServiceExtensionContext = getContext(this) as common.UIServiceExtensionContext;
438            // connectionId为调用connectServiceExtensionAbility接口时的返回值，需开发者自行维护
439            context.disconnectServiceExtensionAbility(connectionId).then(() => {
440              hilog.info(DOMAIN_NUMBER, TAG, 'disconnectServiceExtensionAbility success');
441              // 成功断连后台服务
442              promptAction.showToast({
443                message: $r('app.string.SuccessfullyDisconnectBackendService')
444              });
445            }).catch((error: BusinessError) => {
446              hilog.error(DOMAIN_NUMBER, TAG, 'disconnectServiceExtensionAbility failed');
447            });
448          })
449        }
450        //...
451      }
452      //...
453    }
454    //...
455  }
456}
457```
458