diff --git a/en/application-dev/form/Readme-EN.md b/en/application-dev/form/Readme-EN.md
index 2710099a1ede67cd730a092036755223dfbd1f1d..81ed1442d26b819a8b4b202ad0fe6444e163421f 100644
--- a/en/application-dev/form/Readme-EN.md
+++ b/en/application-dev/form/Readme-EN.md
@@ -1,39 +1,39 @@
# Form Kit
- [Introduction to Form Kit](formkit-overview.md)
-- Service Widget Development in Stage Model
- - Developing an ArkTS Widget
- - [ArkTS Widget Working Principles](arkts-ui-widget-working-principles.md)
- - [ArkTS Widget Related Modules](arkts-ui-widget-modules.md)
- - ArkTS Widget Development
- - [Creating an ArkTS Widget](arkts-ui-widget-creation.md)
- - [Configuring Widget Configuration Files](arkts-ui-widget-configuration.md)
- - [Widget Lifecycle Management](arkts-ui-widget-lifecycle.md)
- - Widget Page Development
- - [Widget Page Capability Overview](arkts-ui-widget-page-overview.md)
- - [Using Animations in the Widget](arkts-ui-widget-page-animation.md)
- - [Applying Custom Drawing in the Widget](arkts-ui-widget-page-custom-drawing.md)
- - Widget Event Development
- - [Widget Event Capability Overview](arkts-ui-widget-event-overview.md)
- - [Launching the UIAbility of the Widget Provider Through the router Event](arkts-ui-widget-event-router.md)
- - [Launching the UIAbility of the Widget Provider in the Background Through the call Event](arkts-ui-widget-event-call.md)
- - [Updating Widget Content Through the message Event](arkts-ui-widget-event-formextensionability.md)
- - [Updating Widget Content Through the router or call Event](arkts-ui-widget-event-uiability.md)
- - Widget Data Interaction
- - [Updating Widget Content](arkts-ui-widget-interaction-overview.md)
- - [Interval-based Widget Updates](arkts-ui-widget-update-by-time.md)
- - [Time-specific Widget Updates](arkts-ui-widget-update-by-time-point.md)
-
- - [Updating Widget Content Through a Proxy](arkts-ui-widget-update-by-proxy.md)
- - [Conditional Widget Updates](arkts-ui-widget-update-by-conditions.md)
- - [Updating Widget Content by Widget Host (for System Applications Only)](arkts-ui-widget-content-update.md)
-
- - [Updating Local and Online Images in the Widget](arkts-ui-widget-image-update.md)
- - [Updating Widget Content by State](arkts-ui-widget-update-by-status.md)
- - Editing the ArkTS Widget Page
- - [Overview of ArkTs Widget Page Editing Interaction](arkts-ui-widget-event-formeditextensionability-overview.md)
- - [Editing and Updating the Widget Content](arkts-ui-widget-event-formeditextensionability.md)
-
- - [Widget Host Development (for System Applications Only)](widget-host-development-guide.md)
-
- - [Developing a JS Widget](js-ui-widget-development.md)
-- [Service Widget Development in FA Model](widget-development-fa.md)
+- ArkTS Widget Development (Recommended)
+ - [ArkTS Widget Overview](arkts-form-overview.md)
+ - [Creating an ArkTS Widget](arkts-ui-widget-creation.md)
+ - [Configuring ArkTS Widget Configuration Files](arkts-ui-widget-configuration.md)
+ - [Managing ArkTS Widget Lifecycle](arkts-ui-widget-lifecycle.md)
+ - [ArkTS Widget Process Model](arkts-ui-widget-process.md)
+ - ArkTS Widget Provider Development
+ - ArkTS Widget UI Development
+ - [Overview of ArkTS Widget UI Development](arkts-ui-widget-page-overview.md)
+ - [Using Animations in ArkTS Widgets](arkts-ui-widget-page-animation.md)
+ - [Using Canvas in ArkTS Widgets](arkts-ui-widget-page-custom-drawing.md)
+ - ArkTS Widget Page Interaction
+ - [Overview of ArkTS Widget Page Interaction](arkts-ui-widget-event-overview.md)
+ - [Interaction Through the router Event](arkts-ui-widget-event-router.md)
+ - [Interaction Through the call Event](arkts-ui-widget-event-call.md)
+ - [Interaction Through the message Event](arkts-ui-widget-event-formextensionability.md)
+ - ArkTS Widget Update
+ - [Overview of ArkTS Widget Update](arkts-ui-widget-interaction-overview.md)
+ - [Active Update of ArkTS Widgets](arkts-ui-widget-active-refresh.md)
+ - [Passive Update of ArkTS Widgets](arkts-ui-widget-passive-refresh.md)
+
+ - [Updating Widget Content Through a Proxy](arkts-ui-widget-update-by-proxy.md)
+
+ - [Updating Local and Online Images in the Widget](arkts-ui-widget-image-update.md)
+ - [Updating Widget Content by State](arkts-ui-widget-update-by-status.md)
+ - ArkTS Widget Editing
+ - [Overview of ArkTS Widget Editing](arkts-ui-widget-event-formeditextensionability-overview.md)
+ - [Widget Editing Development](arkts-ui-widget-event-formeditextensionability.md)
+ - Widget Addition to Home Screen
+ - [Adding Widgets to the Home Screen](arkts-ui-widget-open-formmanager.md)
+
+ - [ArkTS Widget Host Development (for System Applications Only)](widget-host-development-guide.md)
+
+- JS Widget Development
+ - [JS Widget Overview](js-ui-widget-overview.md)
+ - [Developing a JS Widget (Stage Model)](js-ui-widget-development.md)
+ - [Developing a JS Widget (FA Model)](widget-development-fa.md)
diff --git a/en/application-dev/form/arkts-form-overview.md b/en/application-dev/form/arkts-form-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..d0b9198b8e957faa7f55afa0354673cd74b44f66
--- /dev/null
+++ b/en/application-dev/form/arkts-form-overview.md
@@ -0,0 +1,85 @@
+# ArkTS Widget Overview
+This section describes how to develop an ArkTS widget based on the declarative paradigm.
+
+## Highlights
+1. Unified development paradigm
+
+ - ArkTS widgets share the same declarative UI development framework as application pages. This means that the page layouts can be directly reused in widgets, improving development experience and efficiency. For details, see Figure 1.
+
+ **Figure 1** Comparison of widget project structures
+ 
+
+2. Enhanced widget capabilities
+
+ - Animation: ArkTS widgets support the [property animation](../reference/apis-arkui/arkui-ts/ts-animatorproperty.md) and [explicit animation](../reference/apis-arkui/arkui-ts/ts-explicit-animation.md) capabilities, which can be leveraged to deliver a more engaging experience.
+ - Custom drawing: ArkTS widgets allow you to draw graphics with the [Canvas](../reference/apis-arkui/arkui-ts/ts-components-canvas-canvas.md) component to present information more vividly.
+ - Logic code execution: The capability to run logic code in widgets means that service logic can be self-closed in widgets, expanding the use cases of widgets.
+
+## How to Implement
+
+- Widget host: an application that displays the widget content and controls the widget location. Only the system application can function as a widget host.
+
+- Widget provider: an application that provides the widget content and controls the widget content, component layout, and component tap events.
+
+- Widget Manager: a resident agent that manages widgets in the system. It provides [formProvider](../reference/apis-form-kit/js-apis-app-form-formProvider.md) and [formHost](../reference/apis-form-kit/js-apis-app-form-formHost-sys.md) as well as the APIs for widget management, usage, and periodic updates.
+
+- Widget rendering service: a service that manages widget rendering instances. Widget rendering instances are bound to the [FormComponent](../reference/apis-arkui/arkui-ts/ts-basic-components-formcomponent-sys.md) on the widget host on a one-to-one basis. The widget rendering service runs the widget page code **widgets.abc** for rendering based on the widget information configured in **form_config.json**, and sends the rendered data to the corresponding [FormComponent](../reference/apis-arkui/arkui-ts/ts-basic-components-formcomponent-sys.md) on the widget host.
+
+**Figure 2** Implementation principles of ArkTS widgets
+
+
+**Figure 3** Working principles of the ArkTS widget rendering service
+
+
+Unlike JS widgets, ArkTS widgets support logic code execution. The widget page code **widgets.abc** is executed by the widget rendering service, which is managed by the Widget Manager. Each widget component of a widget host corresponds to a rendering instance in the widget rendering service. Rendering instances of a widget provider run in the same ArkTS virtual machine operating environment, and rendering instances of different widget providers run in different ArkTS virtual machine operating environments. In this way, the resources and state data are isolated between widgets of different widget providers. During development, pay attention to the use of the **globalThis** object. Use one **globalThis** object for widgets from the same widget provider, and different **globalThis** objects for widgets from different widget providers.
+
+## ArkTS Widget Types
+ArkTS widgets are classified into dynamic widgets and static widgets.
+
+Compared with dynamic widgets, static widgets have the same overall running framework and rendering process. The main difference is that after the widget rendering service renders the widget content, the widget host uses the last frame of rendered data as a static image, and the widget rendering instance releases all running resources of the widget to save memory. As such, frequent updating of static widgets causes continuous creation and destruction of resources, resulting in increased power consumption.
+
+| Widget Type| Supported Capability| Scenario| Pros and Cons|
+| ------- | ------ | ------- | ------- |
+| Static widget| Limited to UI components and layout capabilities.| Suitable for presenting static information (with a stable UI), allowing navigation to a specific UIAbility via the **FormLink** component.| Offers basic functionality with efficient memory management.|
+| Dynamic widget| Common event and custom animation capabilities in addition to UI components and layout capabilities.| Suitable for scenarios requiring complex logic and interactions, such as updating images or content on a widget.| Provides enhanced capabilities at the cost of high memory overhead.|
+
+### Dynamic Widget
+For dynamic ArkTS widgets, the [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction) API is provided for interaction between the widget internal and the provider application. Currently, this API supports the router, message, and call events and can be called only in the widget.
+
+**Figure 4** Implementation principles of dynamic widget events
+
+
+Dynamic widget events are used in the following scenarios:
+- router event: used to redirect to a specified UIAbility, enabling the functionality of navigating from a widget to an internal application page after a widget is touched. For non-system applications, this redirection is limited to their own UIAbilities.
+- call event: used to launch a specified UIAbility to the background, after which the UIAbility can request the corresponding background continuous task to complete functionalities such as music playback.
+- message event: used to launch the FormExtensionAbility, which then notifies the application via the **onFormEvent** callback, thereby fulfilling the functionality of passing messages to the application after a widget is touched.
+
+### Static Widget
+The **FormLink** component is provided for interactions between static widgets and widget providers. It supports three types of events: router, message, and call.
+See [FormLink](../reference/apis-arkui/arkui-ts/ts-container-formlink.md).
+
+## Constraints
+Compared with JS widgets, ArkTS widgets provide more capabilities, but they are also more prone to malicious behavior. To account for the impact on the widget host – typically the home screen, ArkTS widgets are subject to the following restrictions:
+
+- Currently, widgets can be developed only based on ArkUI. Cross-platform development is not supported.
+
+- When importing modules, you can import only the modules marked with "supported in ArkTS widgets." If an API that is not supported is used, the widget loading is abnormal.
+
+- [HAR](../quick-start/har-package.md) can be imported, but [HSP](../quick-start/in-app-hsp.md) cannot.
+
+- The native programming language cannot be used for development, and the native .so file cannot be loaded.
+
+- Only partial components, events, animations, data management, state management, and API capabilities of the [declarative paradigm](../ui/arkts-ui-development-overview.md) are supported. For APIs that can be used in ArkTS widgets, the following description will be added: "Widget capability: This API can be used in ArkTS widgets since API version *x*."
+
+- The event processing of the widget is independent of that of the widget host. To prevent gesture conflicts, avoid using swipers in the widget when the widget host supports left and right swipes.
+
+In addition, ArkTS widgets do not support the following features:
+
+- Instant preview
+
+- Breakpoint debugging
+
+- Hot reload
+
+- setTimeOut
+
diff --git a/en/application-dev/form/arkts-ui-widget-active-refresh.md b/en/application-dev/form/arkts-ui-widget-active-refresh.md
new file mode 100644
index 0000000000000000000000000000000000000000..a02478472bcef09609fee2b32c82a059092fe10b
--- /dev/null
+++ b/en/application-dev/form/arkts-ui-widget-active-refresh.md
@@ -0,0 +1,91 @@
+# Active Update of ArkTS Widgets
+
+This section provides the development guidelines for active update. For details about the update process, see [Active Update](./arkts-ui-widget-interaction-overview.md#active-update).
+
+## Active Update by Widget Provider
+
+The widget provider can call [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform) to actively update the widget. It is recommended that this API be used with the widget lifecycle callbacks [onFormEvent](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonformevent), [onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform), and [onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonaddform).
+
+```ts
+import { formBindingData, formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+let storage = new LocalStorage();
+const TAG: string = 'Index';
+const DOMAIN_NUMBER: number = 0xFF00;
+
+@Entry(storage)
+@Component
+struct Index {
+ @StorageLink('formId') formId: number = 0;
+ @StorageLink('formData') formData: Object | string = {};
+
+ build() {
+ Column() {
+ Column() {
+ //...
+ Button() {
+ //...
+ }
+ .onClick(() => {
+ console.info(DOMAIN_NUMBER, TAG, `click to check updateForm, formId: ${this.formId}`);
+ const formInfo: formBindingData.FormBindingData = formBindingData.createFormBindingData(this.formData);
+ // formId is the ID of the widget to be updated.
+ formProvider.updateForm(this.formId, formInfo).then(() => {
+ console.info(DOMAIN_NUMBER, TAG, 'updateForm success.');
+ }).catch((error: BusinessError) => {
+ console.error(DOMAIN_NUMBER, TAG, `updateForm fail, code: ${error?.code}, message: ${error?.message}`);
+ })
+ })
+ .margin(5)
+ }
+ //...
+ }
+ //...
+ }
+}
+```
+
+
+## Active Update by Widget Host (for System Applications Only)
+
+Due to the time limit of interval-based and time-specific updates, the widget host can call [requestForm](../reference/apis-form-kit/js-apis-app-form-formHost-sys.md#requestform) to request the Widget Manager to actively update the widget. The Widget Manager calls the [onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform) lifecycle callback in the FormExtensionAbility of the widget provider. In the callback, the [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform) API can be called to update the widget content.
+
+```ts
+import { formHost } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+let storage = new LocalStorage();
+const TAG: string = 'Index';
+const DOMAIN_NUMBER: number = 0xFF00;
+
+@Entry(storage)
+@Component
+struct Index {
+ @StorageLink('formId') formId: number = 0;
+
+ build() {
+ Column() {
+ Column() {
+ //...
+ Button() {
+ //...
+ }
+ .onClick(() => {
+ console.info(DOMAIN_NUMBER, TAG, `click to check requestForm, formId: ${this.formId}`);
+ // formId is the ID of the widget to be updated.
+ formHost.requestForm(this.formId.toString()).then(() => {
+ console.info(DOMAIN_NUMBER, TAG, 'requestForm success.');
+ }).catch((error: BusinessError) => {
+ console.error(DOMAIN_NUMBER, TAG, `requestForm fail, code: ${error?.code}, message: ${error?.message}`);
+ })
+ })
+ .margin(5)
+ }
+ //...
+ }
+ //...
+ }
+}
+```
+
diff --git a/en/application-dev/form/arkts-ui-widget-configuration.md b/en/application-dev/form/arkts-ui-widget-configuration.md
index 8d736d119e5aef8e2bd73d2243d5ca99020d5171..501a742aaac0b3de2d2b84e2c0b16bd7d7d7a73a 100644
--- a/en/application-dev/form/arkts-ui-widget-configuration.md
+++ b/en/application-dev/form/arkts-ui-widget-configuration.md
@@ -1,10 +1,11 @@
-# Configuring Widget Configuration Files
+# Configuring ArkTS Widget Configuration Files
-Widget-related configuration includes **FormExtensionAbility** configuration and widget configuration.
+Widget-related configuration includes [FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md) configuration and widget configuration.
+## FormExtensionAbility Configuration
-1. Configure FormExtensionAbility information under **extensionAbilities** in the [module.json5 file](../quick-start/module-configuration-file.md). For a FormExtensionAbility, you must specify **metadata**. Specifically, set **name** to **ohos.extension.form** (fixed), and set **resource** to the index of the widget configuration information.
+Configure FormExtensionAbility information under **extensionAbilities** in the [module.json5 file](../quick-start/module-configuration-file.md). For a FormExtensionAbility, you must specify metadata. Specifically, set **name** to **ohos.extension.form** (fixed), and set **resource** to the [index of the widget configuration information](#widget-configuration).
Example configuration:
@@ -32,7 +33,11 @@ Widget-related configuration includes **FormExtensionAbility** configuration and
}
```
-2. Configure the widget configuration information. In the **metadata** configuration item of FormExtensionAbility, you can specify the resource index of specific configuration information of the widget. For example, if **resource** is set to **$profile:form_config**, **form_config.json** in the **resources/base/profile/** directory of the development view is used as the profile configuration file of the widget. The following table describes the internal structure of the profile configuration file.
+## Widget Configuration
+
+In the **metadata** configuration item of FormExtensionAbility, you can specify the resource index of specific configuration information of the widget. For example, if **resource** is set to **$profile:form_config**, **form_config.json** in the **resources/base/profile/** directory of the development view is used as the profile configuration file of the widget. The **form_config.json** configuration file is automatically generated when you [create a widget](./arkts-ui-widget-creation.md).
+
+### Fields in Configuration File
**Table 1** form_config.json file
@@ -40,33 +45,33 @@ Widget-related configuration includes **FormExtensionAbility** configuration and
| -------- | -------- | -------- | -------- |
| forms | Configuration about all application widgets.
A maximum of 16 widgets can be configured. If more than 16 widgets are configured, the first 16 widgets are retained.| Array| No|
| name | Name of the widget. The value is a string with a maximum of 127 bytes.| String| No|
- | displayName | Display name of the widget. The value can be a string or a resource index to the name in multiple languages. The string must contain 1 to 30 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)|
+ | displayName | Display name of the widget. It is primarily displayed on the widget management page and should reflect the core functionalities or usage of the widget. The value can be a string or a resource index to the name in multiple languages, with the resource index recommended. The string must contain 1 to 30 bytes.| String| No|
+ | description | Description of the widget. It is displayed on the widget management page and should reflect the core functionalities of the widget. The value can be a string or a resource index to the name in multiple languages, with the resource index recommended. The value is a string with a maximum of 255 bytes.| String| Yes (initial value: left empty)|
| src | Full path of the UI code corresponding to the widget. For an ArkTS widget, the full path must contain the widget file name extension, for example, **./ets/widget/pages/WidgetCard.ets**. For a JS widget, the full path does not need to contain the widget file name extension, for example, **./js/widget/pages/WidgetCard**.| String| No|
| uiSyntax | Type of the widget.
- **arkts**: ArkTS widget
- **hml**: JS widget| String| Yes (initial value: **hml**)|
- | [window](#window-field)| Window-related configurations.| Object| Yes (initial value: see Table 2)|
+ | [window](#window-field)| Window-related configurations.
**NOTE**
This field takes effect only for JS widgets.| Object| Yes (initial value: see Table 2)|
| isDefault | Whether the widget is a default one. Each UIAbility has only one default widget.
- **true**: The widget is the default one.
- **false**: The widget is not the default one.| Boolean| No|
- | colorMode | Color mode of the widget.
- **auto**: following the system color mode
- **dark**: dark color mode
- **light**: 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.
- **1 * 1**: indicates a round widget with one row and one column.
- **6 * 4**: indicates a grid with six rows and four columns.| String array| No|
+ | colorMode | Color mode of the widget.
- **auto**: following the system color mode
- **dark**: dark color mode
- **light**: 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.
- **1 * 1**: round widget with one row and one column. This value is configurable only for system applications and takes effect only when the screen is locked.
- **6 * 4**: indicates a grid with six 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.
- **true**: The widget can be updated at a specified interval (**updateDuration**) or at the scheduled time (**scheduledUpdateTime**). **updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.
- **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.
**NOTE**
**updateDuration** takes precedence over **scheduledUpdateTime**. If both are specified, the value specified by **updateDuration** is used.| String| Yes (initial value: The widget is not updated at the scheduled time.)|
| 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.
**NOTE**
**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)|
| metadata | Metadata of the widget. For details, see [Metadata](../reference/apis-ability-kit/js-apis-bundleManager-metadata.md).| Object| Yes (initial value: left empty)|
- | dataProxyEnabled | Whether the widget supports the update-through-proxy feature.
- **true**: The widget supports the update-through-proxy feature.
- **false**: The widget does not support the update-through-proxy feature.
If this tag is set to **true**, the settings for the scheduled update time will still take effect, but the settings for the update interval and next update time will not.| Boolean| Yes (initial value: **false**)|
- | [isDynamic](#isdynamic-field)| Whether the widget is a dynamic widget. This tag applies only to ArkTS widgets.
- **true**: The widget is a dynamic widget.
- **false**: The widget is a static widget.
| Boolean| Yes (initial value: **true**)|
+ | dataProxyEnabled | Whether the widget supports the [update-through-proxy](./arkts-ui-widget-update-by-proxy.md) feature.
- **true**: The widget supports the update-through-proxy feature.
- **false**: The widget does not support the update-through-proxy feature.
If it is set to **true**, the settings for the [interval-based update and next update](./arkts-ui-widget-passive-refresh.md#interval-based-update) will not take effect, and [Time-specific Update](./arkts-ui-widget-passive-refresh.md#time-specific-update) is not affected.| Boolean| Yes (initial value: **false**)|
+ | [isDynamic](#isdynamic-field)| Whether the widget is a dynamic widget. This field applies only to ArkTS widgets.
- **true**: The widget is a dynamic widget.
- **false**: The widget is a static widget.
| Boolean| Yes (initial value: **true**)|
| fontScaleFollowSystem | Whether the font size of the widget changes with the system font size.
- **true**: The font size varies with the system font size.
- **false**: The font size cannot change with the system font size.
| Boolean| Yes (initial value: **true**)|
- | supportShapes | Shapes that the widget can be displayed. The options are as follows:
- **rect**: square widget.
- **circle**: circular widget.| String| Yes (initial value: **rect**)|
+ | supportShapes | Shapes that the widget can be displayed. The options are as follows:
- **rect**: rectangular widget.
- **circle**: circular widget.| String array| Yes (initial value: **rect**)|
| previewImages | Preview images of the widget, corresponding to the **supportDimensions** parameter.| String| Yes (mandatory for smart wearables and currently valid only for wearables)|
- | formVisibleNotify | Whether the widget is allowed to use the widget visibility notification. This parameter is valid only for widgets of system applications.| Boolean| Yes (initial value: **false**)|
- | transparencyEnabled | Whether the widget host is allowed to set the background transparency of the widget. This tag applies only to ArkTS widgets.
- **true**: The widget host is allowed to set the background transparency of the widget.
- **false**: The widget host is not allowed to set the background transparency of the widget.
| Boolean| Yes (initial value: **false**)|
+ | formVisibleNotify | Whether to notify the widget provider of the visible status change. This field is valid only for widgets of system applications.
- **true**: The widget provider is notified of the status change.
- **false**: The widget provider is not notified of the status change.| Boolean| Yes (initial value: **false**)|
+ | transparencyEnabled | Whether the widget host is allowed to set the background transparency of the widget. This field applies only to ArkTS widgets.
- **true**: The widget host is allowed to set the background transparency of the widget.
- **false**: The widget host is not allowed to set the background transparency of the widget.
| Boolean| Yes (initial value: **false**)|
|enableBlurBackground|Whether a blur background is enabled for the widget.
- **true**: A blur background is enabled.
- **false**: A blur background is disabled.|Boolean|Yes (initial value: **false**)|
|renderingMode|Rendering mode of the widget.
- **autoColor**: automatic mode, where the widget is visible in both the lock screen widget center and the home screen widget center/widget management.
- **fullColor**: full-color mode, where the widget is visible in the home screen widget center/widget management.
- **singleColor**: monochrome mode, where the widget is visible in the lock screen widget center. |String|Yes (initial value: **fullColor**)|
|multiScheduledUpdateTime|Times for updating the widget. As an additional parameter for single-point update, it follows the 24-hour format, precise to the minute. It allows up to 24 distinct times, with every two times separated by a comma (,).
**NOTE**
It must be used together with **scheduledUpdateTime**.|String|Yes (initial value: The widget is not updated at the scheduled times.)|
|conditionUpdate|Conditional update capabilities supported by the widget (valid only for ArkTS widgets of system applications). The value can be:
- **network**: Network update is supported.|String|Yes (initial value: an empty string)|
-## isDynamic Field
+### isDynamic Field
Specifies whether the widget is a dynamic widget. It applies only to ArkTS widgets.
@@ -75,7 +80,7 @@ Specifies whether the widget is a dynamic widget. It applies only to ArkTS widge
| Static widget| Limited to UI components and layout capabilities.| Suitable for presenting static information (with a stable UI), allowing navigation to a specific UIAbility via the **FormLink** component.| Offers basic functionality with efficient memory management.|
| Dynamic widget| Common event and custom animation capabilities in addition to UI components and layout capabilities.| Suitable for scenarios requiring complex logic and interactions, such as updating images or content on a widget.| Provides enhanced capabilities at the cost of high memory overhead.|
-## window Field
+### window Field
Describes the internal structure of a window object.
@@ -84,9 +89,9 @@ Describes the internal structure of a window object.
| designWidth | Baseline width for page design. The size of an element is scaled by the actual device width.| Number| Yes (initial value: **720px**)|
| autoDesignWidth | Whether to automatically calculate the baseline width for page design. If it is set to **true**, the **designWidth** attribute will be ignored, and the baseline width will be calculated based on the device width and screen density.| Boolean| Yes (initial value: **false**)|
- Example configuration:
-
+### Configuration File Example
+
```json
{
"forms": [
@@ -111,7 +116,6 @@ Describes the internal structure of a window object.
"2*2"
],
"formConfigAbility": "ability://EntryAbility",
- "dataProxyEnabled": false,
"isDynamic": true,
"transparencyEnabled": false,
"metadata": []
@@ -119,3 +123,4 @@ Describes the internal structure of a window object.
]
}
```
+
diff --git a/en/application-dev/form/arkts-ui-widget-creation.md b/en/application-dev/form/arkts-ui-widget-creation.md
index c989c7fa43b17b55dc60d88d645daf6e8db3e31a..a21d1c051820d6c0ca9b1799cd3d16565e1d0e5d 100644
--- a/en/application-dev/form/arkts-ui-widget-creation.md
+++ b/en/application-dev/form/arkts-ui-widget-creation.md
@@ -1,5 +1,5 @@
# Creating an ArkTS Widget
-
+## How to Create
You can create a widget in either of the following modes:
- When creating a project, select **Application**, and then right-click a module folder and choose **New** > **Service Widget** to create a widget.
@@ -21,8 +21,30 @@ To create an ArkTS widget in an existing project, perform the following steps:
2. Select a widget template based on the actual service scenario.
-3. Set **Language** to **ArkTS** and click **Finish**.
+3. Set **Language** to **ArkTS**, set **Support dimension** to the desired widget size, and then set **Default dimension** to the default widget dimension. You can refer to or modify the widget dimension in the [form_config.json](arkts-ui-widget-configuration.md) file. Then, you can click **Finish** to create an ArkTS widget.
You are advised to name the widget based on the actual scenario. After an ArkTS widget is created, the following widget-related files are automatically added to the project directory: **EntryFormAbility.ets** (widget lifecycle management file), **WidgetCard.ets** (widget page file), and **form_config.json** (widget configuration file).
+## Project Structure
+**Figure 1** ArkTS widget project directory and related modules
+
+
+
+- [FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md): provides lifecycle callbacks invoked when a widget is created, destroyed, or updated.
+
+- [FormExtensionContext](../reference/apis-form-kit/js-apis-inner-application-formExtensionContext.md): provides context for FormExtensionAbilities. You can use the APIs of this module to start FormExtensionAbilities.
+
+- [formProvider](../reference/apis-form-kit/js-apis-app-form-formProvider.md): provides capabilities such as obtaining widget information, updating widgets, and setting the widget update time.
+
+- [formInfo](../reference/apis-form-kit/js-apis-app-form-formInfo.md): provides types and enums related to the widget information and state.
+
+- [formBindingData](../reference/apis-form-kit/js-apis-app-form-formBindingData.md): provides APIs for widget data binding. You can use the APIs to create a **FormBindingData** object and obtain related information.
+
+- [Page layout (WidgetCard.ets)](arkts-ui-widget-page-overview.md): provides the widget UI development capability based on ArkUI.
+ - [General capabilities of ArkTS widgets](arkts-ui-widget-page-overview.md#page-capabilities-supported-by-arkts-widgets): provide components, attributes, and APIs that can be used in ArkTS widgets.
+ - [Capabilities exclusive to ArkTS widgets](arkts-ui-widget-event-overview.md): include the **postCardAction** API used for interaction between the widget internal and the provider application and can be called only in the widget.
+
+- [Widget configuration](arkts-ui-widget-configuration.md): includes FormExtensionAbility configuration and widget configuration.
+ - Configure the FormExtensionAbility information under **extensionAbilities** in the [module.json5 file](../quick-start/module-configuration-file.md).
+ - Configure the widget configuration information (**WidgetCard.ets**) in the [form_config.json](arkts-ui-widget-configuration.md) file in **resources/base/profile**.
diff --git a/en/application-dev/form/arkts-ui-widget-event-call.md b/en/application-dev/form/arkts-ui-widget-event-call.md
index 5670888140368057d4a4c43a1efe7ec7bfcdff0b..2cc922760d0b03ccba237ab1e37a5085c233509f 100644
--- a/en/application-dev/form/arkts-ui-widget-event-call.md
+++ b/en/application-dev/form/arkts-ui-widget-event-call.md
@@ -1,4 +1,4 @@
-# Launching the UIAbility of the Widget Provider in the Background Through the call Event
+# Launching UIAbility to the Background (call Event)
There may be cases you want to provide in a widget access to features available in your application running in the foreground, for example, the play, pause, and stop buttons in a music application widget. This is where the **call** capability of the [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction) API comes in handy. This capability, when used in a widget, can start the specified UIAbility of the widget provider in the background. It also allows the widget to call the specified method of the application and transfer data so that the application, while in the background, can behave accordingly in response to touching of the buttons on the widget.
@@ -10,70 +10,75 @@ There may be cases you want to provide in a widget access to features available
## How to Develop
1. Create a dynamic widget.
- Create a dynamic widget named WidgetEventCallCardArkTs.
+ Create a dynamic widget named WidgetEventCall.
2. Implement page layout.
- In this example, two buttons are laid out on the widget page. When one button is clicked, the **postCardAction** API is called to send a call event to the target UIAbility. Note that the **method** parameter in the API indicates the method to call in the target UIAbility. It is mandatory and of the string type.
- ```ts
- //src/main/ets/widgeteventcallcard/pages/WidgetEventCallCardCard.ets
+ In this example, two buttons (A and B) are laid out on the widget page. When one button is touched, the **postCardAction** API is called to send a call event to the target UIAbility, with the method to be called defined in the event. Button A and button B correspond to the funA and funB methods, respectively. The funA method carries the **formID** parameter, and the funB method carries the **formID** and **num** parameters. Pass parameters as required during development. In **postCardAction**, the **method** parameter is mandatory and identifies the name of the method to be invoked, which should match the method listened for by the UIAbility in step 3. Other parameters are optional.
+ ```ts
+ //src/main/ets/widgeteventcallcard/pages/WidgetEventCall.ets
@Entry
@Component
- struct WidgetEventCallCard {
+ struct WidgetEventCall {
@LocalStorageProp('formId') formId: string = '12400633174999288';
-
+ private funA: string = 'Button A';
+ private funB: string = 'Button B';
+
build() {
- Column() {
- //...
- Row() {
- Column() {
- Button() {
- //...
+ RelativeContainer() {
+ Button(this.funA)
+ .id('funA__')
+ .fontSize($r('app.float.page_text_font_size'))
+ .fontWeight(FontWeight.Bold)
+ .alignRules({
+ center: { anchor: '__container__', align: VerticalAlign.Center },
+ middle: { anchor: '__container__', align: HorizontalAlign.Center }
+ })
+ .onClick(() => {
+ postCardAction(this, {
+ action: 'call',
+ // Only the UIAbility of the current application is allowed. The ability name must be the same as that defined in module.json5.
+ abilityName: 'WidgetEventCallEntryAbility',
+ params: {
+ formId: this.formId,
+ // Name of the method to be called.
+ method: 'funA'
}
- //...
- .onClick(() => {
- postCardAction(this, {
- action: 'call',
- abilityName: 'WidgetEventCallEntryAbility', // Only the UIAbility of the current application is allowed. The ability name must be the same as that defined in module.json5.
- params: {
- formId: this.formId,
- method: 'funA' // Set the name of the method to call in the EntryAbility.
- }
- });
- })
-
- Button() {
- //...
- }
- //...
- .onClick(() => {
- postCardAction(this, {
- action: 'call',
- abilityName: 'WidgetEventCallEntryAbility', // Only the UIAbility of the current application is allowed. The ability name must be the same as that defined in module.json5.
- params: {
- formId: this.formId,
- method: 'funB', // Set the name of the method to call in the EntryAbility.
- num: 1 // Set other parameters to be passed in.
- }
- });
- })
+ });
+ })
+ Button(this.funB)
+ .id('funB__')
+ .fontSize($r('app.float.page_text_font_size'))
+ .fontWeight(FontWeight.Bold)
+ .margin({ top: 10 })
+ .alignRules({
+ top: { anchor: 'funA__', align: VerticalAlign.Bottom },
+ middle: { anchor: '__container__', align: HorizontalAlign.Center }
+ })
+ .onClick(() => {
+ postCardAction(this, {
+ action: 'call',
+ abilityName: 'WidgetEventCallEntryAbility',
+ params: {
+ formId: this.formId,
+ // Name of the method to be called.
+ method: 'funB',
+ num: 1
}
- }.width('100%').height('80%')
- .justifyContent(FlexAlign.Center)
- }
- .width('100%')
- .height('100%')
- .alignItems(HorizontalAlign.Center)
+ });
+ })
+ }
+ .height('100%')
+ .width('100%')
}
}
```
3. Create a UIAbility.
- The UIAbility receives the call event and obtains the transferred parameters. It then executes the target method specified by the **method** parameter. Other data can be obtained through the [readString](../reference/apis-ipc-kit/js-apis-rpc.md#readstring) method. Listen for the method required by the call event in the **onCreate** callback of the UIAbility.
+ Listen for the call event in the UIAbility, call the corresponding method based on the **method** parameter, and obtain the parameter by using [rpc.Parcelable](../reference/apis-ipc-kit/js-apis-rpc.md#parcelable9). The method in the UIAbility must be the same as that in step 2.
```ts
//src/main/ets/widgeteventcallcard/WidgetEventCallEntryAbility/WidgetEventCallEntryAbility.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
- import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import { rpc } from '@kit.IPCKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
@@ -82,7 +87,8 @@ There may be cases you want to provide in a widget access to features available
const DOMAIN_NUMBER: number = 0xFF00;
const CONST_NUMBER_1: number = 1;
const CONST_NUMBER_2: number = 2;
-
+
+ // Implementation of the RPC return type, which is used for RPC data serialization and deserialization.
class MyParcelable implements rpc.Parcelable {
num: number;
str: string;
@@ -106,24 +112,18 @@ There may be cases you want to provide in a widget access to features available
}
export default class WidgetEventCallEntryAbility extends UIAbility {
- // If the UIAbility is started for the first time, onCreate is triggered after the call event is received.
+ // If the UIAbility is started, the onCreate lifecycle callback is triggered after the call event is received.
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
try {
- // Listen for the method required by the call event.
+ // Listen for the method required by the call event and call the method.
this.callee.on('funA', (data: rpc.MessageSequence) => {
// Obtain all parameters passed in the call event.
hilog.info(DOMAIN_NUMBER, TAG, `FunACall param: ${JSON.stringify(data.readString())}`);
- promptAction.showToast({
- message: 'FunACall param:' + JSON.stringify(data.readString())
- });
return new MyParcelable(CONST_NUMBER_1, 'aaa');
});
this.callee.on('funB', (data: rpc.MessageSequence) => {
// Obtain all parameters passed in the call event.
hilog.info(DOMAIN_NUMBER, TAG, `FunBCall param: ${JSON.stringify(data.readString())}`);
- promptAction.showToast({
- message: 'FunBCall param:' + JSON.stringify(data.readString())
- });
return new MyParcelable(CONST_NUMBER_2, 'bbb');
});
} catch (err) {
@@ -144,7 +144,7 @@ There may be cases you want to provide in a widget access to features available
```
4. Configure the background running permission.
- To receive the call event, the widget provider must add the background running permission ([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/AccessToken/permissions-for-all.md#ohospermissionkeep_background_running)) to the top-level module in the **module.json5** file.
+ To receive the call event, the widget provider must add the background running permission ([ohos.permission.KEEP_BACKGROUND_RUNNING](../security/AccessToken/permissions-for-all.md#ohospermissionkeep_background_running)) to the **module.json5** file.
```ts
//src/main/module.json5
"requestPermissions": [
@@ -155,7 +155,7 @@ There may be cases you want to provide in a widget access to features available
```
5. Configure the UIAbility.
- Add the configuration of the WidgetEventCallEntryAbility to the **abilities** array of the top-level module in the **module.json5** file.
+ Add the WidgetEventCallEntryAbility configuration information to the abilities array in the **module.json5** file.
```ts
//src/main/module.json5
"abilities": [
diff --git a/en/application-dev/form/arkts-ui-widget-event-formeditextensionability-overview.md b/en/application-dev/form/arkts-ui-widget-event-formeditextensionability-overview.md
index 61941c316ba0bf4ab3e43392c8f6f9fe40e607a1..26e40346e191e9669f294a316710a0d37cf4abfb 100644
--- a/en/application-dev/form/arkts-ui-widget-event-formeditextensionability-overview.md
+++ b/en/application-dev/form/arkts-ui-widget-event-formeditextensionability-overview.md
@@ -1,11 +1,14 @@
-# Overview of ArkTs Widget Page Editing Interaction
+# Overview of ArkTS Widget Editing
-The home screen provides a unified widget editing page. The widget provider uses the startSecondPage method provided by FormEditExtensionContext of the FormEditExtensionAbility component to transfer the level-2 editing page information to the home screen. After the home screen opens the level-2 editing page, the page content can be edited.
+ArkTS widgets provide the page editing capability to allow users to customize widget content, for example, editing a contact widget, modifying contacts displayed in a widget, and editing a weather widget.
+
+## How to Implement
+The home screen provides a unified widget editing page. The widget provider uses the [startSecondPage](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md#formeditextensioncontextstartsecondpage) method provided by the FormEditExtensionContext of [FormEditExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formEditExtensionAbility.md) to transfer the level-2 editing page information to the home screen. After the the level-2 editing page is started, the page content can be edited.
The following figure shows the widget editing process.
-Figure 1 Widget editing process
+**Figure 1** Widget editing process
@@ -13,7 +16,7 @@ Figure 1 Widget editing process
2. After the user identifies that the widget provider inherits [FormEditExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formEditExtensionAbility.md), the level-1 editing page of the widget provider is displayed.
-3. The widget provider invokes the [startSecondPage](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md) method of [FormEditExtensionContext](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md) in the callback method [onSessionCreate](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#uiextensionabilityonsessioncreate) of [FormEditExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formEditExtensionAbility.md) to transfer the level-2 page information of the widget provider to be started to the widget management service.
+3. The widget provider invokes the [startSecondPage](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md#formeditextensioncontextstartsecondpage) method of [FormEditExtensionContext](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md) in the callback method [onSessionCreate](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#onsessioncreate) of [FormEditExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formEditExtensionAbility.md) to transfer the level-2 page information of the widget provider to be started to the widget management service.
4. The widget management service transfers the received level-2 page information of the widget provider to the user.
diff --git a/en/application-dev/form/arkts-ui-widget-event-formeditextensionability.md b/en/application-dev/form/arkts-ui-widget-event-formeditextensionability.md
index 91ec52a90ffbd462690372ee12e73c6e18ff0296..14a51f8ba68b0eb9e0d0429dce1633bd586cd832 100644
--- a/en/application-dev/form/arkts-ui-widget-event-formeditextensionability.md
+++ b/en/application-dev/form/arkts-ui-widget-event-formeditextensionability.md
@@ -1,9 +1,9 @@
-# Editing and Updating the Widget Content
+# Widget Editing Development
The home screen provides a unified widget editing page. The widget provider uses [FormEditExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formEditExtensionAbility.md) provided by the widget framework to develop the widget editing function.
## How to Develop
-1. In the entry module of the project, create a code file named EntryFormEditAbility. In the EntryFormEditAbility file, implement the [startSecondPage](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md) method. In the [onSessionCreate](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#uiextensionabilityonsessioncreate) callback method, load the level-1 widget editing page and transfer the implementation of the **startSecondPage** method to the level-1 widget editing page.
+1. In the entry module of the project, create a code file named EntryFormEditAbility. In the EntryFormEditAbility file, implement the [startSecondPage](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md#formeditextensioncontextstartsecondpage) method. In the [onSessionCreate](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md#onsessioncreate) callback method, load the level-1 widget editing page and transfer the implementation of **startSecondPage** to the level-1 widget editing page.
```ts
// src/main/ets/entryformeditability/EntryFormEditAbility.ets
@@ -15,19 +15,19 @@ import { ExtensionEvent } from '../pages/model/ExtensionEvent';
const TAG: string = 'FormEditDemo[EntryFormEditAbility] -->';
export default class EntryFormEditAbility extends FormEditExtensionAbility {
onCreate() {
- console.log(`${TAG} onCreate`);
+ console.info(`${TAG} onCreate`);
}
onForeground(): void {
- console.log(`${TAG} EntryFormEditAbility onForeground.....`);
+ console.info(`${TAG} EntryFormEditAbility onForeground.....`);
}
onBackground(): void {
- console.log(`${TAG} EntryFormEditAbility onBackground......`);
+ console.info(`${TAG} EntryFormEditAbility onBackground......`);
}
onDestroy(): void {
- console.log(`${TAG} EntryFormEditAbility onDestroy......`);
+ console.info(`${TAG} EntryFormEditAbility onDestroy......`);
}
onSessionCreate(want: Want, session: UIExtensionContentSession) {
- console.log(`${TAG} onSessionCreate start..... want: ${JSON.stringify(want)}`);
+ console.info(`${TAG} onSessionCreate start..... want: ${JSON.stringify(want)}`);
let storage: LocalStorage = new LocalStorage();
let extensionEvent: ExtensionEvent = new ExtensionEvent();
extensionEvent.setStartSecondPage(() => this.startSecondPage());
@@ -36,16 +36,16 @@ export default class EntryFormEditAbility extends FormEditExtensionAbility {
session.loadContent('pages/Extension', storage);
session.setWindowBackgroundColor('#00000000');
} catch (e) {
- console.log(`${TAG} EntryFormEditAbility loadContent err, want: ${JSON.stringify(e)}`);
+ console.error(`${TAG} EntryFormEditAbility loadContent err, want: ${JSON.stringify(e)}`);
}
}
onSessionDestroy(session: UIExtensionContentSession) {
- console.log(`${TAG} onSessionDestroy`);
+ console.info(`${TAG} onSessionDestroy`);
}
private startSecondPage(): void {
const bundleName: string = this.context.extensionAbilityInfo.bundleName;
const secPageAbilityName: string = 'FormEditSecPageAbility';
- console.log(`${TAG} startSecondPage. bundleName: ${bundleName}, secPageAbilityName: ${secPageAbilityName}.`);
+ console.info(`${TAG} startSecondPage. bundleName: ${bundleName}, secPageAbilityName: ${secPageAbilityName}.`);
try {
this.context.startSecondPage({
bundleName: bundleName,
@@ -54,7 +54,7 @@ export default class EntryFormEditAbility extends FormEditExtensionAbility {
}
});
} catch (err) {
- console.log(`${TAG} startSecondPage failed: ${err}`);
+ console.error(`${TAG} startSecondPage failed: ${err}`);
}
}
};
@@ -68,7 +68,7 @@ export default class EntryFormEditAbility extends FormEditExtensionAbility {
import { UIExtensionContentSession } from '@kit.AbilityKit';
import { ExtensionEvent } from './model/ExtensionEvent';
-let storage = LocalStorage.getShared();
+let storage = new LocalStorage();
const TAG: string = 'FormEditDemo[Extension] -->';
@Entry(storage)
@Component
@@ -77,7 +77,7 @@ struct Extension {
private session: UIExtensionContentSession | undefined = storage.get('session');
private extensionEvent: ExtensionEvent | undefined = storage.get('extensionEvent');
onPageShow() {
- console.log(`${TAG} onPageShow. extensionEvent: ${JSON.stringify(this.extensionEvent)}, session: ${JSON.stringify(this.session)}.`);
+ console.info(`${TAG} onPageShow. extensionEvent: ${JSON.stringify(this.extensionEvent)}, session: ${JSON.stringify(this.session)}.`);
}
build() {
Row() {
@@ -93,7 +93,7 @@ struct Extension {
top: 20
})
.onClick(() => {
- console.log(`${TAG} Button onClick`);
+ console.info(`${TAG} Button onClick`);
this.extensionEvent?.startFormEditSecondPage();
})
}
@@ -104,7 +104,7 @@ struct Extension {
}
```
-3. Add the ExtensionEvent file and use the **startFormEditSecondPage** method to invoke the [startSecondPage](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md) method.
+3. Add the ExtensionEvent file and use the **startFormEditSecondPage** method to invoke the [startSecondPage](../reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md#formeditextensioncontextstartsecondpage) method.
```ts
// src/main/ets/widget/pages/model/ExtensionEvent.ets
@@ -112,14 +112,14 @@ struct Extension {
const TAG: string = 'FormEditDemo[ExtensionEvent] -->';
export class ExtensionEvent {
private startSecondPage: () => void = () => {
- console.log(`${TAG} startSecondPage is empty!`);
+ console.info(`${TAG} startSecondPage is empty!`);
};
public setStartSecondPage(startSecondPage: () => void) {
- console.log(`${TAG} setStartSecondPage`);
+ console.info(`${TAG} setStartSecondPage`);
this.startSecondPage = startSecondPage;
}
public startFormEditSecondPage(): void {
- console.log(`${TAG} startFormEditSecondPage`);
+ console.info(`${TAG} startFormEditSecondPage`);
this.startSecondPage();
}
}
diff --git a/en/application-dev/form/arkts-ui-widget-event-formextensionability.md b/en/application-dev/form/arkts-ui-widget-event-formextensionability.md
index b4ec85e7f91b460e14b49218c753ae62ea1394a8..f163fa80889a2fb778ff3ae74fa1537c0940117b 100644
--- a/en/application-dev/form/arkts-ui-widget-event-formextensionability.md
+++ b/en/application-dev/form/arkts-ui-widget-event-formextensionability.md
@@ -1,12 +1,12 @@
-# Updating Widget Content Through the message Event
+# Transferring Messages to an Application (message Event)
-On the widget page, the [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction) API can be used to trigger a message event to start a FormExtensionAbility, which then updates the widget content. The following is an example of this widget update mode.
+On the widget page, you can trigger a message event via the [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction) API to launch the **FormExtensionAbility**. The FormExtensionAbility then notifies the application through the **onFormEvent** callback. This process enables the functionality of passing messages to the application after a widget is touched. Subsequently, the **FormExtensionAbility** refreshes the widget content. Below is a simple example.
> **NOTE**
>
> This topic describes development for dynamic widgets. For static widgets, see [FormLink](../reference/apis-arkui/arkui-ts/ts-container-formlink.md).
-- On the widget page, register the **onClick** event callback of the button and call the **postCardAction** API in the callback to trigger the message event to start the FormExtensionAbility. Use [LocalStorageProp](../ui/state-management/arkts-localstorage.md#localstorageprop to decorate the widget data to be updated.
+- On the widget page, register the **onClick** event callback of the button and call the **postCardAction** API in the callback to trigger the message event to start the FormExtensionAbility. Use [LocalStorageProp](../ui/state-management/arkts-localstorage.md#localstorageprop) to decorate the widget data to be updated.
```ts
let storageUpdateByMsg = new LocalStorage();
@@ -74,14 +74,15 @@ On the widget page, the [postCardAction](../reference/apis-arkui/js-apis-postCar
export default class EntryFormAbility extends FormExtensionAbility {
onFormEvent(formId: string, message: string): void {
- // Called when a specified message event defined by the form provider is triggered.
+ // Called when the message event of the postCardAction API of the widget provider is triggered.
hilog.info(DOMAIN_NUMBER, TAG, `FormAbility onFormEvent, formId = ${formId}, message: ${JSON.stringify(message)}`);
class FormDataClass {
- title: string ='Title Update.'; // It matches the widget layout.
+ title: string = 'Title Update.'; // It matches the widget layout.
detail: string = 'Description update success.'; // It matches the widget layout.
}
+ // Replace it with the actual widget data.
let formData = new FormDataClass();
let formInfo: formBindingData.FormBindingData = formBindingData.createFormBindingData(formData);
formProvider.updateForm(formId, formInfo).then(() => {
@@ -96,6 +97,6 @@ On the widget page, the [postCardAction](../reference/apis-arkui/js-apis-postCar
The figure below shows the effect.
- | Initial State | After Clicking |
+ | Initial State | Touch to Refresh |
| ------------------------------------------------------- | ----------------------------------------------------- |
|  |  |
diff --git a/en/application-dev/form/arkts-ui-widget-event-overview.md b/en/application-dev/form/arkts-ui-widget-event-overview.md
index 0324425a2285a9ce2c405127a2c226c597e01dac..a2ea704050f82f621970a86982268dd66605ddf4 100644
--- a/en/application-dev/form/arkts-ui-widget-event-overview.md
+++ b/en/application-dev/form/arkts-ui-widget-event-overview.md
@@ -1,16 +1,7 @@
-# Widget Event Capability Overview
+# Overview of ArkTS Widget Page Interaction
-For dynamic ArkTS widgets, the [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction) API is provided for interaction between the widget internal and the provider application. Currently, this API supports the router, message, and call events and can be called only in the widget.
+ArkTS widgets provide page interaction capabilities, including page redirection between widgets and widget providers (such as applications), process startup of widget providers, and message transfer between widgets and widget providers. You can call [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction) to implement a [dynamic widget](arkts-form-overview.md#dynamic-widget) and use [FormLink](../reference/apis-arkui/arkui-ts/ts-container-formlink.md) to implement page interaction of a [static widget](arkts-form-overview.md#static-widget). Both **postCardAction** and **FormLink** support router, message, and call events. The usage scenarios are as follows:
-For static ArkTS widgets, the [FormLink](../reference/apis-arkui/arkui-ts/ts-container-formlink.md) component is provided for interaction between the widget internal and the provider application.
-
-## Dynamic Widget Event Capability
-
-
-Dynamic widget events are used in the following scenarios:
-- Router event: used to redirect to a UIAbility and update the widget content.
-- Call event: used to start a UIAbility in the background and update the widget content.
-- Message event: used to start a FormExtensionAbility, which then updates the widget content.
-
-## Static Widget Event Capability
-See [FormLink](../reference/apis-arkui/arkui-ts/ts-container-formlink.md).
+- [router event](arkts-ui-widget-event-router.md): used to redirect to a specified UIAbility, enabling the functionality of navigating from a widget to an internal application page after a widget is touched. For non-system applications, this redirection is limited to their own UIAbilities.
+- [call event](arkts-ui-widget-event-call.md): used to launch a specified UIAbility to the background, after which the UIAbility can request the corresponding background continuous task to complete functionalities such as music playback.
+- [message event](arkts-ui-widget-event-formextensionability.md): used to launch the [FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md), which then notifies the application via the **onFormEvent** API callback, thereby fulfilling the functionality of passing messages to the application after a widget is touched.
diff --git a/en/application-dev/form/arkts-ui-widget-event-router.md b/en/application-dev/form/arkts-ui-widget-event-router.md
index e31fc7f88fb74b25d4b6de8e7b18728050d7633a..c47f719230de1fcc40b6ec7887d8c21fc6f500fd 100644
--- a/en/application-dev/form/arkts-ui-widget-event-router.md
+++ b/en/application-dev/form/arkts-ui-widget-event-router.md
@@ -1,4 +1,4 @@
-# Launching the UIAbility of the Widget Provider Through the router Event
+# Redirecting to an Application Page (router Event)
The **router** capability of the [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction) API can be used in a dynamic widget to quickly start a specific UIAbility of the widget provider. By leveraging this capability, an application can provide in the widget multiple buttons, each of which targets a different target UIAbility. For example, a camera widget can provide the buttons that redirect the user to the UIAbility for taking a photo and the UIAbility for recording a video.
diff --git a/en/application-dev/form/arkts-ui-widget-event-uiability.md b/en/application-dev/form/arkts-ui-widget-event-uiability.md
index 26c474de1e93686fd95681d5aaf422beee0d3233..dd9367f42efb245b8ef897aaac293fc3306a2719 100644
--- a/en/application-dev/form/arkts-ui-widget-event-uiability.md
+++ b/en/application-dev/form/arkts-ui-widget-event-uiability.md
@@ -260,7 +260,7 @@ With the router event, a touch on the widget can start the associated applicatio
}
}
```
- To start the UIAbility in the background, you must configure the ohos.permission.KEEP_BACKGROUND_RUNNING permission in the **module.json5** file.
+ To start the UIAbility in the background, you must configure the `ohos.permission.KEEP_BACKGROUND_RUNNING` permission in the `module.json5` file.
```json
"requestPermissions":[
{
diff --git a/en/application-dev/form/arkts-ui-widget-interaction-overview.md b/en/application-dev/form/arkts-ui-widget-interaction-overview.md
index bf16a7af2f24a8e19280ca0b2a4c4e8322e98f63..674c4324d3b89e10120e7105991d5f1fb7560860 100644
--- a/en/application-dev/form/arkts-ui-widget-interaction-overview.md
+++ b/en/application-dev/form/arkts-ui-widget-interaction-overview.md
@@ -1,37 +1,53 @@
-# Updating Widget Content
+# Overview of ArkTS Widget Update
-The ArkTS widget framework provides the updateForm API for widget providers and the **requestForm** API for widget hosts to proactively trigger widget page refreshes. It also alerts providers to update widgets based on the scheduled information.
+Both the widget host (for example, the home screen) and the widget provider can trigger updates to the widget page. Moreover, the widget framework notifies the widget provider of updates according to the scheduled information. Therefore, widget updates include active updates initiated by the widget provider, active updates initiated by the widget host, and interval-based or time-specific updates. In all these update modes, the widget provider is responsible for pushing the widget data to be updated.
-In widget UI code, you can use [LocalStorageProp](../ui/state-management/arkts-localstorage.md#localstorageprop) to obtain the widget data that requires updating, sent by the provider
+## Widget Data Interaction
-| API| System Capability| Constraints|
-| -------- | -------- | -------- |
-| updateForm | No| 1. Invoked by the widget provider.
2. Allows only the widget provider to update its own widgets.|
-| requestForm | Yes| 1. Invoked by the widget host.
2. Allows only the widget host to update the widgets added to it.|
+The ArkTS widget framework provides the data interaction capability between widget providers (for example, applications) and widgets. The widget transfers data to the widget provider through [postCardAction](../reference/apis-arkui/js-apis-postCardAction.md#postcardaction), and the widget provider can transfer data to the widget through [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform). After the widget provider transfers data to the widget, the data can be used for page update.
+The widget provider and widget are independent of each other. Therefore, data can be transferred only through [LocalStorageProp](../ui/state-management/arkts-localstorage.md#localstorageprop), and the **getContext** method cannot be used. After the widget provider pushes data, the widget UI receives it via **LocalStorageProp**, and converts the received data to a string.
+## Page Update Modes
-Widget provider proactively updating a widget
+Widgets can be updated actively or passively based on the triggering mode.
-
+### Active Update
+
+Active updates include the updates triggered by the widget provider and the widget host. For details, see [Active Update of ArkTS Widgets](arkts-ui-widget-active-refresh.md).
-If there is a need to update widget data, the widget provider, as long as it is running, can proactively update the widget using the **updateForm** API provided by formProvider.
+**Figure 1** Flowchart of active update by the widget provider
+
+If there is a need to update widget data, the widget provider, as long as it is running, can proactively update the widget using the [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform) API provided by formProvider.
-Widget host proactively requesting a widget update
+**Figure 2** Flowchart of active update by the widget host
-If changes in system language or color scheme are detected, the widget host, as long as it is running, can proactively request to update the widget using the **requestForm** API provided by formHost. The widget manager then instructs the widget provider to complete the update.
+If changes in system language or color scheme are detected, the widget host, as long as it is running, can proactively request to update the widget using the **requestForm** API provided by formHost. The Widget Manager then instructs the widget provider to complete the update.
+
+### Passive Update
+
+Passive update includes interval-based update, time-specific update, and conditional update. For details, see [Passive Update of ArkTS Widgets](arkts-ui-widget-passive-refresh.md).
+
+Interval-based update: The widget content will be automatically updated at the specified interval by calling [onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonupdateform).
+Time-specific update: The widget content will be automatically updated at a designated time every day.
+
+Conditional update: The widget is updated when a certain condition is met. Currently, it is triggered when the network status of a device changes from unavailable to available.
+
-Widget manager instructing the widget provider to periodically update a widget
+**Figure 3** Flowchart of interval-based and time-specific updates by the widget provider
Based on the scheduled update information configured by the widget provider, the widget manager determines whether to instruct the provider to update the widget, considering factors such as timing information, widget visibility status, and the number of updates.
+## Constraints
+1. The widget provider is only allowed to update its own widgets.
+2. The widget host is only allowed to update the widgets added to it.
diff --git a/en/application-dev/form/arkts-ui-widget-lifecycle.md b/en/application-dev/form/arkts-ui-widget-lifecycle.md
index e4e329cf7027c0e6b0d553f057b7ea6fc336f1f2..a36469e87dedff05972c28028adf68c1dbe4ba28 100644
--- a/en/application-dev/form/arkts-ui-widget-lifecycle.md
+++ b/en/application-dev/form/arkts-ui-widget-lifecycle.md
@@ -1,4 +1,4 @@
-# Widget Lifecycle Management
+# Managing ArkTS Widget Lifecycle
When creating an ArkTS widget, you need to implement the [FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md) lifecycle APIs.
@@ -11,7 +11,7 @@ When creating an ArkTS widget, you need to implement the [FormExtensionAbility](
import { hilog } from '@kit.PerformanceAnalysisKit';
```
-2. In **EntryFormAbility.ets**, implement the [FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md) lifecycle API, including **onAddForm**, in which [want](../reference/apis-ability-kit/js-apis-app-ability-want.md) can be used to obtain the widget information through [FormParam](../reference/apis-form-kit/js-apis-app-form-formInfo.md).
+2. In **EntryFormAbility.ets**, implement the [FormExtensionAbility](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md) lifecycle API, including **onAddForm**, in which [want](../reference/apis-ability-kit/js-apis-app-ability-want.md) can be used to obtain the widget information through [FormParam](../reference/apis-form-kit/js-apis-app-form-formInfo.md#formparam).
```ts
const TAG: string = 'EntryFormAbility';
const DOMAIN_NUMBER: number = 0xFF00;
@@ -41,7 +41,7 @@ When creating an ArkTS widget, you need to implement the [FormExtensionAbility](
}
onUpdateForm(formId: string): void {
- // Override this method to support scheduled updates, periodic updates, or updates requested by the widget host.
+ // Override this method to support interval-based updates, time-specific updates, or updates requested by the widget host.
hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onUpdateForm');
let obj: Record = {
'title': 'titleOnUpdateForm',
@@ -65,9 +65,9 @@ When creating an ArkTS widget, you need to implement the [FormExtensionAbility](
}
onRemoveForm(formId: string): void {
- // Delete widget data.
+ // Remove widget data.
hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onRemoveForm');
- // Delete the persistent widget instance data.
+ // Remove the persistent widget instance data.
// Implement this API based on project requirements.
}
@@ -86,4 +86,4 @@ When creating an ArkTS widget, you need to implement the [FormExtensionAbility](
> **NOTE**
>
-> The FormExtensionAbility cannot reside in the background. It persists for 10 seconds after the lifecycle callback is completed and exits if no new lifecycle callback is invoked during this time frame. This means that continuous tasks cannot be processed in the widget lifecycle callbacks. For the service logic that may take more than 10 seconds to complete, it is recommended that you [start the application](arkts-ui-widget-event-uiability.md) for processing. After the processing is complete, use [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform) to notify the widget of the update.
+> The FormExtensionAbility cannot reside in the background. It persists for 10 seconds after the lifecycle callback is completed and exits if no new lifecycle callback is invoked during this time frame. This means that continuous tasks cannot be processed in the widget lifecycle callbacks. For the service logic that may take more than 10 seconds to complete, it is recommended that you [start the application](arkts-ui-widget-event-overview.md) for processing. After the processing is complete, use [updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formproviderupdateform) to notify the widget of the update.
diff --git a/en/application-dev/form/arkts-ui-widget-open-formmanager.md b/en/application-dev/form/arkts-ui-widget-open-formmanager.md
new file mode 100644
index 0000000000000000000000000000000000000000..23a5e530da08a27eca0b9c4330a3512883667c96
--- /dev/null
+++ b/en/application-dev/form/arkts-ui-widget-open-formmanager.md
@@ -0,0 +1,50 @@
+# Adding Widgets to the Home Screen
+
+You can add ArkTS widgets of an application to the home screen
+
+which manages widgets in a unified manner. Applications can call the [openFormManager](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formprovideropenformmanager18) API provided by the [formProvider](../reference/apis-form-kit/js-apis-app-form-formProvider.md) module to start the widget management page where you can add a widget to the home screen by touching **Add to home screen**.
+
+## How to Develop
+
+Implement the [openFormManager](../reference/apis-form-kit/js-apis-app-form-formProvider.md#formprovideropenformmanager18) method provided by the [formProvider](../reference/apis-form-kit/js-apis-app-form-formProvider.md) API.
+
+```ts
+// entry/src/main/ets/pages/Index.ets
+
+import { formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+import { Want } from '@kit.AbilityKit';
+
+@Entry
+@Component
+struct Index {
+
+ build() {
+ Row() {
+ Column() {
+ // Add a button and call the openFormManager method to start the widget management page.
+ Button('Start the widget management page.')
+ .onClick(() => {
+ const want: Want = {
+ bundleName: 'com.example.formbutton',
+ abilityName: 'EntryFormAbility',
+ parameters: {
+ 'ohos.extra.param.key.form_dimension': 2,
+ 'ohos.extra.param.key.form_name': 'widget',
+ 'ohos.extra.param.key.module_name': 'entry'
+ },
+ };
+ try {
+ formProvider.openFormManager(want);
+ } catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
+ }
+ })
+ .margin({ top: 10, bottom: 10 })
+ }
+ .width('100%')
+ }
+ .height('100%')
+ }
+}
+```
diff --git a/en/application-dev/form/arkts-ui-widget-page-animation.md b/en/application-dev/form/arkts-ui-widget-page-animation.md
index 3929a8aa34d72aab21b180a8c908a371a2d0ae4c..83248f77c1e649aa64e3868e3f473856eab23c89 100644
--- a/en/application-dev/form/arkts-ui-widget-page-animation.md
+++ b/en/application-dev/form/arkts-ui-widget-page-animation.md
@@ -1,11 +1,11 @@
-# Using Animations in the Widget
+# Using Animations in ArkTS Widgets
-To make your ArkTS widget more engaging, you can apply animations to it, including [explicit animation](../reference/apis-arkui/arkui-ts/ts-explicit-animation.md), [property animation](../reference/apis-arkui/arkui-ts/ts-animatorproperty.md), and [component transition](../reference/apis-arkui/arkui-ts/ts-transition-animation-component.md). Just note the following restrictions when using the animations in ArkTS widgets.
+To make your ArkTS widgets more engaging, you can apply animations to it, including [explicit animation](../reference/apis-arkui/arkui-ts/ts-explicit-animation.md), [property animation](../reference/apis-arkui/arkui-ts/ts-animatorproperty.md), and [component transition](../reference/apis-arkui/arkui-ts/ts-transition-animation-component.md). Just note the following restrictions when using the animations in ArkTS widgets.
**Table 1** Restrictions on animation parameters
-| Name| Description| Description|
+| Name| Description| Restriction|
| -------- | -------- | -------- |
| duration | Animation playback duration| The maximum value is 1 second. If a larger value is set, the animation is still played for 1 second.|
| tempo | Animation playback speed.| Do not set this parameter in the widget. Use the default value 1.|
@@ -16,13 +16,15 @@ To make your ArkTS widget more engaging, you can apply animations to it, includi
>
>Static widgets do not support animations.
-The following sample code implements the animation effect of button rotation.
+## Component Animation
+The following sample code uses the [animation](../reference/apis-arkui/arkui-ts/ts-animatorproperty.md) API to implement the animation effect of button rotation.
```ts
+// entry/src/main/ets/widget/pages/WidgetCard.ets
@Entry
@Component
struct AnimationCard {
@@ -46,3 +48,41 @@ struct AnimationCard {
}
}
```
+## Transition Animation
+The following sample code uses the [transition](../reference/apis-arkui/arkui-ts/ts-transition-animation-component.md) API to implement the animation effect of image appearance and disappearance.
+
+
+
+```ts
+// entry/src/main/ets/widget/pages/WidgetCard.ets
+@Entry
+@Component
+struct TransitionEffectExample1 {
+ @State flag: boolean = true;
+ @State show: string = 'show';
+
+ build() {
+ Column() {
+ Button(this.show).width(80).height(30).margin(30)
+ .onClick(() => {
+ // Tap the button to show or hide the image.
+ if (this.flag) {
+ this.show = 'hide';
+ } else {
+ this.show = 'show';
+ }
+ this.flag = !this.flag;
+ })
+ if (this.flag) {
+ // Apply the same transition effect to the appearance and disappearance of the image.
+ // When the image appears, it changes from the state where the opacity is 0 and the rotation angle is 180° around the z-axis to the state where the opacity is 1 and the rotation angle is 0°. The durations of the opacity and rotation animations are both 1000 ms.
+ // When the image disappears, it changes from the state where the opacity is 1 and the rotation angle is 0° to the state where the opacity is 0 and the rotation angle is 180° around the z-axis. The durations of the opacity and rotation animations are both 1000 ms.
+ Image($r('app.media.testImg')).width(200).height(200)
+ .transition(TransitionEffect.OPACITY.animation({ duration: 1000, curve: Curve.Ease }).combine(
+ TransitionEffect.rotate({ z: 1, angle: 180 })
+ ))
+ }
+ }.width('100%')
+ }
+}
+```
diff --git a/en/application-dev/form/arkts-ui-widget-page-custom-drawing.md b/en/application-dev/form/arkts-ui-widget-page-custom-drawing.md
index 38920cdc5aacfe99672410aafba1ef3f2e5c5eea..83aeee2f473d7a94f304e231b1e6dce4f283b0c2 100644
--- a/en/application-dev/form/arkts-ui-widget-page-custom-drawing.md
+++ b/en/application-dev/form/arkts-ui-widget-page-custom-drawing.md
@@ -1,4 +1,4 @@
-# Applying Custom Drawing in the Widget
+# Using Canvas in ArkTS Widgets
You can apply custom drawing in your ArkTS widget to create a more vibrant experience. Use the [\