1# @ohos.app.ability.AppServiceExtensionAbility (应用后台服务扩展组件) 2<!--Kit: Ability Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @yewei0794--> 5<!--Designer: @jsjzju--> 6<!--Tester: @lixueqing513--> 7<!--Adviser: @huipeizi--> 8 9AppServiceExtensionAbility模块提供后台服务相关扩展能力，包括后台服务的创建、销毁、连接、断开等生命周期回调。 10 11> **说明：** 12> 13> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> 本模块接口仅可在Stage模型下使用。 16 17## 约束限制 18 19- 当前仅支持2in1设备。 20- 应用集成AppServiceExtensionAbility的组件需要申请ACL权限（ohos.permission.SUPPORT_APP_SERVICE_EXTENSION）。该ACL权限当前只对企业普通应用开放申请。 21 22## 生命周期 23 24AppServiceExtensionAbility提供了[onCreate()](#oncreate)、[onRequest()](#onrequest)、[onConnect()](#onconnect)、[onDisconnect()](#ondisconnect)和[onDestroy()](#ondestroy)生命周期回调，开发者可根据需要重写对应的回调方法。下图展示了AppServiceExtensionAbility的生命周期。 25 26 27 28- **onCreate** 29 在AppServiceExtensionAbility实例创建时，系统会触发该回调。 30 31- **onDestroy** 32 在AppServiceExtensionAbility实例销毁时，系统会触发该回调。 33 34- **onRequest** 35 调用方使用[startAppServiceExtensionAbility()](js-apis-inner-application-uiAbilityContext.md#startappserviceextensionability20)拉起AppServiceExtensionAbility实例时，系统会触发该回调。 36 37- **onConnect** 38 调用方使用[connectAppServiceExtensionAbility](js-apis-inner-application-uiAbilityContext.md#connectappserviceextensionability20)连接AppServiceExtensionAbility实例时，系统会触发该回调。 39 40- **onDisconnect** 41 当所有连接方断开与AppServiceExtensionAbility实例的连接时，系统会触发该回调。 42 43## 导入模块 44 45```ts 46import { AppServiceExtensionAbility } from '@kit.AbilityKit'; 47``` 48 49## AppServiceExtensionAbility 50 51AppServiceExtensionAbility模块提供后台服务相关扩展能力，包括后台服务的创建、销毁、连接、断开等生命周期回调。 52 53### 属性 54 55**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 56 57| 名称 | 类型 | 只读 | 可选 | 说明 | 58| -------- | -------- | -------- | -------- | -------- | 59| context | [AppServiceExtensionContext](js-apis-inner-application-appServiceExtensionContext.md) | 否 | 否 | AppServiceExtensionAbility的上下文环境，继承自[ExtensionContext](js-apis-inner-application-extensionContext.md)。 | 60 61 62### onCreate 63 64onCreate(want: Want): void 65 66在AppServiceExtensionAbility实例创建时，系统会触发该回调。应用可以在该接口中执行自己的业务逻辑初始化操作，例如注册公共事件监听等。 67 68> **说明：** 69> 70> 如果AppServiceExtensionAbility实例已创建，再次启动或连接该实例时不会触发onCreate()回调。 71 72**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| -------- | -------- | -------- | -------- | 78| want | [Want](js-apis-app-ability-want.md) | 是 | 调用方拉起当前AppServiceExtensionAbility实例时传递的Want类型信息，包括Ability名称、Bundle名称等。 | 79 80**示例：** 81 82 ```ts 83 import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit'; 84 import { hilog } from '@kit.PerformanceAnalysisKit'; 85 86 const TAG: string = '[AppServiceExtAbility]'; 87 88 export default class AppServiceExtAbility extends AppServiceExtensionAbility { 89 onCreate(want: Want) { 90 hilog.info(0x0000, TAG, `onCreate, want: ${want.abilityName}`); 91 } 92 } 93 ``` 94 95### onDestroy 96 97onDestroy(): void 98 99在AppServiceExtensionAbility实例销毁时，系统会触发该回调。应用可以在该接口中执行资源清理等操作，如注销监听等。 100 101**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 102 103**示例：** 104 105 ```ts 106 import { AppServiceExtensionAbility } from '@kit.AbilityKit'; 107 import { hilog } from '@kit.PerformanceAnalysisKit'; 108 109 const TAG: string = '[AppServiceExtAbility]'; 110 111 export default class AppServiceExtAbility extends AppServiceExtensionAbility { 112 onDestroy() { 113 hilog.info(0x0000, TAG, `onDestroy`); 114 } 115 } 116 ``` 117 118### onRequest 119 120onRequest(want: Want, startId: number): void 121 122调用方每次使用[startAppServiceExtensionAbility()](js-apis-inner-application-uiAbilityContext.md#startappserviceextensionability20)拉起AppServiceExtensionAbility实例时，系统都会触发该回调。 123 124**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| -------- | -------- | -------- | -------- | 130| want | [Want](js-apis-app-ability-want.md) | 是 | 调用方拉起当前AppServiceExtensionAbility实例时传递的Want类型信息，包括Ability名称、Bundle名称等。 | 131| startId | number | 是 | 返回拉起次数。首次拉起初始值返回1，多次拉起时自动递增。 | 132 133**示例：** 134 135 ```ts 136 import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit'; 137 import { hilog } from '@kit.PerformanceAnalysisKit'; 138 139 const TAG: string = '[AppServiceExtAbility]'; 140 141 export default class AppServiceExtAbility extends AppServiceExtensionAbility { 142 onRequest(want: Want, startId: number) { 143 hilog.info(0x0000, TAG, `onRequest, want: ${want.abilityName}, startId: ${startId}`); 144 } 145 } 146 ``` 147 148### onConnect 149 150onConnect(want: Want): rpc.RemoteObject 151 152调用方使用[connectAppServiceExtensionAbility](js-apis-inner-application-uiAbilityContext.md#connectappserviceextensionability20)连接AppServiceExtensionAbility实例时，系统会触发该回调。 153 154 155应用需要在该接口中返回一个RemoteObject对象，用于客户端和服务端进行通信。当AppServiceExtensionAbility实例处于连接状态时，如果调用方发起新的连接，系统会返回缓存的RemoteObject对象，而不会重复回调[onConnect()](#onconnect)接口。 156 157**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 158 159**参数：** 160 161| 参数名 | 类型 | 必填 | 说明 | 162| -------- | -------- | -------- | -------- | 163| want | [Want](js-apis-app-ability-want.md)| 是 | 调用方拉起当前AppServiceExtensionAbility实例时传递的Want类型信息，包括Ability名称、Bundle名称等。 | 164 165**返回值：** 166 167| 类型 | 说明 | 168| -------- | -------- | 169| [rpc.RemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | 一个RemoteObject对象，用于客户端和服务端进行通信。 | 170 171**示例：** 172 173 ```ts 174 import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit'; 175 import { rpc } from '@kit.IPCKit'; 176 import { hilog } from '@kit.PerformanceAnalysisKit'; 177 178 const TAG: string = '[AppServiceExtAbility]'; 179 180 class StubTest extends rpc.RemoteObject { 181 constructor(des: string) { 182 super(des); 183 } 184 185 onConnect(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence, option: rpc.MessageOption) { 186 } 187 } 188 189 export default class AppServiceExtAbility extends AppServiceExtensionAbility { 190 onConnect(want: Want) { 191 hilog.info(0x0000, TAG, `onConnect, want: ${want.abilityName}`); 192 return new StubTest('test'); 193 } 194 } 195 ``` 196 197### onDisconnect 198 199onDisconnect(want: Want): void 200 201当所有连接方断开与AppServiceExtensionAbility实例的连接时，系统会触发该回调。 202 203**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| -------- | -------- | -------- | -------- | 209| want |[Want](js-apis-app-ability-want.md)| 是 | AppServiceExtensionAbility实例最近一次被拉起或者连接时，调用方传递的Want类型信息，包括Ability名称、Bundle名称等。 | 210 211**示例：** 212 213 ```ts 214 import { AppServiceExtensionAbility, Want } from '@kit.AbilityKit'; 215 import { hilog } from '@kit.PerformanceAnalysisKit'; 216 217 const TAG: string = '[AppServiceExtAbility]'; 218 219 export default class AppServiceExtAbility extends AppServiceExtensionAbility { 220 onDisconnect(want: Want) { 221 hilog.info(0x0000, TAG, `onDisconnect, want: ${want.abilityName}`); 222 } 223 } 224 ``` 225
