From 5883e709b12bddb8e1ffe8f35cace0235fd9bea0 Mon Sep 17 00:00:00 2001 From: wusongqing Date: Mon, 4 Jul 2022 17:53:18 +0800 Subject: [PATCH] update docs against 4972 Signed-off-by: wusongqing --- .../reference/apis/js-apis-formprovider.md | 335 ++++++++++++++++-- 1 file changed, 311 insertions(+), 24 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-formprovider.md b/en/application-dev/reference/apis/js-apis-formprovider.md index 7ff3e5f3d8..0637af7ceb 100644 --- a/en/application-dev/reference/apis/js-apis-formprovider.md +++ b/en/application-dev/reference/apis/js-apis-formprovider.md @@ -1,9 +1,10 @@ # FormProvider -> **NOTE**
-> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +The **FormProvider** module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and release a widget release. -Provides APIs related to the widget provider. +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -27,11 +28,11 @@ SystemCapability.Ability.Form **Parameters** - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------------------------------------- | - | formId | string | Yes | ID of a widget. | - | minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | - | callback | AsyncCallback<void> | Yes| Callback used to return the result.| +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------- | +| formId | string | Yes | ID of a widget. | +| minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** @@ -56,16 +57,16 @@ SystemCapability.Ability.Form **Parameters** - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------------------------------------- | - | formId | string | Yes | ID of a widget. | - | minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------- | +| formId | string | Yes | ID of a widget. | +| minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | **Return value** - | Type | Description | - | ------------- | ---------------------------------- | - | Promise\ |Promise used to return the result. | +| Type | Description | +| ------------- | ---------------------------------- | +| Promise\ |Promise used to return the result. | **Example** @@ -90,11 +91,11 @@ SystemCapability.Ability.Form **Parameters** - | Name| Type | Mandatory| Description | - | ------ | ---------------------------------------------------------------------- | ---- | ---------------- | - | formId | string | Yes | ID of the widget to update.| - | formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. | - | callback | AsyncCallback<void> | Yes| Callback used to return the result.| +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | +| formId | string | Yes | ID of the widget to update.| +| formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** @@ -121,10 +122,10 @@ SystemCapability.Ability.Form **Parameters** - | Name| Type | Mandatory| Description | - | ------ | ---------------------------------------------------------------------- | ---- | ---------------- | - | formId | string | Yes | ID of the widget to update.| - | formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. | +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | +| formId | string | Yes | ID of the widget to update.| +| formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. | **Return value** @@ -144,3 +145,289 @@ SystemCapability.Ability.Form console.log('formProvider updateForm, error:' + JSON.stringify(error)); }); ``` + +## getFormsInfo9+ + +getFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void; + +Obtains the application's widget information on the device. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| + +**Example** + +```js +formProvider.getFormsInfo((error, data) => { + if (error.code) { + console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); + } +}); +``` +## getFormsInfo9+ + +getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void; + +Obtains the application's widget information that meets a filter criterion on the device. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| filter | formInfo.FormInfoFilter | Yes| Filter criterion.| +| callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| + +**Example** + +```js +const filter : formInfo.FormInfoFilter = { + moduleName : "entry" +}; +formProvider.getFormsInfo(filter, (error, data) => { + if (error.code) { + console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); + } +}); +``` + +## getFormsInfo9+ + +getFormsInfo(filter?: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>>; + +Obtains the application's widget information on the device. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| filter | formInfo.FormInfoFilter | No| Filter criterion.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Promise used to return the widget information.| + +**Example** + +```js +const filter : formInfo.FormInfoFilter = { + moduleName : "entry" +}; +formProvider.getFormsInfo(filter).then((data) => { + console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); +}).catch((error) => { + console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); +}); +``` + +## requestPublishForm9+ + +requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback<string>): <void>; + +Requests to publish a widget carrying data to the widget host. This API uses an asynchronous callback to return the result. + +**System capability** + +SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | +| want | [Want](js-apis-application-Want.md) | Yes | Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data used for creating the widget.| +| callback | AsyncCallback<string> | Yes| Callback used to return the widget ID.| + +**Example** + + ```js + import formBindingData from '@ohos.application.formBindingData'; + var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } + }; + let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + formProvider.requestPublishForm(want, obj, (error, data) => { + if (error.code) { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + } else { + console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); + } + }); + ``` + +## requestPublishForm9+ + +requestPublishForm(want: Want, callback: AsyncCallback<string>): <void>; + +Requests to publish a widget to the widget host. This API uses an asynchronous callback to return the result. + +**System capability** + +SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | +| want | [Want](js-apis-application-Want.md) | Yes | Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| callback | AsyncCallback<string> | Yes | Callback used to return the widget ID. | + +**Example** + + ```js + var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } + }; + formProvider.requestPublishForm(want, (error, data) => { + if (error.code) { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + } else { + console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); + } + }); + ``` + +## requestPublishForm9+ + +requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise<string>; + +Requests to publish a widget to the widget host. This API uses a promise to return the result. + +**System capability** + +SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| want | [Want](js-apis-application-Want.md) | Yes | Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | No | Data used for creating the widget. | + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<string> | Promise used to return the widget ID.| + +**Example** + + ```js + var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } + }; + formProvider.requestPublishForm(want).then((data) => { + console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data)); + }).catch((error) => { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + }); + ``` + +## isRequestPublishFormSupported9+ + +isRequestPublishFormSupported(callback: AsyncCallback<boolean>): void; + +Checks whether a widget can be published to the widget host. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| + +**Example** + +```js +formProvider.isRequestPublishFormSupported((error, isSupported) => { + if (error.code) { + console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); + } else { + if (isSupported) { + var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } + }; + formProvider.requestPublishForm(want, (error, data) => { + if (error.code) { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + } else { + console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); + } + }); + } + } +}); +``` + +## isRequestPublishFormSupported9+ + +isRequestPublishFormSupported(): Promise<boolean>; + +Checks whether a widget can be published to the widget host. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<boolean> | Promise used to return the result.| + +**Example** + +```js +formProvider.isRequestPublishFormSupported().then((isSupported) => { + if (isSupported) { + var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } + }; + formProvider.requestPublishForm(want).then((data) => { + console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data)); + }).catch((error) => { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + }); + } +}).catch((error) => { + console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); +}); +``` -- GitLab