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