1# @ohos.app.form.formProvider (formProvider)(系统接口)
2
3FormProvider模块提供了卡片提供方相关接口的能力，开发者在开发卡片时，可通过该模块提供接口实现更新卡片、设置卡片更新时间、获取卡片信息、请求发布卡片等。
4
5> **说明：**
6>
7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8> 当前页面仅包含本模块的系统接口，其他公共接口参见[@ohos.app.form.formProvider (formProvider)](./js-apis-app-form-formProvider.md)。
9
10## 导入模块
11
12```ts
13import { formProvider } from '@kit.FormKit';
14```
15
16
17## requestPublishForm
18
19requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\<string>): void
20
21请求发布一张卡片到使用方。使用方通常为桌面，使用callback异步回调。
22
23**系统能力：** SystemCapability.Ability.Form
24
25**系统接口：** 此接口为系统接口。
26
27**参数：**
28
29| 参数名 | 类型                                                                    | 必填 | 说明             |
30| ------ | ---------------------------------------------------------------------- | ---- | ---------------- |
31| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md)                           | 是   | 发布请求，需包含以下字段。<br>abilityName: 目标卡片ability<br>parameters:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' |
32| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是   | 创建卡片的数据。 |
33| callback | AsyncCallback&lt;string&gt; | 是 | 回调函数，返回卡片标识。 |
34
35**错误码：**
36
37| 错误码ID | 错误信息 |
38| -------- | -------- |
39| 202 | The application is not a system application. |
40| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
41| 16500050 | IPC connection error. |
42| 16500100 | Failed to obtain the configuration information. |
43| 16501000 | An internal functional error occurred. |
44
45以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。
46
47**示例：**
48
49```ts
50import { formBindingData, formProvider } from '@kit.FormKit';
51import { Want } from '@kit.AbilityKit';
52import { BusinessError } from '@kit.BasicServicesKit';
53
54let want: Want = {
55  abilityName: 'FormAbility',
56  parameters: {
57    'ohos.extra.param.key.form_dimension': 2,
58    'ohos.extra.param.key.form_name': 'widget',
59    'ohos.extra.param.key.module_name': 'entry'
60  }
61};
62try {
63  let param: Record<string, string> = {
64    'temperature': '22c',
65    'time': '22:00'
66  }
67  let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param);
68  formProvider.requestPublishForm(want, obj, (error: BusinessError, data: string) => {
69    if (error) {
70      console.error(`callback error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
71      return;
72    }
73    console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
74  });
75} catch (error) {
76  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
77}
78```
79
80## requestPublishForm
81
82requestPublishForm(want: Want, callback: AsyncCallback&lt;string&gt;): void
83
84请求发布一张卡片到使用方。使用方通常为桌面，使用callback异步回调。
85
86**系统能力：** SystemCapability.Ability.Form
87
88**系统接口：** 此接口为系统接口。
89
90**参数：**
91
92| 参数名   | 类型                                | 必填 | 说明                                                         |
93| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ |
94| want     | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 发布请求，需包含以下字段。<br>abilityName: 目标卡片ability<br>parameters:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' |
95| callback | AsyncCallback&lt;string&gt;         | 是   |  回调函数，返回卡片标识。 |
96
97**错误码：**
98
99| 错误码ID | 错误信息 |
100| -------- | -------- |
101| 202 | The application is not a system application. |
102| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
103| 16500050 | IPC connection error. |
104| 16500100 | Failed to obtain the configuration information. |
105| 16501000 | An internal functional error occurred. |
106
107以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。
108
109**示例：**
110
111```ts
112import { formProvider } from '@kit.FormKit';
113import { Want } from '@kit.AbilityKit';
114import { BusinessError } from '@kit.BasicServicesKit';
115
116let want: Want = {
117  abilityName: 'FormAbility',
118  parameters: {
119    'ohos.extra.param.key.form_dimension': 2,
120    'ohos.extra.param.key.form_name': 'widget',
121    'ohos.extra.param.key.module_name': 'entry'
122  }
123};
124try {
125  formProvider.requestPublishForm(want, (error: BusinessError, data: string) => {
126    if (error) {
127      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
128      return;
129    }
130    console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
131  });
132} catch (error) {
133  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
134}
135```
136
137## requestPublishForm
138
139requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise&lt;string&gt;
140
141请求发布一张卡片到使用方。使用方通常为桌面，使用Promise异步回调。
142
143**系统能力：** SystemCapability.Ability.Form
144
145**系统接口：** 此接口为系统接口。
146
147**参数：**
148
149| 参数名          | 类型                                                         | 必填 | 说明                                                         |
150| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
151| want            | [Want](../apis-ability-kit/js-apis-app-ability-want.md)                          | 是   | 发布请求，需包含以下字段。<br>abilityName: 目标卡片ability<br>parameters:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' |
152| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 否   | 创建卡片的数据，默认为空，不提供创建卡片数据。                                      |
153
154**返回值：**
155
156| 类型          | 说明                                |
157| :------------ | :---------------------------------- |
158| Promise&lt;string&gt; | Promise对象。返回卡片标识。 |
159
160**错误码：**
161
162| 错误码ID | 错误信息 |
163| -------- | -------- |
164| 202 | The application is not a system application. |
165| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
166| 16500050 | IPC connection error. |
167| 16500100 | Failed to obtain the configuration information. |
168| 16501000 | An internal functional error occurred. |
169
170以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。
171
172**示例：**
173
174```ts
175import { formProvider } from '@kit.FormKit';
176import { Want } from '@kit.AbilityKit';
177import { BusinessError } from '@kit.BasicServicesKit';
178
179let want: Want = {
180  abilityName: 'FormAbility',
181  parameters: {
182    'ohos.extra.param.key.form_dimension': 2,
183    'ohos.extra.param.key.form_name': 'widget',
184    'ohos.extra.param.key.module_name': 'entry'
185  }
186};
187try {
188  formProvider.requestPublishForm(want).then((data: string) => {
189    console.log(`formProvider requestPublishForm success, form ID is : ${JSON.stringify(data)}`);
190  }).catch((error: BusinessError) => {
191    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
192  });
193} catch (error) {
194  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
195}
196```
197
198## isRequestPublishFormSupported
199
200isRequestPublishFormSupported(callback: AsyncCallback&lt;boolean&gt;): void
201
202查询是否支持发布一张卡片到使用方，使用callback异步回调。
203
204**系统接口：** 此接口为系统接口。
205
206**系统能力：** SystemCapability.Ability.Form
207
208**参数：**
209
210| 参数名 | 类型    | 必填 | 说明    |
211| ------ | ------ | ---- | ------- |
212| callback | AsyncCallback&lt;boolean&gt; | 是 | 回调函数。返回是否支持发布一张卡片到使用方。|
213
214**错误码：**
215
216| 错误码ID | 错误信息 |
217| -------- | -------- |
218| 202 | The application is not a system application. |
219| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
220| 16500050 | IPC connection error. |
221| 16501000 | An internal functional error occurred. |
222
223以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。
224
225**示例：**
226
227```ts
228import { formProvider } from '@kit.FormKit';
229import { Want } from '@kit.AbilityKit';
230import { BusinessError } from '@kit.BasicServicesKit';
231
232try {
233  formProvider.isRequestPublishFormSupported((error: BusinessError, isSupported: boolean) => {
234    if (error) {
235      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
236    } else {
237      if (isSupported) {
238        let want: Want = {
239          abilityName: 'FormAbility',
240          parameters: {
241            'ohos.extra.param.key.form_dimension': 2,
242            'ohos.extra.param.key.form_name': 'widget',
243            'ohos.extra.param.key.module_name': 'entry'
244          }
245        };
246        try {
247          formProvider.requestPublishForm(want, (error: BusinessError, data: string) => {
248            if (error) {
249              console.error(`callback error, code: ${error.code}, message: ${error.message})`);
250              return;
251            }
252            console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
253          });
254        } catch (error) {
255          console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
256        }
257      }
258    }
259  });
260} catch (error) {
261  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
262}
263```
264
265## isRequestPublishFormSupported
266
267isRequestPublishFormSupported(): Promise&lt;boolean&gt;
268
269查询是否支持发布一张卡片到使用方，使用Promise异步回调。
270
271**系统接口：** 此接口为系统接口。
272
273**系统能力：** SystemCapability.Ability.Form
274
275**返回值：**
276
277| 类型          | 说明                                |
278| :------------ | :---------------------------------- |
279| Promise&lt;boolean&gt; | Promise对象。返回是否支持发布一张卡片到使用方。 |
280
281**错误码：**
282
283| 错误码ID | 错误信息 |
284| -------- | -------- |
285| 202 | The application is not a system application. |
286| 16500050 | IPC connection error. |
287| 16501000 | An internal functional error occurred. |
288
289以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。
290
291**示例：**
292
293```ts
294import { formProvider } from '@kit.FormKit';
295import { Want } from '@kit.AbilityKit';
296import { BusinessError } from '@kit.BasicServicesKit';
297
298try {
299  formProvider.isRequestPublishFormSupported().then((isSupported: boolean) => {
300    if (isSupported) {
301      let want: Want = {
302        abilityName: 'FormAbility',
303        parameters: {
304          'ohos.extra.param.key.form_dimension': 2,
305          'ohos.extra.param.key.form_name': 'widget',
306          'ohos.extra.param.key.module_name': 'entry'
307        }
308      };
309      try {
310        formProvider.requestPublishForm(want).then((data: string) => {
311          console.log(`formProvider requestPublishForm success, form ID is : ${JSON.stringify(data)}`);
312        }).catch((error: BusinessError) => {
313          console.error(`promise error, code: ${error.code}, message: ${error.message})`);
314        });
315      } catch (error) {
316        console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
317      }
318    }
319  }).catch((error: BusinessError) => {
320    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
321  });
322} catch (error) {
323  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
324}
325```