• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Using UIServiceExtensionAbility for System Floating Windows
2
3<!--Kit: Ability Kit-->
4<!--Subsystem: Ability-->
5<!--Owner: @zhangyafei-echo-->
6<!--Designer: @li-weifeng2-->
7<!--Tester: @lixueqing513-->
8<!--Adviser: @huipeizi-->
9
10## Overview
11
12The UIServiceExtensionAbility is an extension service component that includes a User Interface (UI). System applications can use the UIServiceExtensionAbility to implement a service capability with specific functions and a UI, and then expose this UI service for other third-party applications to call.
13
14In this document, the component that starts or connects to a UIServiceExtensionAbility is called the client, and the UIServiceExtensionAbility is called the server.
15
16An application can use a UIServiceExtensionAbility in two modes:
17- Call [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#startuiserviceextensionability14) in the [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) class to start a UIServiceExtensionAbility.
18- Call [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#connectuiserviceextensionability14) in the [UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md) or [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) class to connect to a UIServiceExtensionAbility.
19
20## Constraints
21
22- This API takes effect only for 2-in-1 devices.
23
24- Third-party applications can connect to a UIServiceExtensionAbility provided by a system application only when they gain focus in the foreground.
25
26- The UIServiceExtensionAbility lifecycle is closely related to the window it binds. It is destroyed once the window is destroyed.
27
28
29## Starting a UIServiceExtensionAbility
30
31An application (client) calls [startUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#startuiserviceextensionability14) to start a UIServiceExtensionAbility. Once the UIServiceExtensionAbility is started, its lifecycle is independent of the client. Even if the client is destroyed, the background service remains alive. However, the service is destroyed if the window fails to be created or is destroyed.
32
33
34The following example uses the **startUIServiceExtensionAbility** API to start a UIServiceExtensionAbility. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability).
35
36```ts
37import { common, Want } from '@kit.AbilityKit';
38import { BusinessError } from '@kit.BasicServicesKit';
39
40@Entry
41@Component
42struct Index {
43  build() {
44    Column() {
45      Row() {
46        // Create a Start button.
47        Button('start UIServiceExtensionAbility')
48          .enabled(true)
49          .onClick(() => {
50            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
51            let startWant: Want = {
52              bundleName: 'com.acts.uiserviceextensionability', // This is just an example. Replace it with the actual bundle name of your UIServiceExtensionAbility.
53              abilityName: 'UiServiceExtAbility', // This is just an example. Replace it with the actual name of your UIServiceExtensionAbility.
54            };
55            try {
56              // Start the UIServiceExtensionAbility.
57              context.startUIServiceExtensionAbility(startWant).then(() => {
58                console.info('startUIServiceExtensionAbility success.');
59              }).catch((error: BusinessError) => {
60                console.error(`startUIServiceExtensionAbility failed, err code: ${error.code}, err msg: ${error.message}.`);
61              });
62            } catch (err) {
63              let code = (err as BusinessError).code;
64              let msg = (err as BusinessError).message;
65              console.error(`startUIServiceExtensionAbility failed, err code: ${code}, err msg: ${msg}.`);
66            }
67          })
68      }
69    }
70  }
71}
72```
73
74## Connecting to a UIServiceExtensionAbility
75
76The client connects to the server through [connectUIServiceExtensionAbility()](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#connectuiserviceextensionability14) and obtains a [UIServiceProxy](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md) object. The client calls [sendData()](../reference/apis-ability-kit/js-apis-inner-application-uiserviceproxy.md#uiserviceproxysenddata) of the proxy object to send data to the server. The server calls the system API **onData()** of the UIServiceExtensionAbility class to receive data from the client.
77
78The following example uses the **connectUIServiceExtensionAbility** API to connect to a UIServiceExtensionAbility. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability).
79
80```ts
81import { common, Want } from '@kit.AbilityKit';
82import { BusinessError } from '@kit.BasicServicesKit';
83
84@Entry
85@Component
86struct Index {
87  comProxy: common.UIServiceProxy | null = null;
88  connectCallback: common.UIServiceExtensionConnectCallback = {
89    onData: (data: Record<string, Object>) => {
90      console.info(`data received, data: ${JSON.stringify(data)}.`);
91    },
92    onDisconnect: () => {
93      console.info(`onDisconnect.`);
94    }
95  }
96
97  build() {
98    Column() {
99      Row() {
100        // Create a Connect button.
101        Button('connect ability')
102          .enabled(true)
103          .onClick(() => {
104            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
105            let startWant: Want = {
106              bundleName: 'com.acts.uiserviceextensionability', // This is just an example. Replace it with the actual bundle name of your UIServiceExtensionAbility.
107              abilityName: 'UiServiceExtAbility', // This is just an example. Replace it with the actual name of your UIServiceExtensionAbility.
108            };
109            try {
110              // Connect to the UIServiceExtensionAbility.
111              context.connectUIServiceExtensionAbility(startWant, this.connectCallback)
112                .then((proxy: common.UIServiceProxy) => {
113                  this.comProxy = proxy;
114                  let formData: Record<string, string> = {
115                    'test': 'test'
116                  };
117                  try {
118                    this.comProxy.sendData(formData);
119                  } catch (err) {
120                    let code = (err as BusinessError).code;
121                    let msg = (err as BusinessError).message;
122                    console.error(`sendData failed, err code:${code}, err msg:${msg}.`);
123                  }
124                })
125                .catch((err: BusinessError) => {
126                  console.error(`connectUIServiceExtensionAbility failed, err code: ${err.code}, err msg: ${err.message}.`);
127                });
128            } catch (err) {
129              let code = (err as BusinessError).code;
130              let msg = (err as BusinessError).message;
131              console.error(`connectUIServiceExtensionAbility failed, err code:${code}, err msg:${msg}.`);
132            }
133          })
134      }
135    }
136  }
137}
138```
139