1# @ohos.app.form.FormExtensionAbility (FormExtensionAbility) 2 3FormExtensionAbility为卡片扩展模块，提供卡片创建、销毁、刷新等生命周期回调。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 本模块接口仅可在Stage模型下使用。 9 10## 导入模块 11 12```ts 13import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 14``` 15 16## 属性 17 18**系统能力**：SystemCapability.Ability.Form 19 20| 名称 | 类型 | 可读 | 可写 | 说明 | 21| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 22| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | 是 | 否 | FormExtensionAbility的上下文环境，继承自[ExtensionContext](js-apis-inner-application-extensionContext.md)。 | 23 24## onAddForm 25 26onAddForm(want: Want): formBindingData.FormBindingData 27 28卡片提供方接收创建卡片的通知接口。 29 30**系统能力**：SystemCapability.Ability.Form 31 32**参数：** 33 34| 参数名 | 类型 | 必填 | 说明 | 35| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 36| want | [Want](js-apis-application-want.md) | 是 | 当前ExtensionAbility相关的Want类型信息，包括卡片ID、卡片名称、卡片样式等。这些卡片信息必须作为持久数据进行管理，以便后续更新和删除卡片。 | 37 38**返回值：** 39 40| 类型 | 说明 | 41| ------------------------------------------------------------ | ----------------------------------------------------------- | 42| [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | formBindingData.FormBindingData对象，卡片要显示的数据。 | 43 44**示例：** 45 46```ts 47import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 48import formBindingData from'@ohos.app.form.formBindingData'; 49 50export default class MyFormExtensionAbility extends FormExtensionAbility { 51 onAddForm(want) { 52 console.log('FormExtensionAbility onAddForm, want:' + want.abilityName); 53 let dataObj1 = { 54 temperature:'11c', 55 'time':'11:00' 56 }; 57 let obj1 = formBindingData.createFormBindingData(dataObj1); 58 return obj1; 59 } 60} 61``` 62 63## onCastToNormalForm 64 65onCastToNormalForm(formId: string): void 66 67卡片提供方接收临时卡片转常态卡片的通知接口。 68 69**系统能力**：SystemCapability.Ability.Form 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| ------ | ------ | ---- | ------------------------ | 75| formId | string | 是 | 请求转换为常态的卡片标识。 | 76 77**示例：** 78 79```ts 80export default class MyFormExtensionAbility extends FormExtensionAbility { 81 onCastToNormalForm(formId) { 82 console.log('FormExtensionAbility onCastToNormalForm, formId:' + formId); 83 } 84} 85``` 86 87## onUpdateForm 88 89onUpdateForm(formId: string): void 90 91卡片提供方接收更新卡片的通知接口。获取最新数据后调用[FormExtensionContext](js-apis-inner-application-formExtensionContext.md)的updateForm接口刷新卡片数据。 92 93**系统能力**：SystemCapability.Ability.Form 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | ------ | ---- | ------------------ | 99| formId | string | 是 | 请求更新的卡片ID。 | 100 101**示例：** 102 103```ts 104import formBindingData from '@ohos.app.form.formBindingData'; 105export default class MyFormExtensionAbility extends FormExtensionAbility { 106 onUpdateForm(formId) { 107 console.log('FormExtensionAbility onUpdateForm, formId:' + formId); 108 let obj2 = formBindingData.createFormBindingData({temperature:'22c', time:'22:00'}); 109 this.context.updateForm(formId, obj2).then((data)=>{ 110 console.log('FormExtensionAbility context updateForm, data:' + data); 111 }).catch((error) => { 112 console.error('Operation updateForm failed. Cause: ' + error);}); 113 } 114} 115``` 116 117## onChangeFormVisibility 118 119onChangeFormVisibility(newStatus: { [key: string]: number }): void 120 121卡片提供方接收修改可见性的通知接口。 122 123**系统能力**：SystemCapability.Ability.Form 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| --------- | ------------------------- | ---- | ---------------------------- | 129| newStatus | { [key: string]: number } | 是 | 请求修改的卡片标识和可见状态。 | 130 131**示例：** 132 133```ts 134import formBindingData from '@ohos.app.form.formBindingData'; 135export default class MyFormExtensionAbility extends FormExtensionAbility { 136 onChangeFormVisibility(newStatus) { 137 console.log('FormExtensionAbility onChangeFormVisibility, newStatus:' + newStatus); 138 let obj2 = formBindingData.createFormBindingData({temperature:'22c', time:'22:00'}); 139 140 for (let key in newStatus) { 141 console.log('FormExtensionAbility onChangeFormVisibility, key:' + key + ', value=' + newStatus[key]); 142 this.context.updateForm(key, obj2).then((data)=>{ 143 console.log('FormExtensionAbility context updateForm, data:' + data); 144 }).catch((error) => { 145 console.error('Operation updateForm failed. Cause: ' + error);}); 146 } 147 } 148} 149``` 150 151## onFormEvent 152 153onFormEvent(formId: string, message: string): void 154 155卡片提供方接收处理卡片事件的通知接口。 156 157**系统能力**：SystemCapability.Ability.Form 158 159**参数：** 160 161| 参数名 | 类型 | 必填 | 说明 | 162| ------- | ------ | ---- | ---------------------- | 163| formId | string | 是 | 请求触发事件的卡片标识。 | 164| message | string | 是 | 事件消息。 | 165 166**示例：** 167 168```ts 169export default class MyFormExtension extends FormExtensionAbility { 170 onFormEvent(formId, message) { 171 console.log('FormExtensionAbility onFormEvent, formId:' + formId + ', message:' + message); 172 } 173} 174``` 175 176## onRemoveForm 177 178onRemoveForm(formId: string): void 179 180卡片提供方接收销毁卡片的通知接口。 181 182**系统能力**：SystemCapability.Ability.Form 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| ------ | ------ | ---- | ------------------ | 188| formId | string | 是 | 请求销毁的卡片标识。 | 189 190**示例：** 191 192```ts 193export default class MyFormExtensionAbility extends FormExtensionAbility { 194 onRemoveForm(formId) { 195 console.log('FormExtensionAbility onRemoveForm, formId:' + formId); 196 } 197} 198``` 199 200## onConfigurationUpdate 201 202onConfigurationUpdate(newConfig: Configuration): void; 203 204当系统配置更新时调用。 205 206**系统能力**：SystemCapability.Ability.Form 207 208**参数：** 209 210| 参数名 | 类型 | 必填 | 说明 | 211| -------- | -------- | -------- | -------- | 212| newConfig | [Configuration](js-apis-application-configuration.md) | 是 | 表示需要更新的配置信息。 | 213 214**示例：** 215 216```ts 217class MyFormExtensionAbility extends FormExtensionAbility { 218 onConfigurationUpdate(config) { 219 console.log('onConfigurationUpdate, config:' + JSON.stringify(config)); 220 } 221} 222``` 223 224## onAcquireFormState 225 226onAcquireFormState?(want: Want): formInfo.FormState; 227 228卡片提供方接收查询卡片状态通知接口。默认返回卡片初始状态。 229 230**系统能力**：SystemCapability.Ability.Form 231 232**参数：** 233 234| 参数名 | 类型 | 必填 | 说明 | 235| -------- | -------- | -------- | -------- | 236| want | [Want](js-apis-application-want.md) | 是 | want表示获取卡片状态的描述。描述包括包名称、能力名称、模块名称、卡片名和卡片维度。 | 237 238**示例：** 239 240```ts 241import formInfo from '@ohos.app.form.formInfo'; 242class MyFormExtensionAbility extends FormExtensionAbility { 243 onAcquireFormState(want) { 244 console.log('FormExtensionAbility onAcquireFormState, want:' + want); 245 return formInfo.FormState.UNKNOWN; 246 } 247} 248``` 249 250## onShareForm 251 252onShareForm?(formId: string): { [key: string]: Object } 253 254卡片提供方接收卡片分享的通知接口。 255 256**系统接口**: 此接口为系统接口。 257 258**系统能力**：SystemCapability.Ability.Form 259 260**参数：** 261 262| 参数名 | 类型 | 必填 | 说明 | 263| -------- | -------- | -------- | -------- | 264| formId | string | 是 | 卡片标识。 | 265 266**返回值：** 267 268| 类型 | 说明 | 269| ------------------------------------------------------------ | ----------------------------------------------------------- | 270| {[key: string]: any} | 卡片要分享的数据，由开发者自行决定传入的键值对。 | 271 272**示例：** 273 274```ts 275class MyFormExtensionAbility extends FormExtensionAbility { 276 onShareForm(formId) { 277 console.log('FormExtensionAbility onShareForm, formId:' + formId); 278 let wantParams = { 279 'temperature':'20', 280 'time':'2022-8-8 09:59', 281 }; 282 return wantParams; 283 } 284} 285```