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