1# @ohos.app.ability.ServiceExtensionAbility (ServiceExtensionAbility)(系统接口)
2
3ServiceExtensionAbility模块提供后台服务相关扩展能力，提供后台服务创建、销毁、连接、断开等生命周期回调。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口仅可在Stage模型下使用。
10>
11> 本模块为系统接口。
12
13## 导入模块
14
15```ts
16import { ServiceExtensionAbility } from '@kit.AbilityKit';
17```
18
19## 权限
20
21无
22
23## 属性
24
25**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
26
27**系统接口**：此接口为系统接口。
28
29| 名称 | 类型 | 可读 | 可写 | 说明 |
30| -------- | -------- | -------- | -------- | -------- |
31| context | [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext-sys.md)  | 是 | 否 | ServiceExtension的上下文环境，继承自ExtensionContext。 |
32
33
34## ServiceExtensionAbility.onCreate
35
36onCreate(want: Want): void;
37
38Extension生命周期回调，在创建时回调，执行初始化业务逻辑操作。
39
40**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
41
42**系统接口**：此接口为系统接口。
43
44**参数：**
45
46| 参数名 | 类型 | 必填 | 说明 |
47| -------- | -------- | -------- | -------- |
48| want |  [Want](js-apis-app-ability-want.md) | 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 |
49
50**示例：**
51
52```ts
53import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
54
55class ServiceExt extends ServiceExtensionAbility {
56  onCreate(want: Want) {
57    console.log(`onCreate, want: ${want.abilityName}`);
58  }
59}
60```
61
62
63## ServiceExtensionAbility.onDestroy
64
65onDestroy(): void;
66
67Extension生命周期回调，在销毁时回调，执行资源清理等操作。
68
69**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
70
71**系统接口**：此接口为系统接口。
72
73**示例：**
74
75```ts
76import { ServiceExtensionAbility } from '@kit.AbilityKit';
77
78class ServiceExt extends ServiceExtensionAbility {
79  onDestroy() {
80    console.log('onDestroy');
81  }
82}
83```
84
85
86## ServiceExtensionAbility.onRequest
87
88onRequest(want: Want, startId: number): void;
89
90Extension生命周期回调，如果是startAbility或者startServiceExtensionAbility拉起的服务，会在onCreate之后回调。每次拉起服务都会回调，startId会递增。
91
92**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
93
94**系统接口**：此接口为系统接口。
95
96**参数：**
97
98| 参数名 | 类型 | 必填 | 说明 |
99| -------- | -------- | -------- | -------- |
100| want |  [Want](js-apis-app-ability-want.md) | 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 |
101| startId | number | 是 | 返回拉起次数。首次拉起初始值返回1，多次之后自动递增。 |
102
103**示例：**
104
105```ts
106import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
107
108class ServiceExt extends ServiceExtensionAbility {
109  onRequest(want: Want, startId: number) {
110    console.log('onRequest, want: ${want.abilityName}');
111  }
112}
113```
114
115
116## ServiceExtensionAbility.onConnect
117
118onConnect(want: Want): rpc.RemoteObject | Promise<rpc.RemoteObject>;
119
120Extension生命周期回调，如果是connectAbility拉起的服务，会在onCreate之后回调。返回一个RemoteObject对象，用于客户端和服务端进行通信。
121
122**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
123
124**系统接口**：此接口为系统接口。
125
126**参数：**
127
128| 参数名 | 类型 | 必填 | 说明 |
129| -------- | -------- | -------- | -------- |
130| want |  [Want](js-apis-app-ability-want.md)| 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 |
131
132**返回值：**
133
134| 类型 | 说明 |
135| -------- | -------- |
136| rpc.RemoteObject | 一个RemoteObject对象，用于客户端和服务端进行通信。 |
137
138**示例：**
139
140```ts
141import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
142import { rpc } from '@kit.IPCKit';
143
144class StubTest extends rpc.RemoteObject{
145  constructor(des: string) {
146    super(des);
147  }
148  onConnect(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence, option: rpc.MessageOption) {
149  }
150}
151class ServiceExt extends ServiceExtensionAbility {
152  onConnect(want: Want) {
153    console.log('onConnect , want: ${want.abilityName}');
154    return new StubTest('test');
155  }
156}
157```
158
159如果生成返回值RemoteObject依赖一个异步接口，可以使用异步生命周期：
160
161```ts
162import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
163import { rpc } from '@kit.IPCKit';
164
165class StubTest extends rpc.RemoteObject{
166  constructor(des: string) {
167    super(des);
168  }
169  onConnect(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence, option: rpc.MessageOption) {
170  }
171}
172async function getDescriptor() {
173  // 调用异步函数...
174  return "asyncTest"
175}
176class ServiceExt extends ServiceExtensionAbility {
177  async onConnect(want: Want) {
178    console.log(`onConnect , want: ${want.abilityName}`);
179    let descriptor = await getDescriptor();
180    return new StubTest(descriptor);
181  }
182}
183```
184
185## ServiceExtensionAbility.onDisconnect
186
187onDisconnect(want: Want): void | Promise\<void>;
188
189Extension的生命周期回调，客户端执行断开连接服务时回调。
190
191**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
192
193**系统接口**：此接口为系统接口。
194
195**参数：**
196
197| 参数名 | 类型 | 必填 | 说明 |
198| -------- | -------- | -------- | -------- |
199| want |[Want](js-apis-app-ability-want.md)| 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 |
200
201**示例：**
202
203```ts
204import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
205
206class ServiceExt extends ServiceExtensionAbility {
207  onDisconnect(want: Want) {
208    console.log('onDisconnect, want: ${want.abilityName}');
209  }
210}
211```
212
213在执行完onDisconnect生命周期回调后，应用可能会退出，从而可能导致onDisconnect中的异步函数未能正确执行，比如异步写入数据库。可以使用异步生命周期，以确保异步onDisconnect完成后再继续后续的生命周期。
214
215```ts
216import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
217
218class ServiceExt extends ServiceExtensionAbility {
219  async onDisconnect(want: Want) {
220    console.log('onDisconnect, want: ${want.abilityName}');
221    // 调用异步函数...
222  }
223}
224```
225
226## ServiceExtensionAbility.onReconnect
227
228onReconnect(want: Want): void;
229
230Extension的生命周期回调，当所有以前的客户端都断开连接之后，新客户端尝试连接到服务时调用。预留能力，当前暂未支持。
231
232**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
233
234**系统接口**：此接口为系统接口。
235
236**参数：**
237
238| 参数名 | 类型 | 必填 | 说明 |
239| -------- | -------- | -------- | -------- |
240| want |[Want](js-apis-app-ability-want.md)| 是 | 当前Extension相关的Want类型信息，包括ability名称、bundle名称等。 |
241
242**示例：**
243
244```ts
245import { ServiceExtensionAbility, Want } from '@kit.AbilityKit';
246
247class ServiceExt extends ServiceExtensionAbility {
248  onReconnect(want: Want) {
249    console.log('onReconnect, want: ${want.abilityName}');
250  }
251}
252```
253
254## ServiceExtensionAbility.onConfigurationUpdate
255
256onConfigurationUpdate(newConfig: Configuration): void;
257
258当Extension更新配置信息时调用。
259
260**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
261
262**系统接口**：此接口为系统接口。
263
264**参数：**
265
266| 参数名 | 类型 | 必填 | 说明 |
267| -------- | -------- | -------- | -------- |
268| newConfig | [Configuration](js-apis-app-ability-configuration.md) | 是 | 表示需要更新的配置信息。 |
269
270**示例：**
271
272```ts
273import { ServiceExtensionAbility, Configuration } from '@kit.AbilityKit';
274
275class ServiceExt extends ServiceExtensionAbility {
276  onConfigurationUpdate(newConfig: Configuration) {
277    console.log(`onConfigurationUpdate, config: ${JSON.stringify(newConfig)}`);
278  }
279}
280```
281
282## ServiceExtensionAbility.onDump
283
284onDump(params: Array\<string>): Array\<string>;
285
286转储客户端信息时调用。
287
288**系统能力**：SystemCapability.Ability.AbilityRuntime.Core
289
290**系统接口**：此接口为系统接口。
291
292**参数：**
293
294| 参数名 | 类型 | 必填 | 说明 |
295| -------- | -------- | -------- | -------- |
296| params | Array\<string> | 是 | 表示命令形式的参数。|
297
298**示例：**
299
300```ts
301import { ServiceExtensionAbility } from '@kit.AbilityKit';
302
303class ServiceExt extends ServiceExtensionAbility {
304  onDump(params: Array<string>) {
305    console.log(`dump, params: ${JSON.stringify(params)}`);
306    return ['params'];
307  }
308}
309```
310
311