• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.app.form.formBindingData (formBindingData)
2
3<!--Kit: Form Kit-->
4<!--Subsystem: Ability-->
5<!--Owner: @cx983299475-->
6<!--Designer: @xueyulong-->
7<!--Tester: @chenmingze-->
8<!--Adviser: @Brilliantry_Rui-->
9The **FormBindingData** module provides APIs for widget data binding. You can use the APIs to create a **FormBindingData** object and obtain related information.
10
11> **NOTE**
12>
13> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
14
15## Modules to Import
16
17```ts
18import { formBindingData } from '@kit.FormKit';
19```
20
21
22## ProxyData<sup>10+</sup>
23
24Defines the subscription information about the widget update by proxy.
25
26**Model restriction**: This API can be used only in the stage model.
27
28**Atomic service API**: This API can be used in atomic services since API version 11.
29
30**System capability**: SystemCapability.Ability.Form
31
32| Name| Type| Mandatory| Description|
33| -------- | -------- | -------- | -------- |
34| key<sup>10+</sup> | string | Yes| Subscriber ID of the widget update by proxy. The value is the same as that of the data publisher.|
35| subscriberId<sup>10+</sup> | string | No| Subscription condition of the widget update by proxy. The default value is the current widget ID (specified by **formId**).|
36
37
38## FormBindingData
39
40Describes a **FormBindingData** object.
41
42**Atomic service API**: This API can be used in atomic services since API version 11.
43
44**System capability**: SystemCapability.Ability.Form
45
46| Name| Type| Mandatory| Description|
47| -------- | -------- | -------- | -------- |
48| data | Object | Yes| Data to be displayed on the widget. The value can be an object containing multiple key-value pairs or a string in JSON format.|
49| proxies<sup>10+</sup> | Array<[ProxyData](#proxydata10)> | No| Subscription information of the widget update by proxy. The default value is an empty array.<br>**Model restriction**: This API can be used only in the stage model.<br>|
50
51## formBindingData.createFormBindingData
52
53createFormBindingData(obj?: Object | string): FormBindingData
54
55Creates a **FormBindingData** object.
56
57**Atomic service API**: This API can be used in atomic services since API version 11.
58
59**System capability**: SystemCapability.Ability.Form
60
61**Parameters**
62
63| Name| Type          | Mandatory| Description                                                        |
64| ------ | -------------- | ---- | ------------------------------------------------------------ |
65| obj    | Object\|string | No  | Data to be displayed on the widget. The value can be an object containing multiple key-value pairs or a string in JSON format. The image data is identified by **'formImages'**, and the content is multiple key-value pairs, each of which consists of an image identifier and image file descriptor. The final format is {'formImages': {'key1': fd1, 'key2': fd2}}.<br>**NOTE**<br>During [widget update](../../form/arkts-ui-widget-interaction-overview.md), when the widget UI receives widget data through @LocalStorageProp, the **FormBindingData** object is serialized, that is, the widget data is converted into the string type. Since API version 20, the maximum number of image files is 20, and the total memory size of all images cannot exceed 10 MB. If the total memory size exceeds 10 MB, the images will be displayed abnormally. In API version 19 and earlier versions, the maximum number of image files is 5, and the maximum memory size of each image is 2 MB.|
66
67
68**Return value**
69
70| Type                               | Description                                   |
71| ----------------------------------- | --------------------------------------- |
72| [FormBindingData](#formbindingdata) | **FormBindingData** object created based on the passed data.|
73
74**Error codes**
75
76For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
77
78| ID| Error Message|
79| -------- | -------- |
80| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
81
82
83**Example**
84
85```ts
86import { formBindingData } from '@kit.FormKit';
87import { fileIo } from '@kit.CoreFileKit';
88import { common } from '@kit.AbilityKit';
89@Entry
90@Component
91struct Index {
92  content = this.getUIContext().getHostContext() as common.UIAbilityContext;
93  pathDir: string = this.content.filesDir;
94  createFormBindingData() {
95    try {
96      let filePath = this.pathDir + "/form.png";
97      let file = fileIo.openSync(filePath);
98      let formImagesParam: Record<string, number> = {
99        'image': file.fd
100      };
101      let createFormBindingDataParam: Record<string, string | Record<string, number>> = {
102        'name': '21°',
103        'imgSrc': 'image',
104        'formImages': formImagesParam
105      };
106      formBindingData.createFormBindingData(createFormBindingDataParam);
107    } catch (error) {
108      console.error(`catch error, error: ${JSON.stringify(error)}`);
109    }
110  }
111  build() {
112    Button('createFormBindingData')
113      .onClick((event: ClickEvent)=>{
114        this.createFormBindingData();
115      })
116  }
117}
118```
119