1# UIServiceExtension
2
3## 概述
4
5UIServiceExtension是UIService类型的[ExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-extensionAbility.md)浮窗类组件，提供UI界面（例如预览界面）和后台服务能力。组件内部持有了一个UIServiceExtensionContext，通过UIServiceExtensionContext提供了丰富的接口供外部使用。
6
7本文描述中称被启动的UIServiceExtension为服务端，称启动UIServiceExtension的组件为客户端。
8
9应用可以通过启动和连接两种形式使用UIServiceExtension：
10- 通过[UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md)调用[startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability14)方法启动UIServiceExtension。
11- 通过[UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)、[UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md)调用[connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14)方法连接UIServiceExtension。
12
13
14> **说明：**
15>
16> 1. 三方应用可以使用UIServiceExtension，不支持实现UIServiceExtension（需要系统权限）。
17>
18> 2. 三方应用需要在前台获焦的情况下才能连接系统提供的UIServiceExtension。
19>
20> 3. UIServiceExtension的生命周期与绑定的窗口强关联，窗口销毁后UIServiceExtension也一起销毁。
21
22
23## 启动UIServiceExtension
24
25应用通过[startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartuiserviceextensionability14)方法启动一个UIServiceExtension。UIServiceExtension启动后，其生命周期独立于客户端，即使客户端已经销毁，该后台服务仍可继续运行，窗口创建失败或销毁后该服务会被销毁。
26
27
28示例中的context的获取方式请参见[获取UIAbility的上下文信息](uiability-usage.md#获取uiability的上下文信息)。
29
30```ts
31import { common, Want } from '@kit.AbilityKit';
32import { BusinessError } from '@kit.BasicServicesKit';
33
34@Entry
35@Component
36struct Index {
37  build() {
38    Column() {
39      Row() {
40        // 创建启动按钮
41        Button('start ability')
42          .enabled(true)
43          .onClick(() => {
44            let context = getContext(this) as common.UIAbilityContext;
45            let startWant: Want = {
46              bundleName: 'com.acts.uiserviceextensionability',
47              abilityName: 'UiServiceExtAbility',
48            };
49            try {
50              // 启动UIServiceExtensionAbility
51              context.startUIServiceExtensionAbility(startWant).then(() => {
52                console.log('startUIServiceExtensionAbility success');
53              }).catch((error: BusinessError) => {
54                console.log('startUIServiceExtensionAbility error', JSON.stringify(error));
55              })
56            } catch (err) {
57              console.log('startUIServiceExtensionAbility failed', JSON.stringify(err));
58            }
59          })
60      }
61    }
62  }
63}
64```
65
66## 客户端连接服务端
67
68  客户端通过[connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectuiserviceextensionability14)连接服务端，获取并保存[UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md)对象。通过该proxy对象的[sendData()](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md#uiserviceproxysenddata)方法发送数据给服务端。服务端通过UIServiceExtensionAbility类onData()（系统接口）方法接收客户端数据。
69
70
71```ts
72import { common, Want } from '@kit.AbilityKit';
73import { BusinessError } from '@kit.BasicServicesKit';
74
75@Entry
76@Component
77struct Index {
78  comProxy: common.UIServiceProxy | null = null;
79  connectCallback : common.UIServiceExtensionConnectCallback = {
80    onData:(data: Record<string, Object>) => {
81      console.log("received data", JSON.stringify(data));
82    },
83    onDisconnect:() => {
84      console.log("onDisconnect ");
85    }
86  }
87
88  build() {
89    Column() {
90      Row() {
91        // 创建连接按钮
92        Button("connect ability")
93          .enabled(true)
94          .onClick(() => {
95            let context = getContext(this) as common.UIAbilityContext;
96            let startWant:Want = {
97              bundleName: 'com.acts.uiserviceextensionability',
98              abilityName: 'UiServiceExtAbility',
99            };
100            try {
101            // 连接UIServiceExtensionAbility
102            context.connectUIServiceExtensionAbility(startWant, this.connectCallback).then((proxy: common.UIServiceProxy) => {
103                this.comProxy = proxy;
104                let formData: Record<string, string> = {
105                  'test': 'test'
106                };
107                try {
108                  this.comProxy.sendData(formData);
109                } catch (err) {
110                  console.log('sendData failed', JSON.stringify(err));
111                };
112              }).catch((err: BusinessError) => {
113                console.log("connectUIServiceExtensionAbility failed", JSON.stringify(err));
114              });
115            } catch(err) {
116              console.log("connectUIServiceExtensionAbility failed", JSON.stringify(err));
117            };
118      })
119      }
120  }
121}
122}
123```