1# FormExtensionContext (系统接口) 2 3FormExtensionContext模块是[FormExtensionAbility](js-apis-app-form-formExtensionAbility.md)的上下文环境，继承自[ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md)。 4 5FormExtensionContext模块提供FormExtensionAbility具有的接口和能力。 6 7> **说明：** 8> 9> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 10> 本模块接口仅可在Stage模型下使用。 11> 本模块接口为系统接口。 12 13 14 15## 导入模块 16 17```ts 18import { common } from '@kit.AbilityKit'; 19``` 20 21## FormExtensionContext.startAbility 22 23startAbility(want: Want, callback: AsyncCallback<void>): void 24 25拉起一个应用的Ability。使用callback异步回调。 26 27**系统接口：** 此接口为系统接口。 28 29**系统能力：** SystemCapability.Ability.Form 30 31**错误码：** 32 33| 错误码ID | 错误信息 | 34| -------- | -------- | 35| 202 | The application is not a system application. | 36| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 37| 16500050 | IPC connection error. | 38| 16500100 | Failed to obtain the configuration information. | 39| 16501000 | An internal functional error occurred. | 40 41以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| ------| --------------------------------- | ---- | -------------------------------------- | 47| want| [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 包含bundleName，abilityName以及用户自定参数用于拉起Ability。 | 48| callback| AsyncCallback<void> | 是 | 回调函数。当拉起一个应用的Ability成功，err为undefined，否则为错误对象。 | 49 50**示例：** 51 52```ts 53import { FormExtensionAbility } from '@kit.FormKit'; 54import { Want } from '@kit.AbilityKit'; 55import { BusinessError } from '@kit.BasicServicesKit'; 56 57export default class MyFormExtensionAbility extends FormExtensionAbility { 58 onFormEvent(formId: string, message: string) { 59 // 当触发卡片message事件时，执行startAbility 60 console.log(`FormExtensionAbility onFormEvent, formId: ${formId}, message:${message}`); 61 let want: Want = { 62 deviceId: '', 63 bundleName: 'com.example.formstartability', 64 abilityName: 'EntryAbility', 65 parameters: { 66 'message': message 67 } 68 }; 69 this.context.startAbility(want, (error: BusinessError) => { 70 if (error) { 71 console.error(`FormExtensionContext startAbility, error:${JSON.stringify(error)}`); 72 } else { 73 console.log('FormExtensionContext startAbility success'); 74 } 75 }); 76 } 77}; 78``` 79 80## FormExtensionContext.startAbility 81 82startAbility(want: Want): Promise<void> 83 84拉起一个应用的Ability。使用Promise异步回调。 85 86**系统接口：** 此接口为系统接口。 87 88**系统能力：** SystemCapability.Ability.Form 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ------| --------------------------------- | ---- | -------------------------------------- | 94| want| [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 包含bundleName，abilityName以及用户自定参数用于拉起Ability。 | 95 96**返回值：** 97 98| 类型 | 说明 | 99| ------------ | ---------------------------------- | 100| Promise<void> | 无返回结果的Promise对象。 | 101 102**错误码：** 103 104| 错误码ID | 错误信息 | 105| -------- | -------- | 106| 202 | The application is not a system application. | 107| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 108| 16500050 | IPC connection error. | 109| 16500100 | Failed to obtain the configuration information. | 110| 16501000 | An internal functional error occurred. | 111 112以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 113 114**示例：** 115 116```ts 117import { FormExtensionAbility } from '@kit.FormKit'; 118import { Want } from '@kit.AbilityKit'; 119import { BusinessError } from '@kit.BasicServicesKit'; 120 121export default class MyFormExtensionAbility extends FormExtensionAbility { 122 onFormEvent(formId: string, message: string) { 123 // 当触发卡片message事件时，执行startAbility 124 console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`); 125 let want: Want = { 126 deviceId: '', 127 bundleName: 'com.example.formstartability', 128 abilityName: 'EntryAbility', 129 parameters: { 130 'message': message 131 } 132 }; 133 this.context.startAbility(want).then(() => { 134 console.info('StartAbility Success'); 135 }).catch((error: BusinessError) => { 136 console.error(`StartAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 137 }); 138 } 139}; 140``` 141 142## FormExtensionContext.connectServiceExtensionAbility<sup>10+</sup> 143 144connectServiceExtensionAbility(want: Want, options: ConnectOptions): number 145 146将一个Ability与服务类型的Ability绑定。 147 148**系统能力：** SystemCapability.Ability.Form 149 150**系统接口：** 此接口为系统接口，三方应用不支持调用。 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| -------- | -------- | -------- | -------- | 156| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 | 157| options | [ConnectOptions](../apis-ability-kit/js-apis-inner-ability-connectOptions.md) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。 | 158 159**返回值：** 160 161| 类型 | 说明 | 162| -------- | -------- | 163| number | 返回一个connectId，后续根据此connectId断开连接。 | 164 165**错误码：** 166 167| 错误码ID | 错误信息 | 168| ------- | -------------------------------- | 169| 201 | Permissions denied. | 170| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 171| 16000001 | The specified ability does not exist. | 172| 16000002 | Incorrect ability type. | 173| 16000004 | Can not start invisible component. | 174| 16000005 | The specified process does not have the permission. | 175| 16000006 | Cross-user operations are not allowed. | 176| 16000008 | The crowdtesting application expires. | 177| 16000053 | The ability is not on the top of the UI. | 178| 16000055 | Installation-free timed out. | 179| 16000011 | The context does not exist. | 180| 16000050 | Internal error. | 181 182以上错误码详细介绍请参考[元能力子系统错误码](../apis-ability-kit/errorcode-ability.md)。 183 184**示例：** 185 186```ts 187import { rpc } from '@kit.IPCKit'; 188import { FormExtensionAbility } from '@kit.FormKit'; 189import { common, Want } from '@kit.AbilityKit'; 190import { BusinessError } from '@kit.BasicServicesKit'; 191 192let commRemote: rpc.IRemoteObject | null = null; 193 194export default class MyFormExtensionAbility extends FormExtensionAbility { 195 onFormEvent(formId: string, message: string) { 196 // 当触发卡片message事件时，执行connectServiceExtensionAbility 197 console.log(`FormExtensionAbility onFormEvent, formId:${formId}, message:${message}`); 198 let want: Want = { 199 deviceId: '', 200 bundleName: 'com.example.formstartability', 201 abilityName: 'EntryAbility', 202 parameters: { 203 'message': message 204 } 205 }; 206 let options: common.ConnectOptions = { 207 onConnect(elementName, remote) { 208 commRemote = remote; // remote 用于与ServiceExtensionAbility进行通信 209 console.log('----------- onConnect -----------'); 210 }, 211 onDisconnect(elementName) { 212 console.log('----------- onDisconnect -----------') 213 }, 214 onFailed(code) { 215 console.error('----------- onFailed -----------') 216 } 217 }; 218 219 let connection: number | null = null; 220 try { 221 connection = this.context.connectServiceExtensionAbility(want, options); 222 } catch (paramError) { 223 // 处理入参错误异常 224 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 225 } 226 } 227}; 228``` 229 230## FormExtensionContext.disconnectServiceExtensionAbility<sup>10+</sup> 231 232disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback<void>): void 233 234将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空。 235 236**系统能力：** SystemCapability.Ability.Form 237 238**系统接口：** 此接口为系统接口，三方应用不支持调用。 239 240**参数：** 241 242| 参数名 | 类型 | 必填 | 说明 | 243| -------- | -------- | -------- | -------- | 244| connection | number | 是 | 在[connectServiceExtensionAbility](#formextensioncontextconnectserviceextensionability10)中返回的number。 | 245| callback | AsyncCallback<void> | 是 | 回调函数。当Ability与绑定的服务类型的Ability解绑成功，err为undefined，否则为错误对象。 | 246 247**错误码：** 248 249| 错误码ID | 错误信息 | 250| ------- | -------------------------------- | 251| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 252| 16000011 | The context does not exist. | 253| 16000050 | Internal error. | 254 255以上错误码详细介绍请参考[元能力子系统错误码](../apis-ability-kit/errorcode-ability.md)。 256 257**示例：** 258 259```ts 260import { FormExtensionAbility } from '@kit.FormKit'; 261import { rpc } from '@kit.IPCKit'; 262import { BusinessError } from '@kit.BasicServicesKit'; 263 264// commRemote为onConnect回调内返回的remote对象，此处定义为null无任何实际意义，仅作示例 265let commRemote: rpc.IRemoteObject | null = null; 266export default class MyFormExtensionAbility extends FormExtensionAbility { 267 onFormEvent(formId: string, message: string) { 268 // 实际使用时，connection为connectServiceExtensionAbility中的返回值，此处定义为1无任何实际意义，仅作示例 269 let connection: number = 1; 270 271 try { 272 this.context.disconnectServiceExtensionAbility(connection, (error: BusinessError) => { 273 commRemote = null; 274 if (error.code) { 275 // 处理业务逻辑错误 276 console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 277 return; 278 } 279 // 执行正常业务 280 console.log('disconnectServiceExtensionAbility succeed'); 281 }); 282 } catch (paramError) { 283 commRemote = null; 284 // 处理入参错误异常 285 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 286 } 287 } 288}; 289``` 290 291## FormExtensionContext.disconnectServiceExtensionAbility<sup>10+</sup> 292 293disconnectServiceExtensionAbility(connection: number): Promise<void> 294 295将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空(Promise形式返回结果)。 296 297**系统能力：** SystemCapability.Ability.Form 298 299**系统接口：** 此接口为系统接口，三方应用不支持调用。 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| -------- | -------- | -------- | -------- | 305| connection | number | 是 | 在[connectServiceExtensionAbility](#formextensioncontextconnectserviceextensionability10)中返回的number。 | 306 307**返回值：** 308 309| 类型 | 说明 | 310| -------- | -------- | 311| Promise<void> | Promise对象。无返回结果的Promise对象。 | 312 313**错误码：** 314 315| 错误码ID | 错误信息 | 316| ------- | -------------------------------- | 317| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 318| 16000011 | The context does not exist. | 319| 16000050 | Internal error. | 320 321以上错误码详细介绍请参考[元能力子系统错误码](../apis-ability-kit/errorcode-ability.md)。 322 323**示例：** 324 325```ts 326import { FormExtensionAbility } from '@kit.FormKit'; 327import { rpc } from '@kit.IPCKit'; 328import { BusinessError } from '@kit.BasicServicesKit'; 329 330// commRemote为onConnect回调内返回的remote对象，此处定义为null无任何实际意义，仅作示例 331let commRemote: rpc.IRemoteObject | null = null; 332export default class MyFormExtensionAbility extends FormExtensionAbility { 333 onFormEvent(formId: string, message: string) { 334 // 实际使用时，connection为connectServiceExtensionAbility中的返回值，此处定义为1无任何实际意义，仅作示例 335 let connection: number = 1; 336 337 try { 338 this.context.disconnectServiceExtensionAbility(connection) 339 .then(() => { 340 commRemote = null; 341 // 执行正常业务 342 console.log('disconnectServiceExtensionAbility succeed'); 343 }) 344 .catch((error: BusinessError) => { 345 commRemote = null; 346 // 处理业务逻辑错误 347 console.error(`disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}`); 348 }); 349 } catch (paramError) { 350 commRemote = null; 351 // 处理入参错误异常 352 console.error(`error.code: ${(paramError as BusinessError).code}, error.message: ${(paramError as BusinessError).message}`); 353 } 354 } 355}; 356``` 357