• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。
38
39| 错误码ID | 错误信息 |
40| -------- | -------- |
41| 202 | The application is not a system application. |
42| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
43| 16500050 | IPC connection error. |
44| 16500100 | Failed to obtain the configuration information. |
45| 16501000 | An internal functional error occurred. |
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以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。
100
101| 错误码ID | 错误信息 |
102| -------- | -------- |
103| 202 | The application is not a system application. |
104| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
105| 16500050 | IPC connection error. |
106| 16500100 | Failed to obtain the configuration information. |
107| 16501000 | An internal functional error occurred. |
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以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。
163
164| 错误码ID | 错误信息 |
165| -------- | -------- |
166| 202 | The application is not a system application. |
167| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
168| 16500050 | IPC connection error. |
169| 16500100 | Failed to obtain the configuration information. |
170| 16501000 | An internal functional error occurred. |
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; | 是 | 返回查询结果的回调函数。<br>true: 表示可以添加卡片到卡片使用方。<br>false: 表示不可以添加卡片到卡片使用方。|
213
214**错误码：**
215
216以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。
217
218| 错误码ID | 错误信息 |
219| -------- | -------- |
220| 202 | The application is not a system application. |
221| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
222| 16500050 | IPC connection error. |
223| 16501000 | An internal functional error occurred. |
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对象。返回是否可以添加卡片到卡片使用方的结果。<br>true: 表示可以添加卡片到卡片使用方。<br>false: 表示不可以添加卡片到卡片使用方。|
280
281**错误码：**
282
283以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。
284
285| 错误码ID | 错误信息 |
286| -------- | -------- |
287| 202 | The application is not a system application. |
288| 16500050 | IPC connection error. |
289| 16501000 | An internal functional error occurred. |
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```
326
327## activateSceneAnimation<sup>20+</sup>
328
329activateSceneAnimation(formId: string): Promise&lt;void&gt;
330
331互动卡片请求状态切换到激活态，只针对[场景动效类型互动卡片](../../form/arkts-ui-widget-configuration.md#sceneanimationparams标签)生效，使用Promise异步回调。互动卡片状态分为激活态和非激活态，非激活态下，互动卡片同普通卡片一致；激活态下，互动卡片支持拉起卡片提供方所开发的LiveFormExtensionAbility进程，实现互动卡片动效。
332
333**系统能力：** SystemCapability.Ability.Form
334
335**系统接口：** 此接口为系统接口。
336
337**参数：**
338
339| 参数名 | 类型    | 必填 | 说明    |
340| ------ | ------ | ---- |-------|
341| formId | string | 是 | 卡片id。 |
342
343**返回值：**
344
345| 类型 | 说明 |
346| -------- | -------- |
347| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
348
349**错误码：**
350
351以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。
352
353| 错误码ID | 错误信息 |
354| -------- | -------- |
355| 202 | The application is not a system application. |
356| 801 | Capability not supported.function activateSceneAnimation can not work correctly due to limited device capabilities. |
357| 16500050 | IPC connection error. |
358| 16500060 | Service connection error. |
359| 16500100 | Failed to obtain the configuration information. |
360| 16501000 | An internal functional error occurred. |
361| 16501001 | The ID of the form to be operated does not exist. |
362| 16501003 | The form cannot be operated by the current application. |
363| 16501011 | The form can not support this operation. |
364
365**示例：**
366
367```ts
368import { formProvider } from '@kit.FormKit';
369import { BusinessError } from '@kit.BasicServicesKit';
370
371let formId: string = '12400633174999288';
372
373try {
374  formProvider.activateSceneAnimation(formId).then(() => {
375    console.info('activateSceneAnimation succeed.');
376  }).catch((error: BusinessError) => {
377    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
378  });
379} catch (error) {
380  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
381}
382```
383
384## deactivateSceneAnimation<sup>20+</sup>
385
386deactivateSceneAnimation(formId: string): Promise&lt;void&gt;
387
388互动卡片请求切换到非激活态，只针对[场景动效类型互动卡片](../../form/arkts-ui-widget-configuration.md#sceneanimationparams标签)生效，使用Promise异步回调。互动卡片状态分为激活态和非激活态，非激活态下，互动卡片同普通卡片一致；激活态下，互动卡片支持拉起卡片提供方所开发的LiveFormExtensionAbility进程，实现互动卡片动效。
389
390**系统能力：** SystemCapability.Ability.Form
391
392**系统接口：** 此接口为系统接口。
393
394**参数：**
395
396| 参数名 | 类型    | 必填 | 说明    |
397| ------ | ------ | ---- |-------|
398| formId | string | 是 | 卡片id。|
399
400**返回值：**
401
402| 类型 | 说明 |
403| -------- | -------- |
404| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
405
406**错误码：**
407
408以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。
409
410| 错误码ID | 错误信息 |
411| -------- | -------- |
412| 202 | The application is not a system application. |
413| 801 | Capability not supported.function deactivateSceneAnimation can not work correctly due to limited device capabilities. |
414| 16500050 | IPC connection error. |
415| 16500060 | Service connection error. |
416| 16500100 | Failed to obtain the configuration information. |
417| 16501000 | An internal functional error occurred. |
418| 16501001 | The ID of the form to be operated does not exist. |
419| 16501003 | The form cannot be operated by the current application. |
420| 16501011 | The form can not support this operation. |
421
422**示例：**
423
424```ts
425import { formProvider } from '@kit.FormKit';
426import { BusinessError } from '@kit.BasicServicesKit';
427
428let formId: string = '12400633174999288';
429
430try {
431  formProvider.deactivateSceneAnimation(formId).then(() => {
432    console.info('deactivateSceneAnimation succeed.');
433  }).catch((error: BusinessError) => {
434    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
435  });
436} catch (error) {
437  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
438}
439```