diff --git a/en/application-dev/ability/fa-formability.md b/en/application-dev/ability/fa-formability.md index ac0e7f8a14081622fdf2e7214ecae56fc9bc07d5..833890df17b8f5747b85b09ea09e2c470419fa67 100644 --- a/en/application-dev/ability/fa-formability.md +++ b/en/application-dev/ability/fa-formability.md @@ -3,20 +3,20 @@ ## Widget Overview A widget is a set of UI components used to display important information or operations for an application. It provides users with direct access to a desired application service, without requiring them to open the application. -A widget displays brief information about an application on the UI of another application (host application, currently system applications only) and provides basic interactive features such as opening a UI page or sending a message. The widget client is responsible for displaying the widget. +A widget displays brief information about an application on the UI of another application (host application, currently system applications only) and provides basic interactive features such as opening a UI page or sending a message. The widget host is responsible for displaying the widget. Basic concepts: - Widget provider The widget provider is an atomic service that provides the content to be displayed. It controls the display content, component layout, and component click events of a widget. -- Widget client - The widget client is an application that displays the widget content and controls the position where the widget is displayed in the host application. +- Widget host + The widget host is an application that displays the widget content and controls the position where the widget is displayed in the host application. - Widget Manager The Widget Manager is a resident agent that manages widgets added to the system and provides functions such as periodic widget update. > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** -> The widget client and provider do not keep running all the time. The Widget Manager starts the widget provider to obtain widget information when a widget is added, deleted, or updated. +> The widget host and provider do not keep running all the time. The Widget Manager starts the widget provider to obtain widget information when a widget is added, deleted, or updated. -You only need to develop widget content as the widget provider. The system automatically handles the work done by the widget client and Widget Manager. +You only need to develop widget content as the widget provider. The system automatically handles the work done by the widget host and Widget Manager. The widget provider controls the widget content to display, component layout, and click events bound to components. @@ -85,11 +85,11 @@ To create a widget in the FA model, you need to implement the lifecycles of **Li return formData; }, onCastToNormal(formId) { - // Called when the widget client converts the temporary widget into a normal one. The widget provider should do something to respond to the conversion. + // Called when the widget host converts the temporary widget into a normal one. The widget provider should do something to respond to the conversion. console.log('FormAbility onCastToNormal'); }, onUpdate(formId) { - // To support scheduled update, periodic update, or update requested by the widget client for a widget, override this method for data update. + // To support scheduled update, periodic update, or update requested by the widget host for a widget, override this method for data update. console.log('FormAbility onUpdate'); let obj = { "title": "titleOnUpdate", @@ -101,7 +101,7 @@ To create a widget in the FA model, you need to implement the lifecycles of **Li }); }, onVisibilityChange(newStatus) { - // Called when the widget client initiates an event about visibility changes. The widget provider should do something to respond to the notification. + // Called when the widget host initiates an event about visibility changes. The widget provider should do something to respond to the notification. console.log('FormAbility onVisibilityChange'); }, onEvent(formId, message) { @@ -233,13 +233,13 @@ You should override **onDestroy** to delete widget data. For details about the persistence method, see [Lightweight Data Store Development](../database/database-preference-guidelines.md). -Note that the **Want** passed by the widget client to the widget provider contains a temporary flag, indicating whether the requested widget is a temporary one. +Note that the **Want** passed by the widget host to the widget provider contains a temporary flag, indicating whether the requested widget is a temporary one. -Normal widget: a widget that will be persistently used by the widget client +Normal widget: a widget that will be persistently used by the widget host -Temporary widget: a widget that is temporarily used by the widget client +Temporary widget: a widget that is temporarily used by the widget host -Data of a temporary widget is not persistently stored. If the widget framework is killed and restarted, data of a temporary widget will be deleted. However, the widget provider is not notified of which widget is deleted, and still keeps the data. Therefore, the widget provider should implement data clearing. In addition, the widget client may convert a temporary widget into a normal one. If the conversion is successful, the widget provider should process the widget ID and store the data persistently. This prevents the widget provider from deleting persistent data when clearing temporary widgets. +Data of a temporary widget is not persistently stored. If the widget framework is killed and restarted, data of a temporary widget will be deleted. However, the widget provider is not notified of which widget is deleted, and still keeps the data. Therefore, the widget provider should implement data clearing. In addition, the widget host may convert a temporary widget into a normal one. If the conversion is successful, the widget provider should process the widget ID and store the data persistently. This prevents the widget provider from deleting persistent data when clearing temporary widgets. ### Developing the Widget UI Page You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programmed widget. diff --git a/en/application-dev/ability/stage-formextension.md b/en/application-dev/ability/stage-formextension.md index 825412ca63c57ae1ad907bfee19eadc33d1202b5..9bdce67b2ce4eef4825079e6cf07086280b85466 100644 --- a/en/application-dev/ability/stage-formextension.md +++ b/en/application-dev/ability/stage-formextension.md @@ -4,21 +4,21 @@ A widget is a set of UI components used to display important information or operations for an application. It provides users with direct access to a desired application service, without requiring them to open the application. -A widget displays brief information about an application on the UI of another application (host application, currently system applications only) and provides basic interactive features such as opening a UI page or sending a message. The widget client is responsible for displaying the service widget. +A widget displays brief information about an application on the UI of another application (host application, currently system applications only) and provides basic interactive features such as opening a UI page or sending a message. The widget host is responsible for displaying the service widget. Basic concepts: - Widget provider The widget provider is an atomic service that provides the content to be displayed. It controls the display content, component layout, and component click events of a widget. -- Widget client - The widget client is an application that displays the widget content and controls the position where the widget is displayed in the host application. +- Widget host + The widget host is an application that displays the widget content and controls the position where the widget is displayed in the host application. - Widget Manager The Widget Manager is a resident agent that manages widgets added to the system and provides functions such as periodic widget update. > ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** -> The widget client and provider do not keep running all the time. The Widget Manager starts the widget provider to obtain widget information when a widget is added, deleted, or updated. +> The widget host and provider do not keep running all the time. The Widget Manager starts the widget provider to obtain widget information when a widget is added, deleted, or updated. -You only need to develop widget content as the widget provider. The system automatically handles the work done by the widget client and Widget Manager. +You only need to develop widget content as the widget provider. The system automatically handles the work done by the widget host and Widget Manager. The widget provider controls the widget content to display, component layout, and click events bound to components. @@ -97,11 +97,11 @@ To create a widget in the stage model, you need to implement the lifecycle callb return formData; } onCastToNormal(formId) { - // Called when the widget client converts the temporary widget into a normal one. The widget provider should do something to respond to the conversion. + // Called when the widget host converts the temporary widget into a normal one. The widget provider should do something to respond to the conversion. console.log('FormAbility onCastToNormal'); } onUpdate(formId) { - // To support scheduled update, periodic update, or update requested by the widget client for a widget, override this method for data update. + // To support scheduled update, periodic update, or update requested by the widget host for a widget, override this method for data update. console.log('FormAbility onUpdate'); let obj = { "title": "titleOnUpdate", @@ -113,7 +113,7 @@ To create a widget in the stage model, you need to implement the lifecycle callb }); } onVisibilityChange(newStatus) { - // Called when the widget client initiates an event about visibility changes. The widget provider should do something to respond to the notification. + // Called when the widget host initiates an event about visibility changes. The widget provider should do something to respond to the notification. console.log('FormAbility onVisibilityChange'); } onEvent(formId, message) { @@ -246,13 +246,13 @@ You should override **onDestroy** to delete widget data. For details about the persistence method, see [Lightweight Data Store Development](../database/database-preference-guidelines.md). -Note that the **Want** passed by the widget client to the widget provider contains a temporary flag, indicating whether the requested widget is a temporary one. +Note that the **Want** passed by the widget host to the widget provider contains a temporary flag, indicating whether the requested widget is a temporary one. -Normal widget: a widget that will be persistently used by the widget client +Normal widget: a widget that will be persistently used by the widget host -Temporary widget: a widget that is temporarily used by the widget client +Temporary widget: a widget that is temporarily used by the widget host -Data of a temporary widget is not persistently stored. If the widget framework is killed and restarted, data of a temporary widget will be deleted. However, the widget provider is not notified of which widget is deleted, and still keeps the data. Therefore, the widget provider should implement data clearing. In addition, the widget client may convert a temporary widget into a normal one. If the conversion is successful, the widget provider should process the widget ID and store the data persistently. This prevents the widget provider from deleting persistent data when clearing temporary widgets. +Data of a temporary widget is not persistently stored. If the widget framework is killed and restarted, data of a temporary widget will be deleted. However, the widget provider is not notified of which widget is deleted, and still keeps the data. Therefore, the widget provider should implement data clearing. In addition, the widget host may convert a temporary widget into a normal one. If the conversion is successful, the widget provider should process the widget ID and store the data persistently. This prevents the widget provider from deleting persistent data when clearing temporary widgets. ### Developing the Widget UI Page You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programmed widget. diff --git a/en/application-dev/reference/apis/js-apis-formhost.md b/en/application-dev/reference/apis/js-apis-formhost.md new file mode 100644 index 0000000000000000000000000000000000000000..8e890a787adc0cb6b69cbfed2ecbbfabb1ef370d --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-formhost.md @@ -0,0 +1,945 @@ +# FormHost + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **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. + +Provides APIs related to the widget host. + +## Modules to Import + +``` +import formHost from '@ohos.application.formHost'; +``` + +## Required Permissions + +ohos.permission.REQUIRE_FORM + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +## deleteForm + +deleteForm(formId: string, callback: AsyncCallback<void>): void; + +Deletes a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.deleteForm(formId, (error, data) => { + if (error) { + console.log('formHost deleteForm, error:' + error.code); + } + }); + ``` + +## deleteForm + +deleteForm(formId: string): Promise<void>; + +Deletes a widget. This API uses a promise to return the result. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.deleteForm(formId).catch((error) => { + console.log('formProvider deleteForm, error:' + JSON.stringify(error)); + }); + ``` + +## releaseForm + +releaseForm(formId: string, callback: AsyncCallback<void>): void; + +Releases a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager still retains the widget cache and storage information. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.releaseForm(formId, (error, data) => { + if (error) { + console.log('formHost releaseForm, error:' + error.code); + } + }); + ``` + +## releaseForm + +releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void; + +Releases a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and determines whether to retain the cache information based on the setting. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name | Type | Mandatory| Description | + | -------------- | ------ | ---- | ----------- | + | formId | string | Yes | ID of a widget. | + | isReleaseCache | boolean | Yes | Whether to release the cache.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.releaseForm(formId, true, (error, data) => { + if (error) { + console.log('formHost releaseForm, error:' + error.code); + } + }); + ``` + +## releaseForm + +releaseForm(formId: string, isReleaseCache?: boolean): Promise<void>; + +Releases a widget. This API uses a promise to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and determines whether to retain the cache information based on the setting. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name | Type | Mandatory| Description | + | -------------- | ------ | ---- | ----------- | + | formId | string | Yes | ID of a widget. | + | isReleaseCache | boolean | No | Whether to release the cache.| + + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.releaseForm(formId, true).catch((error) => { + console.log('formProvider releaseForm, error:' + JSON.stringify(error)); + }); + ``` + +## requestForm + +requestForm(formId: string, callback: AsyncCallback<void>): void; + +Requests a widget update. This API uses an asynchronous callback to return the result. + +**System capability** + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.requestForm(formId, (error, data) => { + if (error) { + console.log('formHost requestForm, error:' + error.code); + } + }); + ``` + +## requestForm + +requestForm(formId: string): Promise<void>; + +Requests a widget update. This API uses a promise to return the result. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.requestForm(formId).catch((error) => { + console.log('formProvider requestForm, error:' + JSON.stringify(error)); + }); + ``` + +## castTempForm + +castTempForm(formId: string, callback: AsyncCallback<void>): void; + +Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.castTempForm(formId, (error, data) => { + if (error) { + console.log('formHost castTempForm, error:' + error.code); + } + }); + ``` + +## castTempForm + +castTempForm(formId: string): Promise<void>; + +Converts a temporary widget to a normal one. This API uses a promise to return the result. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.castTempForm(formId).catch((error) => { + console.log('formProvider castTempForm, error:' + JSON.stringify(error)); + }); + ``` + +## notifyVisibleForms + +notifyVisibleForms(formId: string, callback: AsyncCallback<void>): void; + +Instructs the widget framework to make a widget visible. This API uses an asynchronous callback to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.notifyVisibleForms(formId, (error, data) => { + if (error) { + console.log('formHost notifyVisibleForms, error:' + error.code); + } + }); + ``` + +## notifyVisibleForms + +notifyVisibleForms(formId: string): Promise<void>; + +Instructs the widget framework to make a widget visible. This API uses a promise to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.notifyVisibleForms(formId).catch((error) => { + console.log('formProvider notifyVisibleForms, error:' + JSON.stringify(error)); + }); + ``` + +## notifyInvisibleForms + +notifyInvisibleForms(formId: string, callback: AsyncCallback<void>): void; + +Instructs the widget framework to make a widget invisible. This API uses an asynchronous callback to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.notifyInvisibleForms(formId, (error, data) => { + if (error) { + console.log('formHost notifyInvisibleForms, error:' + error.code); + } + }); + ``` + +## notifyInvisibleForms + +notifyInvisibleForms(formId: string): Promise<void>; + +Instructs the widget framework to make a widget invisible. This API uses a promise to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.notifyInvisibleForms(formId).catch((error) => { + console.log('formProvider notifyInvisibleForms, error:' + JSON.stringify(error)); + }); + ``` + +## enableFormsUpdate + +enableFormsUpdate(formId: string, callback: AsyncCallback<void>): void; + +Instructs the widget framework to make a widget to be updatable. This API uses an asynchronous callback to return the result. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.enableFormsUpdate(formId, (error, data) => { + if (error) { + console.log('formHost enableFormsUpdate, error:' + error.code); + } + }); + ``` + +## enableFormsUpdate + +enableFormsUpdate(formId: string): Promise<void>; + +Instructs the widget framework to make a widget to be updatable. This API uses a promise to return the result. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.enableFormsUpdate(formId).catch((error) => { + console.log('formProvider enableFormsUpdate, error:' + JSON.stringify(error)); + }); + ``` + +## disableFormsUpdate + +disableFormsUpdate(formId: string, callback: AsyncCallback<void>): void; + +Instructs the widget framework to make a widget not to be updatable. This API uses an asynchronous callback to return the result. After this API is called, the widget is in the disabled state and cannot receive updates from the widget provider. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.disableFormsUpdate(formId, (error, data) => { + if (error) { + console.log('formHost disableFormsUpdate, error:' + error.code); + } + }); + ``` + +## disableFormsUpdate + +disableFormsUpdate(formId: string): Promise<void>; + +Instructs the widget framework to make a widget not to be updatable. This API uses a promise to return the result. After this API is called, the widget is in the disabled state and cannot receive updates from the widget provider. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formId | string | Yes | ID of a widget.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.disableFormsUpdate(formId).catch((error) => { + console.log('formProvider disableFormsUpdate, error:' + JSON.stringify(error)); + }); + ``` + +## isSystemReady + +isSystemReady(callback: AsyncCallback<void>): void; + +Checks whether the system is ready. This API uses an asynchronous callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.isSystemReady((error, data) => { + if (error) { + console.log('formHost isSystemReady, error:' + error.code); + } + }); + ``` + +## isSystemReady + +isSystemReady(): Promise<void>; + +Checks whether the system is ready. This API uses a promise to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formId = "12400633174999288"; + formHost.isSystemReady().catch((error) => { + console.log('formProvider isSystemReady, error:' + JSON.stringify(error)); + }); + ``` + +## getAllFormsInfo + +getAllFormsInfo(callback: AsyncCallback<Array<FormInfo>>): void; + +Obtains the widget information provided by all applications 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 + formHost.getAllFormsInfo((error, data) => { + if (error) { + console.log('formHost getAllFormsInfo, error:' + error.code); + } + }); + ``` + +## getAllFormsInfo + +getAllFormsInfo(): Promise<Array<FormInfo>>; + +Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Promise used to return the widget information.| + +**Example** + + ```js + formHost.getAllFormsInfo().catch((error) => { + console.log('formProvider getAllFormsInfo, error:' + JSON.stringify(error)); + }); + ``` + +## getFormsInfo + +getFormsInfo(bundleName: string, callback: AsyncCallback<Array<FormInfo>>): void; + +Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | bundleName | string | Yes| Bundle name of the target application.| + | callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| + +**Example** + + ```js + formHost.getFormsInfo("com.example.ohos.accountjsdemo", (error, data) => { + if (error) { + console.log('formHost getFormsInfo, error:' + error.code); + } + }); + ``` + +## getFormsInfo + +getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<FormInfo>>): void; + +Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | bundleName | string | Yes| Bundle name of the target application.| + | moduleName | string | Yes| Module name.| + | callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| + +**Example** + + ```js + formHost.getFormsInfo("com.example.ohos.accountjsdemo", (error, data) => { + if (error) { + console.log('formHost getFormsInfo, error:' + error.code); + } + }); + ``` + +## getFormsInfo + +getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<FormInfo>>; + +Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | bundleName | string | Yes| Bundle name of the target application.| + | moduleName | string | No| Module name.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Promise used to return the widget information.| + +**Example** + + ```js + formHost.getAllFormsInfo().catch((error) => { + console.log('formProvider getAllFormsInfo, error:' + JSON.stringify(error)); + }); + ``` + +## deleteInvalidForms + +deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void; + +Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formIds | Array<string> | Yes | List of widget IDs.| + | callback | AsyncCallback<number> | Yes| Callback used to return the number of widgets deleted.| + +**Example** + + ```js + var formIds = new Array("12400633174999288", "12400633174999289"); + formHost.deleteInvalidForms(formIds, (error, data) => { + if (error) { + console.log('formHost deleteInvalidForms, error:' + error.code); + } + }); + ``` + +## deleteInvalidForms + +function deleteInvalidForms(formIds: Array<string>): Promise<number>; + +Deletes invalid widgets from the list. This API uses a promise to return the result. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<number> | Promise used to return the number of widgets deleted.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var formIds = new Array("12400633174999288", "12400633174999289"); + formHost.deleteInvalidForms(formIds).catch((error) => { + console.log('formProvider deleteInvalidForms, error:' + JSON.stringify(error)); + }); + ``` + +## acquireFormState + +acquireFormState(want: Want, callback: AsyncCallback<FormStateInfo>): void; + +Obtains the widget state. This API uses an asynchronous callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| want | [Want](js-apis-featureAbility.md#want) | Yes | **Want** information carried to query the widget state.| +| callback | AsyncCallback<[FormStateInfo](js-apis-formInfo.md#formstateinfo)> | Yes| Callback used to return the widget state.| + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "com.extreme.test.MainAbility" + }; + formHost.acquireFormState(want, (error, data) => { + if (error) { + console.log('formHost acquireFormState, error:' + error.code); + } + }); + ``` + +## acquireFormState + +function acquireFormState(formIds: Array<string>): Promise<formInfo.FormStateInfo>; + +Obtains the widget state. This API uses a promise to return the result. + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<[FormStateInfo](js-apis-formInfo.md#formstateinfo)> | Promise used to return the widget state.| + +**System capability**: + +SystemCapability.Ability.Form + +**Example** + + ```js + var want = { + "deviceId": "", + "bundleName": "com.extreme.test", + "abilityName": "com.extreme.test.MainAbility" + }; + formHost.acquireFormState(want).catch((error) => { + console.log('formProvider acquireFormState, error:' + JSON.stringify(error)); + }); + ``` + +## on("formUninstall") + +on(type: "formUninstall", callback: Callback<string>): void; + +Subscribes to the widget state changes. This API uses a callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | type | string | Yes | Type of event to subscribe to. The value **formUninstall** indicates a widget uninstallation event.| + | callback | Callback<string> | Yes| Callback used to return the result.| + +**Example** + + ```js + formHost.on("formUninstall", (error, data) => { + if (error) { + console.log('formHost on formUninstall, error:' + error.code); + } + }); + ``` + +## off("formUninstall") + +off(type: "formUninstall", callback: Callback<string>): void; + +Unsubscribes from the widget state changes. This API uses a callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | type | string | Yes | Type of event to unsubscribe from. The value **formUninstall** indicates a widget uninstallation event.| + | callback | Callback<string> | Yes| Callback used to return the result.| + +**Example** + + ```js + formHost.off("formUninstall", (error, data) => { + if (error) { + console.log('formHost off formUninstall, error:' + error.code); + } + }); + ``` + +## notifyFormsVisible + +notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void; + +Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formIds | Array<string> | Yes | List of widget IDs.| + | isVisible | boolean | Yes | Whether to be visible.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formIds = new Array("12400633174999288", "12400633174999289"); + formHost.notifyFormsVisible(formIds, true, (error, data) => { + if (error) { + console.log('formHost notifyFormsVisible, error:' + error.code); + } + }); + ``` + +## notifyFormsVisible + +notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void>; + +Instructs the widgets to make themselves visible. This API uses a promise to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formIds | Array<string> | Yes | List of widget IDs.| + | isVisible | boolean | Yes | Whether to be visible.| + +**Example** + + ```js + var formIds = new Array("12400633174999288", "12400633174999289"); + formHost.notifyFormsVisible(formIds, true).catch((error) => { + console.log('formProvider notifyFormsVisible, error:' + JSON.stringify(error)); + }); + ``` + +## notifyFormsEnableUpdate + +notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void; + +Instructs the widgets to enable or disable update. This API uses an asynchronous callback to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formIds | Array<string> | Yes | List of widget IDs.| + | isEnableUpdate | boolean | Yes | Whether to enable update.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```js + var formIds = new Array("12400633174999288", "12400633174999289"); + formHost.notifyFormsEnableUpdate(formIds, true, (error, data) => { + if (error) { + console.log('formHost notifyFormsEnableUpdate, error:' + error.code); + } + }); + ``` + +## notifyFormsEnableUpdate + +notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void>; + +Instructs the widgets to enable or disable update. This API uses a promise to return the result. + +**System capability**: + +SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formIds | Array<string> | Yes | List of widget IDs.| + | isEnableUpdate | boolean | Yes | Whether to enable update.| + +**Example** + + ```js + var formIds = new Array("12400633174999288", "12400633174999289"); + formHost.notifyFormsEnableUpdate(formIds, true).catch((error) => { + console.log('formProvider notifyFormsEnableUpdate, error:' + JSON.stringify(error)); + }); + ``` diff --git a/en/application-dev/reference/apis/js-apis-formprovider.md b/en/application-dev/reference/apis/js-apis-formprovider.md index f682cbc36b446e792a971035e04de9a59924eca9..40367d50bcec160ec9d2bf932f3d8c6275a86d5f 100644 --- a/en/application-dev/reference/apis/js-apis-formprovider.md +++ b/en/application-dev/reference/apis/js-apis-formprovider.md @@ -61,6 +61,12 @@ SystemCapability.Ability.Form | 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. | + **Example** ```js @@ -118,6 +124,12 @@ SystemCapability.Ability.Form | 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** + +| Type | Description | +| -------------- | ----------------------------------- | +| Promise\ | Promise used to return the result.| + **Example** ```js