diff --git a/en/application-dev/ability/fa-formability.md b/en/application-dev/ability/fa-formability.md index c1cadebe652dbd9f195e96ed1dec221df0eff849..377d5e4b8faeda387f4eda5a6506d103c3d76395 100644 --- a/en/application-dev/ability/fa-formability.md +++ b/en/application-dev/ability/fa-formability.md @@ -1,49 +1,49 @@ # FA Widget Development ## 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 is a set of UI components that display important information or operations specific to an application. It provides users with direct access to a desired application service, without the need to open the application first. -A widget displays brief information about an application on the UI of another application (host application, currently system applications only) and provides basic interactive functions such as opening a UI page or sending a message. +A widget usually appears as a part of the UI of another application (which currently can only be a system application) and provides basic interactive features such as opening a UI page or sending a message. -Basic concepts: -- Widget provider: an atomic service that controls what and how content is displayed in a widget and interacts with users. -- Widget host: an application that displays the widget content and controls the position where the widget is displayed in the host application. -- Widget Manager: a resident agent that manages widgets added to the system and provides functions such as periodic widget update. +Before you get started, it would be helpful if you have a basic understanding of the following concepts: +- Widget provider: an atomic service that provides the widget content to display and controls how widget components are laid out and how they interact with users. +- Widget host: an application that displays the widget content and controls the widget location. +- Widget Manager: a resident agent that provides widget management features such as periodic widget updates. > **NOTE** > -> 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. +> The widget host and provider do not need to be running all the time. The Widget Manager will start 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 host and Widget Manager. +You only need to develop the widget provider. The system automatically handles the work of the widget host and Widget Manager. -The widget provider controls the widget content to display, component layout, and click events bound to components. +The widget provider controls the widget content to display, the layout of components used in the widget, and click events bound to the components. ## Development Overview -In FA widget development, you need to carry out the following operations as a widget provider based on the [Feature Ability (FA) model](fa-brief.md). +Carry out the following operations to develop the widget provider based on the [FA model](fa-brief.md): -- Develop the lifecycle callbacks in **LifecycleForm**. -- Create a **FormBindingData** instance. -- Update a widget through **FormProvider**. -- Develop the widget UI pages. +1. Implement lifecycle callbacks by using the **LifecycleForm** APIs. +2. Create a **FormBindingData** instance. +3. Update a widget by using the **FormProvider** APIs. +4. Develop the widget UI pages. ## Available APIs -The table below describes the lifecycle callbacks provided in **LifecycleForm**. +The table below describes the **LifecycleForm** APIs, which represent the lifecycle callbacks of a widget (known as a **Form** instance). **Table 1** LifecycleForm APIs | API | Description | | :----------------------------------------------------------- | :------------------------------------------- | -| onCreate(want: Want): formBindingData.FormBindingData | Called to notify the widget provider that a **Form** instance (widget) has been created. | +| onCreate(want: Want): formBindingData.FormBindingData | Called to notify the widget provider that a widget has been created. | | onCastToNormal(formId: string): void | Called to notify the widget provider that a temporary widget has been converted to a normal one.| | onUpdate(formId: string): void | Called to notify the widget provider that a widget has been updated. | | onVisibilityChange(newStatus: { [key: string]: number }): void | Called to notify the widget provider of the change in widget visibility. | | onEvent(formId: string, message: string): void | Called to instruct the widget provider to receive and process a widget event. | -| onDestroy(formId: string): void | Called to notify the widget provider that a **Form** instance (widget) has been destroyed. | -| onAcquireFormState?(want: Want): formInfo.FormState | Called when the widget provider receives the status query result of a widget. | +| onDestroy(formId: string): void | Called to notify the widget provider that a widget has been destroyed. | +| onAcquireFormState?(want: Want): formInfo.FormState | Called to instruct the widget provider to receive the status query result of a widget. | -For details about the **FormProvider** APIs, see [FormProvider](../reference/apis/js-apis-formprovider.md). +The table below describes the **FormProvider** APIs. For details, see [FormProvider](../reference/apis/js-apis-formprovider.md). **Table 2** FormProvider APIs @@ -56,9 +56,9 @@ For details about the **FormProvider** APIs, see [FormProvider](../reference/api ## How to Develop -### Creating LifecycleForm +### Implementing Lifecycle Callbacks -To create a widget in the FA model, you need to implement the lifecycles of **LifecycleForm**. The sample code is as follows: +To create an FA widget, you need to implement lifecycle callbacks using the **LifecycleForm** APIs. The sample code is as follows: 1. Import the required modules. @@ -68,7 +68,7 @@ To create a widget in the FA model, you need to implement the lifecycles of **Li import formProvider from '@ohos.application.formProvider' ``` -2. Implement the lifecycle callbacks of **LifecycleForm**. +2. Implement lifecycle callbacks for the widget. ```javascript export default { @@ -87,7 +87,7 @@ To create a widget in the FA model, you need to implement the lifecycles of **Li console.log('FormAbility onCastToNormal'); }, onUpdate(formId) { - // To support scheduled update, periodic update, or update requested by the widget host, override this method for widget data update. + // Override this method to support scheduled updates, periodic updates, or updates requested by the widget host. console.log('FormAbility onUpdate'); let obj = { "title": "titleOnUpdate", @@ -119,19 +119,19 @@ To create a widget in the FA model, you need to implement the lifecycles of **Li ### Configuring the Widget Configuration File -Configure the **config.json** file for the widget. +The widget configuration file is named **config.json**. Find the **config.json** file for the widget and edit the file depending on your need. -- The **js** module in the **config.json** file provides the JavaScript resources of the widget. The internal structure is described as follows: +- The **js** module in the **config.json** file provides JavaScript resources of the widget. The internal structure is described as follows: | Field| Description | Data Type| Default | | -------- | ------------------------------------------------------------ | -------- | ------------------------ | | name | Name of a JavaScript component. The default value is **default**. | String | No | | pages | Route information about all pages in the JavaScript component, including the page path and page name. The value is an array, in which each element represents a page. The first element in the array represents the home page of the JavaScript FA.| Array | No | | window | Window-related configurations. | Object | Yes | - | type | Type of the JavaScript component. Available values are as follows:
**normal**: indicates that the JavaScript component is an application instance.
**form**: indicates that the JavaScript component is a widget instance.| String | Yes (initial value: **normal**)| + | type | Type of the JavaScript component.
**normal**: indicates an application instance.
**form**: indicates a widget instance.| String | Yes (initial value: **normal**)| | mode | Development mode of the JavaScript component. | Object | Yes (initial value: left empty) | - A configuration example is as follows: + Example configuration: ```json "js": [{ @@ -145,27 +145,27 @@ Configure the **config.json** file for the widget. }] ``` -- The **abilities** module in the **config.json** file corresponds to the **LifecycleForm** of the widget. The internal structure is described as follows: +- The **abilities** module in the **config.json** file corresponds to **LifecycleForm** of the widget. The internal structure is described as follows: | Field | Description | Data Type | Default | | ------------------- | ------------------------------------------------------------ | ---------- | ------------------------ | | name | Class name of the widget. The value is a string with a maximum of 127 bytes. | String | No | | description | Description of the widget. The value can be a string or a resource index to descriptions in multiple languages. The value is a string with a maximum of 255 bytes.| String | Yes (initial value: left empty) | | isDefault | Whether the widget is a default one. Each ability has only one default widget.
**true**: The widget is the default one.
**false**: The widget is not the default one.| Boolean | No | - | type | Type of the widget. Available values are as follows:
**JS**: indicates a JavaScript-programmed widget. | String | No | - | colorMode | Color mode of the widget. Available values are as follows:
**auto**: The widget adopts the auto-adaptive color mode.
**dark**: The widget adopts the dark color mode.
**light**: The widget adopts the light color mode.| String | Yes (initial value: **auto**)| - | supportDimensions | Grid styles supported by the widget. Available values are as follows:
**1 * 2**: indicates a grid with one row and two columns.
**2 * 2**: indicates a grid with two rows and two columns.
**2 * 4**: indicates a grid with two rows and four columns.
**4 * 4**: indicates a grid with four rows and four columns.| String array| No | + | type | Type of the widget.
**JS**: indicates a JavaScript-programmed widget. | String | No | + | colorMode | Color mode of the widget.
**auto**: The widget adopts the auto-adaptive color mode.
**dark**: The widget adopts the dark color mode.
**light**: The widget adopts the light color mode.| String | Yes (initial value: **auto**)| + | supportDimensions | Grid styles supported by the widget.
**1 * 2**: indicates a grid with one row and two columns.
**2 * 2**: indicates a grid with two rows and two columns.
**2 * 4**: indicates a grid with two rows and four columns.
**4 * 4**: indicates a grid with four rows and four columns.| String array| No | | defaultDimension | Default grid style of the widget. The value must be available in the **supportDimensions** array of the widget.| String | No | - | updateEnabled | Whether the widget can be updated periodically. Available values are as follows:
**true**: The widget can be updated periodically, depending on the update way you select, either at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** is preferentially recommended.
**false**: The widget cannot be updated periodically.| Boolean | No | - | scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute.
This parameter has a lower priority than **updateDuration**. If both are specified, the value specified by **updateDuration** is used.| String | Yes (initial value: **0:0**) | - | updateDuration | Interval to update the widget. The value is a natural number, in the unit of 30 minutes.
If the value is **0**, this field does not take effect.
If the value is a positive integer ***N***, the interval is calculated by multiplying ***N*** and 30 minutes.
This parameter has a higher priority than **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| Number | Yes (initial value: **0**) | + | updateEnabled | Whether the widget can be updated periodically.
**true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**.
**false**: The widget cannot be updated periodically.| Boolean | No | + | scheduledUpdateTime | Scheduled time to update the widget. The value is in 24-hour format and accurate to minute.
**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| String | Yes (initial value: **0:0**) | + | updateDuration | Interval to update the widget. The value is a natural number, in the unit of 30 minutes.
If the value is **0**, this field does not take effect.
If the value is a positive integer ***N***, the interval is calculated by multiplying ***N*** and 30 minutes.
**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| Number | Yes (initial value: **0**) | | formConfigAbility | Link to a specific page of the application. The value is a URI. | String | Yes (initial value: left empty) | | formVisibleNotify | Whether the widget is allowed to use the widget visibility notification. | String | Yes (initial value: left empty) | | jsComponentName | Component name of the widget. The value is a string with a maximum of 127 bytes. | String | No | | metaData | Metadata of the widget. This field contains the array of the **customizeData** field. | Object | Yes (initial value: left empty) | | customizeData | Custom information about the widget. | Object array | Yes (initial value: left empty) | - A configuration example is as follows: + Example configuration: ```json "abilities": [{ @@ -197,7 +197,7 @@ Configure the **config.json** file for the widget. ### Persistently Storing Widget Data -Mostly, the widget provider is started only when it needs to obtain information about a widget. The Widget Manager supports multi-instance management and uses the widget ID to identify an instance. If the widget provider supports widget data modification, it must persistently store the data based on the widget ID, so that it can access the data of the target widget when obtaining, updating, or starting a widget. +A widget provider is usually started when it is needed to provide information about a widget. The Widget Manager supports multi-instance management and uses the widget ID to identify an instance. If the widget provider supports widget data modification, it must persistently store the data based on the widget ID, so that it can access the data of the target widget when obtaining, updating, or starting a widget. ```javascript onCreate(want) { @@ -219,35 +219,35 @@ Mostly, the widget provider is started only when it needs to obtain information } ``` -You should override **onDestroy** to delete widget data. +You should override **onDestroy** to implement widget data deletion. ```javascript onDestroy(formId) { console.log('FormAbility onDestroy'); - // You need to implement the code for deleting the persistent widget instance. + // You need to implement the code for deleting the persistent widget data. // The deleteFormInfo API is not implemented here. deleteFormInfo(formId); } ``` -For details about the persistence method, see [Lightweight Data Store Development](../database/database-preference-guidelines.md). +For details about how to implement persistence data storage, see [Lightweight Data Store Development](../database/database-preference-guidelines.md). -Note that the **Want** passed by the widget host to the widget provider contains a flag that indicates whether the requested widget is a temporary one. +The **Want** passed by the widget host to the widget provider contains a flag that specifies whether the requested widget is normal or temporary. -- Normal widget: a widget that will be persistently used by the widget host +- Normal widget: a widget persistently used by the widget host -- Temporary widget: a widget that is temporarily used by the widget host +- Temporary widget: a widget 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 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. +Data of a temporary widget will be deleted on the Widget Manager if the widget framework is killed and restarted. The widget provider, however, is not notified of the deletion and still keeps the data. Therefore, the widget provider needs to clear the data of temporary widgets proactively if the data has been kept for a long period of time. If the widget host has converted a temporary widget into a normal one, the widget provider should change the widget data from temporary storage to persistent storage. Otherwise, the widget data may be deleted by mistake. ### Updating Widget Data -When a widget application initiates a data update upon a scheduled or periodic update, the application obtains the latest data and calls **updateForm** to update the widget. The code snippet is as follows: +When an application initiates a scheduled or periodic update, the application obtains the latest data and calls **updateForm** to update the widget. The code snippet is as follows: ```javascript onUpdate(formId) { - // To support scheduled update, periodic update, or update requested by the widget host, override this method for widget data update. + // Override this method to support scheduled updates, periodic updates, or updates requested by the widget host. console.log('FormAbility onUpdate'); let obj = { "title": "titleOnUpdate", @@ -267,9 +267,9 @@ You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programme > **NOTE** > -> Currently, only the JavaScript-based web-like development paradigm can be used to develop the widget UI. +> Only the JavaScript-based web-like development paradigm is supported when developing the widget UI. - - In the HML file: + - HML file: ```html
@@ -284,7 +284,7 @@ You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programme
``` - - In the CSS file: + - CSS file: ```css .container { @@ -325,7 +325,7 @@ You can use HML, CSS, and JSON to develop the UI page for a JavaScript-programme } ``` - - In the JSON file: + - JSON file: ```json { "data": { @@ -352,18 +352,18 @@ Now you've got a widget shown below. You can set router and message events for components on a widget. The router event applies to ability redirection, and the message event applies to custom click events. The key steps are as follows: -1. Set **onclick** in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file. +1. Set the **onclick** field in the HML file to **routerEvent** or **messageEvent**, depending on the **actions** settings in the JSON file. 2. For the router event, set the following attributes: - - **action**: **"router"**. + - **action**: **router**, which indicates a router event. - **abilityName**: target ability name, for example, **com.example.entry.MainAbility**, which is the default main ability name in DevEco Studio for the FA model. - **params**: custom parameters of the target ability. Set them as required. The value can be obtained from **parameters** in **want** used for starting the target ability. For example, in the lifecycle function **onCreate** of the main ability in the FA model, **featureAbility.getWant()** can be used to obtain **want** and its **parameters** field. 3. For the message event, set the following attributes: - - **action**: **"message"**. + - **action**: **message**, which indicates a message event. - **params**: custom parameters of the message event. Set them as required. The value can be obtained from **message** in the widget lifecycle function **onEvent**. The code snippet is as follows: - - In the HML file: + - HML file: ```html
@@ -378,7 +378,7 @@ The code snippet is as follows:
``` - - In the JSON file: + - JSON file: ```json { "data": {