1# AppServiceExtensionContext (应用后台服务扩展组件上下文) 2<!--Kit: Ability Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @yewei0794--> 5<!--Designer: @jsjzju--> 6<!--Tester: @lixueqing513--> 7<!--Adviser: @huipeizi--> 8 9AppServiceExtensionContext模块是[AppServiceExtensionAbility](../apis-ability-kit/js-apis-app-ability-appServiceExtensionAbility.md)的上下文环境，继承自[ExtensionContext](js-apis-inner-application-extensionContext.md)。 10 11AppServiceExtensionContext提供了连接、断开ServiceExtensionAbility（系统应用后台服务扩展组件）的能力，以及AppServiceExtensionAbility终止自身的能力。这里的ServiceExtensionAbility只能由系统应用开发，支持三方应用连接。 12 13 14> **说明：** 15> 16> - 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 17> - 本模块接口仅可在Stage模型下使用。 18> - 本模块接口需要在主线程中使用，不要在Worker、TaskPool等子线程中使用。 19 20## 导入模块 21 22```ts 23import { common } from '@kit.AbilityKit'; 24``` 25 26## 使用说明 27 28在使用AppServiceExtensionContext的功能前，需要通过AppServiceExtensionAbility子类实例获取。 29 30**示例：** 31 32```ts 33import { AppServiceExtensionAbility } from '@kit.AbilityKit'; 34 35export default class AppServiceExtension extends AppServiceExtensionAbility { 36 onCreate(want: Want) { 37 let context = this.context; // 获取AppServiceExtensionContext 38 } 39} 40``` 41 42## AppServiceExtensionContext 43 44### startAbility 45 46startAbility(want: Want, options?: StartOptions): Promise<void> 47 48启动UIAbility。仅支持在主线程调用。使用Promise异步回调。 49 50**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 51 52**参数：** 53 54| 参数名 | 类型 | 必填 | 说明 | 55| -------- | -------- | -------- | -------- | 56| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的Ability的信息，如Ability名称、Bundle名称等。 | 57| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 58 59**返回值：** 60 61| 类型 | 说明 | 62| -------- | -------- | 63| Promise<void> | Promise对象。无返回结果的Promise对象。 | 64 65**错误码：** 66 67以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 68 69| 错误码ID | 错误信息 | 70| ------- | -------- | 71| 201 | The application does not have permission to call the interface. | 72| 16000001 | The specified ability does not exist. | 73| 16000002 | Incorrect ability type. | 74| 16000004 | Cannot start an invisible component. | 75| 16000005 | The specified process does not have the permission. | 76| 16000008 | The crowdtesting application expires. | 77| 16000009 | An ability cannot be started or stopped in Wukong mode. | 78| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 79| 16000011 | The context does not exist. | 80| 16000012 | The application is controlled. | 81| 16000013 | The application is controlled by EDM. | 82| 16000019 | No matching ability is found. | 83| 16000050 | Internal error. | 84| 16000055 | Installation-free timed out. | 85| 16000071 | App clone is not supported. | 86| 16000072 | App clone or multi-instance is not supported. | 87| 16000073 | The app clone index is invalid. | 88| 16000076 | The app instance key is invalid. | 89| 16000077 | The number of app instances reaches the limit. | 90| 16000078 | The multi-instance is not supported. | 91| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 92| 16000080 | Creating a new instance is not supported. | 93 94**示例：** 95 96```ts 97import { AppServiceExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 98import { BusinessError } from '@kit.BasicServicesKit'; 99 100export default class MyAppServiceExtensionAbility extends AppServiceExtensionAbility { 101 onCreate(want: Want) { 102 let wantInfo: Want = { 103 bundleName: 'com.example.myapplication', 104 abilityName: 'EntryAbility' 105 }; 106 let options: StartOptions = { 107 displayId: 0 108 }; 109 110 try { 111 this.context.startAbility(wantInfo, options) 112 .then(() => { 113 // 执行正常业务 114 console.info('startAbility succeed'); 115 }) 116 .catch((err: BusinessError) => { 117 // 处理业务逻辑错误 118 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 119 }); 120 } catch (err) { 121 // 处理入参错误异常 122 let code = (err as BusinessError).code; 123 let message = (err as BusinessError).message; 124 console.error(`startAbility failed, code is ${code}, message is ${message}`); 125 } 126 } 127} 128``` 129 130### connectServiceExtensionAbility 131 132connectServiceExtensionAbility(want: Want, callback: ConnectOptions): number 133 134将当前AppServiceExtensionAbility连接到一个ServiceExtensionAbility，通过返回的proxy与ServiceExtensionAbility进行通信，以使用ServiceExtensionAbility对外提供的能力。仅支持在主线程调用。 135 136**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| -------- | -------- | -------- | -------- | 142| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要连接的Ability的信息，如Ability名称，Bundle名称等。 | 143| callback | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、连接失败、断开的信息。 | 144 145**返回值：** 146 147| 类型 | 说明 | 148| -------- | -------- | 149| number | 返回连接id，客户端可以通过[disconnectServiceExtensionAbility](#disconnectserviceextensionability)传入该连接id来断开连接。 | 150 151**错误码：** 152 153以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 154 155| 错误码ID | 错误信息 | 156| ------- | -------- | 157| 16000001 | The specified ability does not exist. | 158| 16000002 | Incorrect ability type. | 159| 16000004 | Cannot start an invisible component. | 160| 16000005 | The specified process does not have the permission. | 161| 16000006 | Cross-user operations are not allowed. | 162| 16000008 | The crowdtesting application expires. | 163| 16000011 | The context does not exist. | 164| 16000050 | Internal error. | 165 166**示例：** 167 168```ts 169import { AppServiceExtensionAbility, Want, common } from '@kit.AbilityKit'; 170import { rpc } from '@kit.IPCKit'; 171import { BusinessError } from '@kit.BasicServicesKit'; 172import { hilog } from '@kit.PerformanceAnalysisKit'; 173 174let commRemote: rpc.IRemoteObject | null = null; // 断开连接时需要释放 175const TAG: string = '[AppServiceExtensionAbility]'; 176 177export default class AppServiceExtension extends AppServiceExtensionAbility { 178 connection: number = 0; 179 180 onCreate(localWant: Want) { 181 let want: Want = { 182 bundleName: 'com.example.myapp', 183 abilityName: 'MyAbility' 184 }; 185 let callback: common.ConnectOptions = { 186 onConnect(elementName, remote) { 187 commRemote = remote; 188 hilog.info(0x0000, TAG, '----------- onConnect -----------'); 189 }, 190 onDisconnect(elementName) { 191 hilog.info(0x0000, TAG, '----------- onDisconnect -----------'); 192 }, 193 onFailed(code) { 194 hilog.error(0x0000, TAG, '----------- onFailed -----------'); 195 } 196 }; 197 198 199 try { 200 this.connection = this.context.connectServiceExtensionAbility(want, callback); 201 } catch (paramError) { 202 commRemote = null; 203 // 处理入参错误异常 204 hilog.error(0x0000, TAG, `error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 205 } 206 } 207 208 onDestroy(): void { 209 this.context.disconnectServiceExtensionAbility(this.connection).then(() => { 210 commRemote = null; 211 // 执行正常业务 212 hilog.info(0x0000, TAG, '----------- disconnectServiceExtensionAbility success -----------'); 213 }) 214 .catch((error: BusinessError) => { 215 commRemote = null; 216 // 处理业务逻辑错误 217 hilog.error(0x0000, TAG, `disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 218 }); 219 } 220} 221``` 222 223### disconnectServiceExtensionAbility 224 225disconnectServiceExtensionAbility(connection: number): Promise<void> 226 227将AppServiceExtensionAbility与已连接的ServiceExtensionAbility断开连接。仅支持在主线程调用。使用Promise异步回调。 228 229**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 230 231**参数：** 232 233| 参数名 | 类型 | 必填 | 说明 | 234| -------- | -------- | -------- | -------- | 235| connection | number | 是 | 在[connectServiceExtensionAbility](#connectserviceextensionability)中返回的连接id。 | 236 237**返回值：** 238 239| 类型 | 说明 | 240| -------- | -------- | 241| Promise<void> | Promise对象。无返回结果的Promise对象。 | 242 243**错误码：** 244 245以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 246 247| 错误码ID | 错误信息 | 248| ------- | -------- | 249| 16000011 | The context does not exist. | 250| 16000050 | Internal error. | 251 252**示例：** 253 254参见[connectServiceExtensionAbility](#connectserviceextensionability)。 255 256### terminateSelf 257 258terminateSelf(): Promise<void> 259 260销毁AppServiceExtensionAbility自身。仅支持在主线程调用。使用Promise异步回调。 261 262**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 263 264**返回值：** 265 266| 类型 | 说明 | 267| -------- | -------- | 268| Promise<void> | Promise对象。无返回结果的Promise对象。 | 269 270**错误码：** 271 272以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 273 274| 错误码ID | 错误信息 | 275| ------- | -------------------------------- | 276| 16000009 | An ability cannot be started or stopped in Wukong mode. | 277| 16000011 | The context does not exist. | 278| 16000050 | Internal error. | 279 280**示例：** 281 282```ts 283import { AppServiceExtensionAbility } from '@kit.AbilityKit'; 284import { BusinessError } from '@kit.BasicServicesKit'; 285import { hilog } from '@kit.PerformanceAnalysisKit'; 286 287const TAG: string = '[AppServiceExtensionAbility]'; 288 289export default class AppServiceExtension extends AppServiceExtensionAbility { 290 onCreate(want: Want) { 291 this.context.terminateSelf().then(() => { 292 // 执行正常业务 293 hilog.info(0x0000, TAG, '----------- terminateSelf succeed -----------'); 294 }).catch((error: BusinessError) => { 295 // 处理业务逻辑错误 296 hilog.error(0x0000, TAG, `terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}`); 297 }); 298 } 299} 300```