** component.
```ts
let storagePersis = new LocalStorage();
diff --git a/en/application-dev/form/arkts-ui-widget-update-by-status.md b/en/application-dev/form/arkts-ui-widget-update-by-status.md
index 4905a54afdef26897002e2babb8b790627b140e8..aaef4dd2e875759db5a45afe2c3f0ef3ec70554e 100644
--- a/en/application-dev/form/arkts-ui-widget-update-by-status.md
+++ b/en/application-dev/form/arkts-ui-widget-update-by-status.md
@@ -1,8 +1,7 @@
# Updating Widget Content by State
-There are cases where multiple copies of the same widget are added to the home screen to accommodate different needs. In these cases, the widget content needs to be dynamically updated based on the state. This topic exemplifies how this is implemented.
-In the following example, two copies of the weather widget are added to the home screen: one for displaying the weather of London, and the other Beijing, both configured to be updated at 07:00 every morning. The widget provider detects the target city, and then displays the city-specific weather information on the widgets.
+There are cases where multiple copies of the same widget are added to the home screen to accommodate different needs. In these cases, the widget content needs to be dynamically updated based on the state. This topic exemplifies how this is implemented. In the following example, two copies of the weather widget are added to the home screen: one for displaying the weather of London, and the other Beijing, both configured to be updated at 07:00 every morning. The widget provider detects the target city, and then displays the city-specific weather information on the widgets.
- Widget configuration file: Configure the widget to be automatically updated every 30 minutes.
@@ -251,4 +250,4 @@ In the following example, two copies of the weather widget are added to the home
> **NOTE**
>
-> When the local database is used for widget information persistence, it is recommended that [TEMPORARY_KEY](../reference/apis-form-kit/js-apis-app-form-formInfo.md#formparam) be used in the [onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onaddform) lifecycle callback to determine whether the currently added widget is a normal one. If the widget is a normal one, the widget information is directly persisted. If the widget is a temporary one, the widget information is persisted when the widget is converted to a normal one ([onCastToNormalForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#oncasttonormalform)). In addition, the persistent widget information needs to be deleted when the widget is destroyed ([onRemoveForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onremoveform)), preventing the database size from continuously increasing due to repeated widget addition and deletion.
+> When the local database is used for widget information persistence, it is recommended that [TEMPORARY_KEY](../reference/apis-form-kit/js-apis-app-form-formInfo.md#formparam) be used in the [onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonaddform) lifecycle callback to determine whether the currently added widget is a normal one. If the widget is a normal one, the widget information is directly persisted. If the widget is a temporary one, the widget information is persisted when the widget is converted to a normal one ([onCastToNormalForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityoncasttonormalform)). In addition, the persistent widget information needs to be deleted when the widget is destroyed ([onRemoveForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonremoveform)), preventing the database size from continuously increasing due to repeated widget addition and deletion.
diff --git a/en/application-dev/form/figures/WidgetTransitionAnimation.gif b/en/application-dev/form/figures/WidgetTransitionAnimation.gif
new file mode 100644
index 0000000000000000000000000000000000000000..50803297e76e53ec8f9e69de44eca80da74c2c69
Binary files /dev/null and b/en/application-dev/form/figures/WidgetTransitionAnimation.gif differ
diff --git a/en/application-dev/form/figures/form-process.png b/en/application-dev/form/figures/form-process.png
new file mode 100644
index 0000000000000000000000000000000000000000..117f773dd6b3ffb44e11628da8c95ff32932c56a
Binary files /dev/null and b/en/application-dev/form/figures/form-process.png differ
diff --git a/en/application-dev/form/figures/live-form-base-demo.gif b/en/application-dev/form/figures/live-form-base-demo.gif
new file mode 100644
index 0000000000000000000000000000000000000000..f9f613aa42ebd9de0e1992ae52b16ce3d7a60fe0
Binary files /dev/null and b/en/application-dev/form/figures/live-form-base-demo.gif differ
diff --git a/en/application-dev/form/figures/live-form-click-timeline.png b/en/application-dev/form/figures/live-form-click-timeline.png
new file mode 100644
index 0000000000000000000000000000000000000000..5a1d1a0923e5b49ef80a603067ef8525891a2d0b
Binary files /dev/null and b/en/application-dev/form/figures/live-form-click-timeline.png differ
diff --git a/en/application-dev/form/figures/live-form-game-demo.gif b/en/application-dev/form/figures/live-form-game-demo.gif
new file mode 100644
index 0000000000000000000000000000000000000000..9b3781c79187f301bcfc7ca83cc381e30e3969dd
Binary files /dev/null and b/en/application-dev/form/figures/live-form-game-demo.gif differ
diff --git a/en/application-dev/form/figures/live-form-judge.png b/en/application-dev/form/figures/live-form-judge.png
new file mode 100644
index 0000000000000000000000000000000000000000..647bb81aabcb5cf78b53e75a93ac42f83a84b7fc
Binary files /dev/null and b/en/application-dev/form/figures/live-form-judge.png differ
diff --git a/en/application-dev/form/figures/live-form-overflow-rule.png b/en/application-dev/form/figures/live-form-overflow-rule.png
new file mode 100644
index 0000000000000000000000000000000000000000..d62343f5fe74a6559d69d29df03b7545958c78af
Binary files /dev/null and b/en/application-dev/form/figures/live-form-overflow-rule.png differ
diff --git a/en/application-dev/form/figures/live-form-pause-game.jpg b/en/application-dev/form/figures/live-form-pause-game.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..4047a654da2d8c666b22b507beeda2e7c509fe40
Binary files /dev/null and b/en/application-dev/form/figures/live-form-pause-game.jpg differ
diff --git a/en/application-dev/form/figures/live-form-running-game.gif b/en/application-dev/form/figures/live-form-running-game.gif
new file mode 100644
index 0000000000000000000000000000000000000000..f83b769a9103d6f63384a5e5609348e4ac525b16
Binary files /dev/null and b/en/application-dev/form/figures/live-form-running-game.gif differ
diff --git a/en/application-dev/form/figures/live-form-status-change.png b/en/application-dev/form/figures/live-form-status-change.png
new file mode 100644
index 0000000000000000000000000000000000000000..ae56a713ba0d2006ecf85d01ee5aacbbc6412717
Binary files /dev/null and b/en/application-dev/form/figures/live-form-status-change.png differ
diff --git a/en/application-dev/form/figures/live-form-stop-game.jpg b/en/application-dev/form/figures/live-form-stop-game.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..e21bef7ccaf2fd56046c0a23964ff1dd15aca93d
Binary files /dev/null and b/en/application-dev/form/figures/live-form-stop-game.jpg differ
diff --git a/en/application-dev/form/figures/live-form-update-timeline.png b/en/application-dev/form/figures/live-form-update-timeline.png
new file mode 100644
index 0000000000000000000000000000000000000000..e13330236f9dde5312b13a4500ae7890ec86b194
Binary files /dev/null and b/en/application-dev/form/figures/live-form-update-timeline.png differ
diff --git a/en/application-dev/form/figures/live-form-weather-demo.gif b/en/application-dev/form/figures/live-form-weather-demo.gif
new file mode 100644
index 0000000000000000000000000000000000000000..f972bc04e6152d5a5e69df2376a5232a6f23849e
Binary files /dev/null and b/en/application-dev/form/figures/live-form-weather-demo.gif differ
diff --git a/en/application-dev/form/formkit-overview.md b/en/application-dev/form/formkit-overview.md
index 81e2a40d9e5519a97d576e075dbb6d6c5b8aedd1..5c2bb75903a89a9dcf5da42796e197601123c616 100644
--- a/en/application-dev/form/formkit-overview.md
+++ b/en/application-dev/form/formkit-overview.md
@@ -2,32 +2,28 @@
Form Kit provides a development framework and APIs for embedding application information into system entries like the home screen and lock screen. It can extract key user information or frequent operations into service widgets (referred to as "widgets"), which can be added to the home screen for easy access to information and direct service interactions.
## Scenarios for Widget Usage
-- Devices supported: Widgets can be used on devices such as phones and tablets.
+- Supported devices: smartphones, tablets, PCs/2-in-1 devices, smart TVs, smart watches, and head units. This kit is not supported on lite wearables.
- Type supported: Both applications and atomic services can develop widgets.
- Widget location: Widgets can be added to system applications such as the home screen and lock screen. Currently, they cannot be embedded in common applications.
+- To use a widget:
-## Widget Architecture
-**Figure 1** Widget architecture
+1. Touch and hold an application icon on the home screen to display the shortcut menu.
+2. Touch **Service widget** to access the widget management page and preview the widget.
+3. Touch the **Add to home** button. The widget is then added to the home screen.
+
+**Figure 1** Typical procedure of using a widget
+
+## Widget Architecture
+**Figure 2** Widget architecture
**Fundamental Concepts in Widget Usage Scenarios**
- Widget host: an application that displays the widget content and controls the widget location. It enables direct user interactions and manages widget addition, deletion, and display. An example is the home screen in the preceding figure.
- Widget provider: an application or atomic service that provides the widget. It is responsible for implementing the widget features, including designing the UI, updating data, and handling click interactions.
-
- Widget manager: a system service within the operating system that manages all widget information on the device. As a bridge between widget providers and hosts, it offers capabilities such as querying, adding, and deleting widget information to the hosts, and provides notifications like widget addition, deletion, refresh, and click events to the providers.
-Below is the typical procedure of using a widget:
-
-**Figure 2** Typical procedure of using a widget
-
-
-
-1. Touch and hold an application icon on the home screen to display the shortcut menu.
-2. Touch **Service widget** to access the preview screen.
-3. Touch the **Add to home** button. The widget is then added to the home screen.
-
## Features
- Information display: Key information from applications or atomic services is displayed on the home screen as widgets. The information can be updated periodically so that users can view relevant information at any time.
@@ -60,11 +56,4 @@ ArkTS widgets and JS widgets have different implementation principles and featur
- Ability Kit: Form Kit relies on the Extension abilities of Ability Kit for its internal implementation and interacts with Ability Kit during lifecycle scheduling.
- ArkUI: Form Kit widget hosts can use some components, events, animations, and state management capabilities provided by ArkUI on their pages.
-## Constraints
-**Constraints on UI Capabilities**
-
-Given the limited size of widgets, they are designed to convey straightforward and unambiguous information and support simple interactions. As a result, the scope of UI components and animation features available for use in widget development are somewhat restricted.
-
-**Constraints on Motion Capabilities**
-
-Widgets offer the functionality for applications and atomic services to maintain a constant presence for information display and updates on interfaces like the home screen. However, the system enforces specific constraints on the frequency of updates and the operational capabilities of widgets running in the background.
+
diff --git a/en/application-dev/form/js-ui-widget-development.md b/en/application-dev/form/js-ui-widget-development.md
index 293bcbeffa65c03e8d439ee6d1d1aa0fca2a36dc..5aed588fd5e45b9dd9be4aeba5ce7b1e58a2471d 100644
--- a/en/application-dev/form/js-ui-widget-development.md
+++ b/en/application-dev/form/js-ui-widget-development.md
@@ -1,47 +1,5 @@
-# Developing a JS Widget
-
-
-The following describes how to develop JS widgets based on the web-like development paradigm.
-
-
-## Working Principles
-
-Below shows the working principles of the widget framework.
-
-**Figure 1** Widget framework working principles in the stage model
-
-
-
-The widget host consists of the following modules:
-
-- Widget usage: provides operations such as creating, deleting, or updating a widget.
-
-- Communication adapter: provided by the SDK for communication with the Widget Manager. It sends widget-related operations to the Widget Manager.
-
-The Widget Manager consists of the following modules:
-
-- Periodic updater: starts a scheduled task based on the update policy to periodically update a widget after it is added to the Widget Manager.
-
-- Cache manager: caches view information of a widget after it is added to the Widget Manager. This enables the cached data to be directly returned when the widget is obtained next time, greatly reducing the latency.
-
-- Lifecycle manager: suspends update when a widget is switched to the background or is blocked, and updates and/or clears widget data during upgrade and deletion.
-
-- Object manager: manages RPC objects of the widget host. It is used to verify requests from the widget host and process callbacks after the widget update.
-
-- Communication adapter: communicates with the widget host and provider through RPCs.
-
-The widget provider consists of the following modules:
-
-- Widget service: implemented by the widget provider developer to process requests on widget creation, update, and deletion, and to provide corresponding widget services.
-
-- Instance manager: implemented by the widget provider developer for persistent management of widget instances allocated by the Widget Manager.
-
-- Communication adapter: provided by the SDK for communication with the Widget Manager. It pushes update data to the Widget Manager.
-
-> **NOTE**
->
-> You only need to develop the widget provider. The system automatically handles the work of the widget host and Widget Manager.
-
+# Developing a JS Widget (Stage Model)
+The stage model is supported since API version 9. It is the mainstream model with a long evolution plan. This model is object-oriented and provides open application components as classes. You can derive application components for capability expansion.
## Available APIs
@@ -49,29 +7,29 @@ The **FormExtensionAbility** class has the following APIs. For details, see [For
| Name | Description|
| -------- | -------- |
-| onAddForm(want: Want): formBindingData.FormBindingData | Called to notify the widget provider that a widget is being created.|
-| onCastToNormalForm(formId: string): void | Called to notify the widget provider that a temporary widget is being converted to a normal one.|
-| onUpdateForm(formId: string): void | Called to notify the widget provider that a widget is being updated.|
-| onChangeFormVisibility(newStatus: Record<string, number>): void | Called to notify the widget provider that the widget visibility status is being changed.|
-| onFormEvent(formId: string, message: string): void | Called to instruct the widget provider to process a widget event.|
-| onRemoveForm(formId: string): void | Called to notify the widget provider that a widget is being destroyed.|
-| onConfigurationUpdate(newConfig: Configuration): void | Called when the configuration of the environment where the widget is running is being updated.|
-| onShareForm?(formId: string): Record<string, Object> | Called to notify the widget provider that the widget host is sharing the widget data.|
+| onAddForm(want: Want): formBindingData.FormBindingData | Called to notify the widget provider that a widget is being created.|
+| onCastToNormalForm(formId: string): void | Called to notify the widget provider that a temporary widget is being converted to a normal one.|
+| onUpdateForm(formId: string): void | Called to notify the widget provider that a widget is being updated.|
+| onChangeFormVisibility(newStatus: Record<string, number>): void | Called to notify the widget provider that the widget visibility status is being changed.|
+| onFormEvent(formId: string, message: string): void | Called to instruct the widget provider to process a widget event.|
+| onRemoveForm(formId: string): void | Called to notify the widget provider that a widget is being destroyed.|
+| onConfigurationUpdate(newConfig: Configuration): void | Called when the configuration of the environment where the widget is running is being updated.|
+| onShareForm?(formId: string): Record<string, Object> | Called to notify the widget provider that the widget host is sharing the widget data.|
The **FormProvider** class has the following APIs. For details, see [FormProvider](../reference/apis-form-kit/js-apis-app-form-formProvider.md).
| Name| Description|
| -------- | -------- |
-| setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void | Sets the next refresh time for a widget. This API uses an asynchronous callback to return the result.|
-| setFormNextRefreshTime(formId: string, minute: number): Promise<void> | Sets the next refresh time for a widget. This API uses a promise to return the result.|
-| updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback<void>): void | Updates a widget. This API uses an asynchronous callback to return the result.|
-| updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void> | Updates a widget. This API uses a promise to return the result.|
+| setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void | Sets the next refresh time for a widget. This API uses an asynchronous callback to return the result.|
+| setFormNextRefreshTime(formId: string, minute: number): Promise<void> | Sets the next refresh time for a widget. This API uses a promise to return the result.|
+| updateForm(formId: string, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback<void>): void | Updates a widget. This API uses an asynchronous callback to return the result.|
+| updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void> | Updates a widget. This API uses a promise to return the result.|
The **FormBindingData** class has the following APIs. For details, see [FormBindingData](../reference/apis-form-kit/js-apis-app-form-formBindingData.md).
| Name| Description|
| -------- | -------- |
-| createFormBindingData(obj?: Object \| string): FormBindingData | Creates a **FormBindingData** object.|
+| createFormBindingData(obj?: Object \| string): FormBindingData | Creates a **FormBindingData** object.|
## How to Develop
@@ -400,64 +358,66 @@ You can use the web-like paradigm (HML+CSS+JSON) to develop JS widget pages. Thi
- CSS: defines style information about the web-like paradigm components in HML.
- ```css
- .container {
- flex-direction: column;
- justify-content: center;
- align-items: center;
- }
-
- .bg-img {
- flex-shrink: 0;
- height: 100%;
- }
-
- .container-inner {
- flex-direction: column;
- justify-content: flex-end;
- align-items: flex-start;
- height: 100%;
- width: 100%;
- padding: 12px;
- }
-
- .title {
- font-size: 19px;
- font-weight: bold;
- color: white;
- text-overflow: ellipsis;
- max-lines: 1;
- }
-
- .detail_text {
- font-size: 16px;
- color: white;
- opacity: 0.66;
- text-overflow: ellipsis;
- max-lines: 1;
- margin-top: 6px;
- }
- ```
+
+ ```css
+ .container {
+ flex-direction: column;
+ justify-content: center;
+ align-items: center;
+ }
+
+ .bg-img {
+ flex-shrink: 0;
+ height: 100%;
+ }
+
+ .container-inner {
+ flex-direction: column;
+ justify-content: flex-end;
+ align-items: flex-start;
+ height: 100%;
+ width: 100%;
+ padding: 12px;
+ }
+
+ .title {
+ font-size: 19px;
+ font-weight: bold;
+ color: white;
+ text-overflow: ellipsis;
+ max-lines: 1;
+ }
+
+ .detail_text {
+ font-size: 16px;
+ color: white;
+ opacity: 0.66;
+ text-overflow: ellipsis;
+ max-lines: 1;
+ margin-top: 6px;
+ }
+ ```
- JSON: defines data and event interaction on the widget UI page.
- ```json
- {
- "data": {
- "title": "TitleDefault",
- "detail": "TextDefault"
- },
- "actions": {
- "routerEvent": {
- "action": "router",
- "abilityName": "EntryAbility",
- "params": {
- "message": "add detail"
- }
+
+ ```json
+ {
+ "data": {
+ "title": "TitleDefault",
+ "detail": "TextDefault"
+ },
+ "actions": {
+ "routerEvent": {
+ "action": "router",
+ "abilityName": "EntryAbility",
+ "params": {
+ "message": "add detail"
}
}
}
- ```
+ }
+ ```
### Developing Widget Events
@@ -483,6 +443,7 @@ The following are examples:
- HML file:
+
```html
@@ -501,94 +462,96 @@ The following are examples:
- CSS file:
- ```css
- .container {
- flex-direction: column;
- justify-content: center;
- align-items: center;
- }
-
- .bg-img {
- flex-shrink: 0;
- height: 100%;
- z-index: 1;
- }
-
- .bottom-img {
- position: absolute;
- width: 150px;
- height: 56px;
- top: 63%;
- background-color: rgba(216, 216, 216, 0.15);
- filter: blur(20px);
- z-index: 2;
- }
-
- .container-inner {
- flex-direction: column;
- justify-content: flex-end;
- align-items: flex-start;
- height: 100%;
- width: 100%;
- padding: 12px;
- }
-
- .title {
- font-family: HarmonyHeiTi-Medium;
- font-size: 14px;
- color: rgba(255, 255, 255, 0.90);
- letter-spacing: 0.6px;
- font-weight: 500;
- width: 100%;
- text-overflow: ellipsis;
- max-lines: 1;
- }
-
- .detail_text {
- ffont-family: HarmonyHeiTi;
- font-size: 12px;
- color: rgba(255, 255, 255, 0.60);
- letter-spacing: 0.51px;
- font-weight: 400;
- text-overflow: ellipsis;
- max-lines: 1;
- margin-top: 6px;
- width: 100%;
- }
- ```
+
+ ```css
+ .container {
+ flex-direction: column;
+ justify-content: center;
+ align-items: center;
+ }
+
+ .bg-img {
+ flex-shrink: 0;
+ height: 100%;
+ z-index: 1;
+ }
+
+ .bottom-img {
+ position: absolute;
+ width: 150px;
+ height: 56px;
+ top: 63%;
+ background-color: rgba(216, 216, 216, 0.15);
+ filter: blur(20px);
+ z-index: 2;
+ }
+
+ .container-inner {
+ flex-direction: column;
+ justify-content: flex-end;
+ align-items: flex-start;
+ height: 100%;
+ width: 100%;
+ padding: 12px;
+ }
+
+ .title {
+ font-family: HarmonyHeiTi-Medium;
+ font-size: 14px;
+ color: rgba(255, 255, 255, 0.90);
+ letter-spacing: 0.6px;
+ font-weight: 500;
+ width: 100%;
+ text-overflow: ellipsis;
+ max-lines: 1;
+ }
+
+ .detail_text {
+ ffont-family: HarmonyHeiTi;
+ font-size: 12px;
+ color: rgba(255, 255, 255, 0.60);
+ letter-spacing: 0.51px;
+ font-weight: 400;
+ text-overflow: ellipsis;
+ max-lines: 1;
+ margin-top: 6px;
+ width: 100%;
+ }
+ ```
- JSON file:
- ```json
- {
- "data": {
- "title": "TitleDefault",
- "detail": "TextDefault"
+
+ ```json
+ {
+ "data": {
+ "title": "TitleDefault",
+ "detail": "TextDefault"
+ },
+ "actions": {
+ "routerEvent": {
+ "action": "router",
+ "abilityName": "JSCardEntryAbility",
+ "params": {
+ "info": "router info",
+ "message": "router message"
+ }
},
- "actions": {
- "routerEvent": {
- "action": "router",
- "abilityName": "JSCardEntryAbility",
- "params": {
- "info": "router info",
- "message": "router message"
- }
- },
- "messageEvent": {
- "action": "message",
- "params": {
- "detail": "message detail"
- }
+ "messageEvent": {
+ "action": "message",
+ "params": {
+ "detail": "message detail"
}
}
}
- ```
+ }
+ ```
> **NOTE**
>
> **JSON Value** in **data** supports multi-level nested data. When updating data, ensure that complete data is carried.
-Assume that a widget is displaying the course information of Mr. Zhang on July 18, as shown in the following code snippet.
+ Assume that a widget is displaying the course information of Mr. Zhang on July 18, as shown in the following code snippet.
```ts
"data": {
"Day": "07.18",
@@ -598,7 +561,7 @@ Assume that a widget is displaying the course information of Mr. Zhang on July 1
}
}
```
-To update the widget content to the course information of Mr. Li on July 18, you must pass the complete data as follows, instead of only a single date item such as **name** or **course**:
+ To update the widget content to the course information of Mr. Li on July 18, you must pass the complete data as follows, instead of only a single date item such as **name** or **course**:
```ts
"teacher": {
"name": "Mr.Li",
@@ -609,53 +572,55 @@ To update the widget content to the course information of Mr. Li on July 18, you
- Receive the router event in UIAbility and obtain parameters.
- ```ts
- import UIAbility from '@ohos.app.ability.UIAbility';
- import AbilityConstant from '@ohos.app.ability.AbilityConstant';
- import Want from '@ohos.app.ability.Want';
- import hilog from '@ohos.hilog';
-
- const TAG: string = 'EtsCardEntryAbility';
- const DOMAIN_NUMBER: number = 0xFF00;
-
- export default class EtsCardEntryAbility extends UIAbility {
- onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
- if (want.parameters) {
- let params: Record = JSON.parse(JSON.stringify(want.parameters.params));
- // Obtain the info parameter passed in the router event.
- if (params.info === 'router info') {
- // Execute the service logic.
- hilog.info(DOMAIN_NUMBER, TAG, `router info: ${params.info}`);
- }
- // Obtain the message parameter passed in the router event.
- if (params.message === 'router message') {
- // Execute the service logic.
- hilog.info(DOMAIN_NUMBER, TAG, `router message: ${params.message}`);
- }
+
+ ```ts
+ import UIAbility from '@ohos.app.ability.UIAbility';
+ import AbilityConstant from '@ohos.app.ability.AbilityConstant';
+ import Want from '@ohos.app.ability.Want';
+ import hilog from '@ohos.hilog';
+
+ const TAG: string = 'EtsCardEntryAbility';
+ const DOMAIN_NUMBER: number = 0xFF00;
+
+ export default class EtsCardEntryAbility extends UIAbility {
+ onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
+ if (want.parameters) {
+ let params: Record = JSON.parse(JSON.stringify(want.parameters.params));
+ // Obtain the info parameter passed in the router event.
+ if (params.info === 'router info') {
+ // Execute the service logic.
+ hilog.info(DOMAIN_NUMBER, TAG, `router info: ${params.info}`);
+ }
+ // Obtain the message parameter passed in the router event.
+ if (params.message === 'router message') {
+ // Execute the service logic.
+ hilog.info(DOMAIN_NUMBER, TAG, `router message: ${params.message}`);
}
}
- };
- ```
+ }
+ };
+ ```
- Receive the message event in FormExtensionAbility and obtain parameters.
- ```ts
- import FormExtension from '@ohos.app.form.FormExtensionAbility';
- import hilog from '@ohos.hilog';
-
- const TAG: string = 'FormAbility';
- const DOMAIN_NUMBER: number = 0xFF00;
-
- export default class FormAbility extends FormExtension {
- onFormEvent(formId: string, message: string): void {
- // If the widget supports event triggering, override this method and implement the trigger.
- hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onFormEvent');
- // Obtain the detail parameter passed in the message event.
- let msg: Record = JSON.parse(message);
- if (msg.detail === 'message detail') {
- // Execute the service logic.
- hilog.info(DOMAIN_NUMBER, TAG, 'message info:' + msg.detail);
- }
+
+ ```ts
+ import FormExtension from '@ohos.app.form.FormExtensionAbility';
+ import hilog from '@ohos.hilog';
+
+ const TAG: string = 'FormAbility';
+ const DOMAIN_NUMBER: number = 0xFF00;
+
+ export default class FormAbility extends FormExtension {
+ onFormEvent(formId: string, message: string): void {
+ // If the widget supports event triggering, override this method and implement the trigger.
+ hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onFormEvent');
+ // Obtain the detail parameter passed in the message event.
+ let msg: Record = JSON.parse(message);
+ if (msg.detail === 'message detail') {
+ // Execute the service logic.
+ hilog.info(DOMAIN_NUMBER, TAG, 'message info:' + msg.detail);
}
- };
- ```
\ No newline at end of file
+ }
+ };
+ ```
diff --git a/en/application-dev/form/js-ui-widget-overview.md b/en/application-dev/form/js-ui-widget-overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..2e3bd6375b07ed745fed4c7ef68d017bb9f1e466
--- /dev/null
+++ b/en/application-dev/form/js-ui-widget-overview.md
@@ -0,0 +1,41 @@
+# JS Widget Overview
+
+JS widgets, developed using a web-like paradigm (HML + CSS + JSON), now support two [application models](../application-models/application-models.md): the FA model and the stage model. For details, see [Developing a JS Widget (Stage Model)](js-ui-widget-development.md) and [Developing a JS Widget (FA Model)](widget-development-fa.md). When developing a new widget, you are advised to use the ArkTS declarative syntax to build UIs. For details about the differences between the declarative paradigm and web-like paradigm, see [Introduction to ArkUI](../ui/arkui-overview.md).
+
+## How to Implement
+
+Below shows the working principles of the widget framework.
+
+**Figure 1** Working principles
+
+
+
+The widget host consists of the following modules:
+
+- Widget usage: provides operations such as creating, deleting, or updating a widget.
+
+- Communication adapter: provided by the SDK for communication with the Widget Manager. It sends widget-related operations to the Widget Manager.
+
+The Widget Manager consists of the following modules:
+
+- Periodic update: starts a scheduled task based on the update policy to periodically update a widget after it is added to the Widget Manager.
+
+- Cache manager: caches view information of a widget after it is added to the Widget Manager. This enables the cached data to be directly returned when the widget is obtained next time, greatly reducing the latency.
+
+- Lifecycle manager: suspends update when a widget is switched to the background or is blocked, and updates and/or clears widget data during upgrade and deletion.
+
+- Object manager: manages RPC objects of the widget host. It is used to verify requests from the widget host and process callbacks after the widget update.
+
+- Communication adapter: communicates with the widget host and provider through RPCs.
+
+The widget provider consists of the following modules:
+
+- Widget service: implemented by the widget provider developer to process requests on widget creation, update, and deletion, and to provide corresponding widget services.
+
+- Instance manager: implemented by the widget provider developer for persistent management of widget instances allocated by the Widget Manager.
+
+- Communication adapter: provided by the SDK for communication with the Widget Manager. It pushes update data to the Widget Manager.
+
+> **NOTE**
+>
+> You only need to develop the widget provider. The system automatically handles the work of the widget host and Widget Manager.
diff --git a/en/application-dev/form/widget-development-fa.md b/en/application-dev/form/widget-development-fa.md
index 3e141b09350e282dcf97dd4fde1c7de73a493bfa..373bf59013aa32a1c3c08f77d82cb10d49661f7b 100644
--- a/en/application-dev/form/widget-development-fa.md
+++ b/en/application-dev/form/widget-development-fa.md
@@ -1,59 +1,5 @@
-# Service Widget Development in FA Model
-
-
-## Widget Overview
-
-A service widget (also called 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 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.
-
-Before you get started, it would be helpful if you have a basic understanding of the following concepts:
-
-- 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.
-
-- 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.
-
-
-## Working Principles
-
-Figure 1 shows the working principles of the widget framework.
-
-**Figure 1** Widget framework working principles in the FA model
-
-
-
-The widget host consists of the following modules:
-
-- Widget usage: provides operations such as creating, deleting, or updating a widget.
-
-- Communication adapter: provided by the OpenHarmony SDK for communication with the Widget Manager. It sends widget-related operations to the Widget Manager.
-
-The Widget Manager consists of the following modules:
-
-- Periodic updater: starts a scheduled task based on the update policy to periodically update a widget after it is added to the Widget Manager.
-
-- Cache manager: caches view information of a widget after it is added to the Widget Manager to directly return the cached data when the widget is obtained next time. This reduces the latency greatly.
-
-- Lifecycle manager: suspends update when a widget is switched to the background or is blocked, and updates and/or clears widget data during upgrade and deletion.
-
-- Object manager: manages RPC objects of the widget host. It is used to verify requests from the widget host and process callbacks after the widget update.
-
-- Communication adapter: communicates with the widget host and provider through RPCs.
-
-The widget provider consists of the following modules:
-
-- Widget service: implemented by the widget provider developer to process requests on widget creation, update, and deletion, and to provide corresponding widget services.
-
-- Instance manager: implemented by the widget provider developer for persistent management of widget instances allocated by the Widget Manager.
-
-- Communication adapter: provided by the OpenHarmony SDK for communication with the Widget Manager. It pushes update data to the Widget Manager.
-
-> **NOTE**
->
-> You only need to develop the widget provider. The system automatically handles the work of the widget host and Widget Manager.
-
+# Developing a JS Widget (FA Model)
+The FA model is supported since API version 7, and no longer recommended. Application components are specified by exporting anonymous objects and fixed entry files. You cannot perform derivation for capability expansion. Now, the stage model is recommended for application development.
## Available APIs
@@ -64,7 +10,7 @@ The **FormAbility** has the following APIs.
| 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: Record<string, number>): void | Called to notify the widget provider of the change in widget visibility.|
+| onVisibilityChange(newStatus: Record<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 widget has been destroyed.|
| onAcquireFormState?(want: Want): formInfo.FormState | Called to instruct the widget provider to receive the status query result of a widget.|
@@ -300,7 +246,7 @@ The widget configuration file is named **config.json**. Find the **config.json**
| 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. The value can be:
**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**)|
+ | colorMode(deprecated) | 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.
**NOTE**
This API is deprecated since API version 20. The color mode follows the system 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.
**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|
@@ -335,7 +281,6 @@ The widget configuration file is named **config.json**. Find the **config.json**
"defaultDimension": "2*2",
"name": "widget",
"description": "This is a service widget.",
- "colorMode": "auto",
"type": "JS",
"formVisibleNotify": true,
"supportDimensions": [
diff --git a/en/application-dev/form/widget-host-development-guide.md b/en/application-dev/form/widget-host-development-guide.md
index 6f58b68ffa9d6cb9a4b94c5c8ab314a14d4d1eb6..0fd70b9f9fbd49e414043dec8c1c27a5be71e153 100644
--- a/en/application-dev/form/widget-host-development-guide.md
+++ b/en/application-dev/form/widget-host-development-guide.md
@@ -37,7 +37,7 @@ Carry out the following operations to develop the widget host based on the stage
>
> - The APIs provided by this component are system APIs.
-When a widget is added through **FormComponent**, the [onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onaddform) API in **FormExtensionAbility** of the widget provider is called.
+When a widget is added through **FormComponent**, the [onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#formextensionabilityonaddform) API in **FormExtensionAbility** of the widget provider is called.
### Temporary and Normal Widgets
@@ -107,7 +107,6 @@ struct formHostSample {
descriptionId: 0,
type: formInfo.FormType.eTS,
jsComponentName: '',
- colorMode: formInfo.ColorMode.MODE_AUTO,
isDefault: false,
updateEnabled: false,
formVisibleNotify: true,
@@ -131,14 +130,14 @@ struct formHostSample {
try {
// Check whether the system is ready.
formHost.isSystemReady().then(() => {
- console.log('formHost isSystemReady success');
+ console.info('formHost isSystemReady success');
// Subscribe to events indicating that a widget becomes invisible and events indicating that a widget becomes visible.
let notifyInvisibleCallback = (data: formInfo.RunningFormInfo[]) => {
- console.log(`form change invisibility, data: ${JSON.stringify(data)}`);
+ console.info(`form change invisibility, data: ${JSON.stringify(data)}`);
}
let notifyVisibleCallback = (data: formInfo.RunningFormInfo[]) => {
- console.log(`form change visibility, data: ${JSON.stringify(data)}`);
+ console.info(`form change visibility, data: ${JSON.stringify(data)}`);
}
formObserver.on('notifyInvisible', notifyInvisibleCallback);
formObserver.on('notifyVisible', notifyVisibleCallback);
@@ -152,7 +151,7 @@ struct formHostSample {
} catch (errData) {
let message = (errData as BusinessError).message;
let errCode = (errData as BusinessError).code;
- console.log(`errData is errCode:${errCode} message:${message}`);
+ console.error(`errData is errCode:${errCode} message:${message}`);
}
// Subscribe to bundle update events.
try {
@@ -163,7 +162,7 @@ struct formHostSample {
} catch (errData) {
let message = (errData as BusinessError).message;
let errCode = (errData as BusinessError).code;
- console.log(`errData is errCode:${errCode} message:${message}`);
+ console.error(`errData is errCode:${errCode} message:${message}`);
}
// Subscribe to bundle uninstall events.
try {
@@ -174,7 +173,7 @@ struct formHostSample {
} catch (errData) {
let message = (errData as BusinessError).message;
let errCode = (errData as BusinessError).code;
- console.log(`errData is errCode:${errCode} message:${message}`);
+ console.error(`errData is errCode:${errCode} message:${message}`);
}
}).catch((error: BusinessError) => {
console.error(`error, code: ${error.code}, message: ${error.message}`);
@@ -188,7 +187,7 @@ struct formHostSample {
aboutToDisappear(): void {
// Delete all widgets.
this.formIds.forEach((id) => {
- console.log('delete all form')
+ console.info('delete all form')
formHost.deleteForm(id);
});
// Unsubscribe from bundle installation events.
@@ -197,7 +196,7 @@ struct formHostSample {
} catch (errData) {
let message = (errData as BusinessError).message;
let errCode = (errData as BusinessError).code;
- console.log(`errData is errCode:${errCode} message:${message}`);
+ console.error(`errData is errCode:${errCode} message:${message}`);
}
// Unsubscribe from bundle update events.
try {
@@ -205,7 +204,7 @@ struct formHostSample {
} catch (errData) {
let message = (errData as BusinessError).message;
let errCode = (errData as BusinessError).code;
- console.log(`errData is errCode:${errCode} message:${message}`);
+ console.error(`errData is errCode:${errCode} message:${message}`);
}
// Unsubscribe from bundle uninstall events.
try {
@@ -213,7 +212,7 @@ struct formHostSample {
} catch (errData) {
let message = (errData as BusinessError).message;
let errCode = (errData as BusinessError).code;
- console.log(`errData is errCode:${errCode} message:${message}`);
+ console.error(`errData is errCode:${errCode} message:${message}`);
}
// Unsubscribe from events indicating that a widget becomes invisible and events indicating that a widget becomes visible.
formObserver.off('notifyInvisible');
@@ -227,7 +226,7 @@ struct formHostSample {
let formHapRecordMap: HashMap = new HashMap();
this.formInfoRecord = [];
formHost.getAllFormsInfo().then((formList: Array) => {
- console.log('getALlFormsInfo size:' + formList.length)
+ console.info('getALlFormsInfo size:' + formList.length)
for (let formItemInfo of formList) {
let formBundleName = formItemInfo.bundleName;
if (formHapRecordMap.hasKey(formBundleName)) {
@@ -276,8 +275,8 @@ struct formHostSample {
Button($r('app.string.selectAddForm'))
.enabled(this.showFormPicker)
.onClick(() => {
- console.info("TextPickerDialog: show()")
- TextPickerDialog.show({
+ console.info("showTextPickerDialog")
+ this.getUIContext().showTextPickerDialog({
range: this.formInfoRecord,
selected: this.pickDialogIndex,
canLoop: false,
@@ -337,12 +336,12 @@ struct formHostSample {
.borderRadius(10)
.borderWidth(1)
.onAcquired((form: FormCallbackInfo) => {
- console.log(`onAcquired: ${JSON.stringify(form)}`)
+ console.info(`onAcquired: ${JSON.stringify(form)}`)
this.selectFormId = form.id.toString();
this.formIds.add(this.selectFormId);
})
.onRouter(() => {
- console.log(`onRouter`)
+ console.info(`onRouter`)
})
.onError((error) => {
console.error(`onError: ${JSON.stringify(error)}`)
@@ -350,7 +349,7 @@ struct formHostSample {
})
.onUninstall((info: FormCallbackInfo) => {
this.showForm = false;
- console.error(`onUninstall: ${JSON.stringify(info)}`)
+ console.info(`onUninstall: ${JSON.stringify(info)}`)
this.formIds.remove(this.selectFormId);
})
@@ -395,7 +394,7 @@ struct formHostSample {
if (error) {
console.error(`deleteForm error, code: ${error.code}, message: ${error.message}`);
} else {
- console.log('formHost deleteForm success');
+ console.info('formHost deleteForm success');
}
});
} catch (error) {
diff --git a/en/application-dev/reference/apis-form-kit/Readme-EN.md b/en/application-dev/reference/apis-form-kit/Readme-EN.md
index 3aeb89e9b83a731b582c4989103099100787a541..feb028ddda05fdebf74bc3f6f13849c0b20368d8 100644
--- a/en/application-dev/reference/apis-form-kit/Readme-EN.md
+++ b/en/application-dev/reference/apis-form-kit/Readme-EN.md
@@ -6,6 +6,7 @@
- [@ohos.app.form.formInfo (FormInfo)](js-apis-app-form-formInfo.md)
- [@ohos.app.form.formProvider (FormProvider)](js-apis-app-form-formProvider.md)
- [@ohos.app.form.FormEditExtensionAbility (FormEditExtensionAbility)](js-apis-app-form-formEditExtensionAbility.md)
+ - [@ohos.app.form.LiveFormExtensionAbility (LiveFormExtensionAbility)](js-apis-app-form-LiveFormExtensionAbility.md)
- [@ohos.app.form.formAgent (FormAgent) (System API)](js-apis-app-form-formAgent-sys.md)
- [@ohos.app.form.FormExtensionAbility (FormExtensionAbility) (System API)](js-apis-app-form-formExtensionAbility-sys.md)
@@ -17,6 +18,7 @@
- application
- [FormExtensionContext](js-apis-inner-application-formExtensionContext.md)
- [FormEditExtensionContext](js-apis-inner-application-formEditExtensionContext.md)
+ - [LiveFormExtensionContext](js-apis-application-LiveFormExtensionContext.md)
- [FormExtensionContext (System API)](js-apis-inner-application-formExtensionContext-sys.md)
diff --git a/en/application-dev/reference/apis-form-kit/errorcode-form.md b/en/application-dev/reference/apis-form-kit/errorcode-form.md
index 709aa6075e891300b399bd855a5bc34fba0698d9..69683a50f00a906234fadfe934842b8e4d6e9455 100644
--- a/en/application-dev/reference/apis-form-kit/errorcode-form.md
+++ b/en/application-dev/reference/apis-form-kit/errorcode-form.md
@@ -4,24 +4,6 @@
>
> This topic describes only module-specific error codes. For details about universal error codes, see [Universal Error Codes](../errorcode-universal.md).
-## 16500001 Internal Error
-
-**Error Message**
-
-Internal error.
-
-**Description**
-
-A common kernel error, for example, a malloc failure, occurs.
-
-**Possible Causes**
-
-The memory is insufficient.
-
-**Solution**
-
-Analyze the memory usage of the entire process, and check whether memory leakage occurs.
-
## 16500050 IPC Failure
**Error Message**
@@ -149,42 +131,43 @@ The widget does not belong to the application.
1. Check the ownership of the widget ID.
2. Upgrade the application permission to **SystemApp**.
-## 16501004 Ability Not Installed
+## 16501006 Failed to Connect to the Widget Rendering Service
**Error Message**
-The ability is not installed.
+FormRenderService is stopped. Connect to the service again.
**Description**
-The specified ability is not installed.
+This error code is reported when the widget rendering service fails to be connected.
**Possible Causes**
-The specified ability is not installed.
+The service is busy.
**Solution**
-Pass in valid **abilityName** and **bundleName**.
+Try again later.
-## 16501005 Failed to Connect to FormRenderService
+## 16501007 Untrusted Widget
**Error Message**
-Failed to connect to FormRenderService.
+Form is not trust.
**Description**
-The FormRenderService fails to be connected.
+The widget is not trusted.
**Possible Causes**
-The service is busy.
+The widget code has problems such as infinite loop and memory leakage, causing system exceptions.
**Solution**
-Try again later.
+Check whether the widget code has an infinite loop or memory leakage.
+
## 16501008 Adding a Widget to the Home Screen Times Out
**Error Message**
@@ -202,3 +185,158 @@ The service is busy.
**Solution**
Try again later.
+
+
+## 16501010 Failed to Set the Background Image of the Interactive Widget
+
+**Error Message**
+
+Failed to set the live form background image.
+
+**Description**
+
+This error code is reported when the background image resource is invalid.
+
+**Possible Causes**
+
+The background image resource is invalid.
+
+**Solution**
+
+Check whether the background image resource is valid.
+
+## 16501011 Interactive Capabilities Not Supported
+
+**Error Message**
+
+The form can not support this operation, please check your fom_config's sceneAnimationParams configuration infomation is correct or not.
+
+**Description**
+
+This error code is reported when the current widget does not support interactive capabilities.
+
+**Possible Causes**
+
+The interactive widget animation is requested by a common widget, or the current interactive widget is incorrectly configured.
+
+**Solution**
+
+Check whether the configured [sceneAnimationParams](../../form/arkts-ui-widget-configuration.md#sceneanimationparams-field) of the current widget is correct.
+
+## 2293761 Internal Service Error
+
+**Error Message**
+
+Some internal server error occurs.
+
+**Description**
+
+An internal error occurs when the system executes the current request.
+
+**Possible Causes**
+
+An internal service execution exception occurs.
+
+**Solution**
+
+1. Restart the system and try again.
+2. If the restart still fails, submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#) to obtain help.
+
+## 2293766 Requested Bundle Name Not Exist
+
+**Error Message**
+
+The requested bundle name does not exist.
+
+**Description**
+
+The requested bundle name does not exist. This is an internal error.
+
+**Possible Causes**
+
+An error occurs when the bundle management module obtains the bundle name of the requester. This is an internal service execution exception.
+
+**Solution**
+
+1. Restart the system and try again.
+2. If the restart still fails, submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#) to obtain help.
+
+## 2293767 Invalid Parameter
+
+**Error Message**
+
+Invalid params received on operating form.
+
+**Description**
+
+Invalid input parameters are passed when the API is called.
+
+**Possible Causes**
+
+1. Mandatory parameters are not transferred.
+2. The parameter type is incorrect.
+3. The number of parameters is incorrect.
+4. The input parameter is empty, for example, an empty string ('').
+5. Incorrect parameter format.
+6. Invalid parameter value. The input parameter must be the same as the corresponding configuration in [app.json5](../../quick-start/app-configuration-file.md) and [Configuring Widget Configuration Files](../../form/arkts-ui-widget-configuration.md).
+
+**Solution**
+
+Check the possible causes to determine whether mandatory parameters are transferred and whether the transferred parameter types are correct.
+
+## 2293795 Failed to Obtain the Bundle Manager Service
+
+**Error Message**
+
+Get bms rpc failed.
+
+**Description**
+
+Failed to obtain the Bundle Manager service.
+
+**Possible Causes**
+
+An internal service execution exception occurs.
+
+**Solution**
+
+1. Restart the system and try again.
+2. If the restart still fails, submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#) to obtain help.
+
+## 2293798 Failed to Obtain the Widget Manager Service
+
+**Error Message**
+
+Get fms rpc failed.
+
+**Description**
+
+Failed to obtain the Widget Manager service.
+
+**Possible Causes**
+
+An internal service execution exception occurs.
+
+**Solution**
+
+1. Restart the system and try again.
+2. If the restart still fails, submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#) to obtain help.
+
+## 2293802 Failed to Obtain the System Manager Service
+
+**Error Message**
+
+Get system manager service failed.
+
+**Description**
+
+Failed to obtain the System Manager service.
+
+**Possible Causes**
+
+An internal service execution exception occurs.
+
+**Solution**
+
+1. Restart the system and try again.
+2. If the restart still fails, submit an [online ticket](https://developer.huawei.com/consumer/en/support/feedback/#) to obtain help.
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md b/en/application-dev/reference/apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md
new file mode 100644
index 0000000000000000000000000000000000000000..8fefaf3c724eae04a9e5f36899c4f38970c4b080
--- /dev/null
+++ b/en/application-dev/reference/apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md
@@ -0,0 +1,110 @@
+# @ohos.app.form.LiveFormExtensionAbility (LiveFormExtensionAbility)
+
+The **LiveFormExtensionAbility** module, inherited from [ExtensionAbility](../apis-ability-kit/js-apis-app-ability-extensionAbility.md), provides interactive widget functions, including creating and destroying interactive widgets.
+
+> **NOTE**
+>
+> The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version.
+>
+> The APIs of this module can be used only in the stage model.
+
+## Modules to Import
+
+```ts
+import { LiveFormExtensionAbility } from '@kit.FormKit';
+```
+## LiveFormExtensionAbility
+Interactive widget extension class. It provides APIs for the widget provider to receive notifications about widget creation and destruction.
+
+### Properties
+
+**Model restriction**: This API can be used only in the stage model.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Atomic service API**: This API can be used in atomic services since API version 20.
+
+| Name| Type | Read-Only| Optional |Description|
+| ------ | ------ | ---- | ---- | ---- |
+| context | [LiveFormExtensionContext](./js-apis-application-LiveFormExtensionContext.md) | No | No|Context of the **LiveFormExtensionAbility**. This context is inherited from [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md).|
+
+### onLiveFormCreate
+
+onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession): void
+
+Called after the UI content of **LiveFormExtensionAbility** is created.
+
+**Model restriction**: This API can be used only in the stage model.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Atomic service API**: This API can be used in atomic services since API version 20.
+
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| liveFormInfo | [LiveFormInfo](#liveforminfo) | Yes| Interactive widget information, including the widget ID.|
+| session | [UIExtensionContentSession](../apis-ability-kit/js-apis-app-ability-uiExtensionContentSession.md) | Yes| UI information.|
+
+**Example**
+
+```ts
+import { UIExtensionContentSession } from '@kit.AbilityKit';
+import { LiveFormExtensionAbility, LiveFormInfo } from '@kit.FormKit';
+
+const TAG: string = '[testTag] LiveFormExtAbility';
+
+export default class LiveFormExtAbility extends LiveFormExtensionAbility {
+ onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession) {
+ console.info(TAG, `onLiveFormCreate, liveFormInfo: ${JSON.stringify(liveFormInfo)}`);
+ }
+}
+```
+
+### onLiveFormDestroy
+
+onLiveFormDestroy(liveFormInfo: LiveFormInfo): void
+
+Called to clear resources when this **LiveFormExtensionAbility** is destroyed.
+
+**Model restriction**: This API can be used only in the stage model.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Atomic service API**: This API can be used in atomic services since API version 20.
+
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| liveFormInfo | [LiveFormInfo](#liveforminfo) | Yes| Interactive widget information, including the widget ID.|
+
+**Example**
+
+```ts
+import { LiveFormExtensionAbility, LiveFormInfo } from '@kit.FormKit';
+
+const TAG: string = '[testTag] LiveFormExtAbility';
+
+export default class LiveFormExtAbility extends LiveFormExtensionAbility {
+ onLiveFormDestroy(liveFormInfo: LiveFormInfo) {
+ console.info(TAG, `onLiveFormDestroy, liveFormInfo: ${JSON.stringify(liveFormInfo)}`);
+ }
+}
+```
+### LiveFormInfo
+
+Defines the interactive widget information.
+
+**Model restriction**: This API can be used only in the stage model.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Atomic service API**: This API can be used in atomic services since API version 20.
+
+| Name| Type| Read-Only| Optional| Description|
+| ------ | ------ | ---- | ---- | -------- |
+| formId | string | No| No| Widget ID.|
+| rect | [formInfo.Rect](js-apis-app-form-formInfo.md#rect20) | No| No| Widget location and dimension.|
+| borderRadius | number | No| No| Widget corner radius. The value must be greater than 0, in vp.|
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formBindingData.md b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formBindingData.md
index e48c0e4f1ff4db0ec10391a3cd4365fd354eaffe..c90b85541379d5d5c9986d4446e0fa01285e2731 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formBindingData.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formBindingData.md
@@ -56,7 +56,7 @@ Creates a **FormBindingData** object.
| Name| Type | Mandatory| Description |
| ------ | -------------- | ---- | ------------------------------------------------------------ |
-| obj | Object\|string | No | Data to be displayed on the widget. The value can be an object containing multiple key-value pairs or a string in JSON format. The image data is identified by **'formImages'**, and the content is multiple key-value pairs, each of which consists of an image identifier and image file descriptor. The final format is {'formImages': {'key1': fd1, 'key2': fd2}}.|
+| obj | Object\|string | No | Data to be displayed on the widget. The value can be an object containing multiple key-value pairs or a string in JSON format. The image data is identified by **'formImages'**, and the content is multiple key-value pairs, each of which consists of an image identifier and image file descriptor. The final format is {'formImages': {'key1': fd1, 'key2': fd2}}.
**NOTE**
During [widget update](../../form/arkts-ui-widget-interaction-overview.md), when the widget UI receives widget data through @LocalStorageProp, the **FormBindingData** object is serialized, that is, the widget data is converted into the string type. Since API version 20, the maximum number of image files is 20, and the total memory size of all images cannot exceed 10 MB. If the total memory size exceeds 10 MB, the images will be displayed abnormally. In API version 19 and earlier versions, the maximum number of image files is 5, and the maximum memory size of each image is 2 MB.|
**Return value**
@@ -71,7 +71,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ
| ID| Error Message|
| -------- | -------- |
-| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed |
+| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
**Example**
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md
index fab6917cd6a3b4e79cc0a198a013fd28d3bedaaf..24e967cd7f953de2d0279830868deaac7321aa7f 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md
@@ -56,7 +56,7 @@ Called to notify the widget provider that a widget is being created.
| Name| Type | Mandatory| Description |
| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ |
-| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Want information of the widget. You can set the **parameters** field to one or more values enumerated in [widget parameters](./js-apis-app-form-formInfo.md#forminfoformparam), such as widget ID, widget name, and widget style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
+| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Want information of the widget. You can set the **parameters** field to one or more values enumerated in [widget parameters](./js-apis-app-form-formInfo.md#formparam), such as widget ID, widget name, and widget style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
**Return value**
@@ -326,7 +326,7 @@ Called to notify the widget provider that the widget host is requesting the widg
| Type | Description |
| ------------------------------------------------------------ | ----------------------------------------------------------- |
-| [formInfo.FormState](js-apis-app-form-formInfo.md#forminfoformstate) | Enumerated values of the current widget status.|
+| [formInfo.FormState](js-apis-app-form-formInfo.md#formstate) | Enumerated values of the current widget status.|
**Example**
@@ -365,3 +365,39 @@ export default class MyFormExtensionAbility extends FormExtensionAbility {
}
}
```
+
+### FormExtensionAbility.onFormLocationChanged20+
+
+onFormLocationChanged(formId: string, newFormLocation: formInfo.FormLocation): void
+
+Called when the widget location changes.
+
+**Model restriction**: This API can be used only in the stage model.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Parameters**
+
+| Name| Type| Mandatory| Description|
+| -------- | -------- | -------- | -------- |
+| formId | string | Yes| Widget ID.|
+| newFormLocation | [formInfo.FormLocation](js-apis-app-form-formInfo.md#formlocation20) | Yes| Enumerated value of the latest widget location.|
+
+**Example**
+
+```ts
+import { formBindingData, FormExtensionAbility, formInfo } from '@kit.FormKit';
+import { Want } from '@kit.AbilityKit';
+
+export default class EntryFormAbility extends FormExtensionAbility {
+ onAddForm(want: Want) {
+ let formData: Record = {
+ 'data': 'addForm'
+ };
+ return formBindingData.createFormBindingData(formData);
+ }
+ onFormLocationChanged(formId: string, newFormLocation: formInfo.FormLocation) {
+ console.info("EntryFormAbility onFormLocationChanged current location: " + newFormLocation);
+ }
+}
+```
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formHost-sys.md b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formHost-sys.md
index d6efd088caa8d2c26e49e8fb00bc535113257d2a..293355d4c5d22412354d42f982e448347999a32b 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formHost-sys.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formHost-sys.md
@@ -2181,7 +2181,7 @@ Sets a router proxy for widgets and obtains the Want information required for re
> **NOTE**
>
>- Generally, for a widget added to the home screen, in the case of router-based redirection, the widget framework checks whether the destination is proper and whether the widget has the redirection permission, and then triggers redirection accordingly. For a widget that is added to a widget host and has a router proxy configured, in the case of router-based redirection, the widget framework does not trigger redirection for the widget. Instead, it returns the **want** parameter containing the destination to the widget host. Therefore, if the widget host wants to use the Want information for redirection, it must have the application redirection permission. For details, see
-[UIAbilityContext.startAbility()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability).
+[UIAbilityContext.startAbility()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#startability).
>
>- Only one router proxy can be set for a widget. If multiple proxies are set, only the last proxy takes effect.
@@ -2221,7 +2221,7 @@ import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct CardExample {
- private context = getContext(this) as common.UIAbilityContext;
+ private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
@State formId: number = 0;
@State fwidth: number = 420;
@State fheight: number = 280;
@@ -2273,7 +2273,7 @@ Sets a router proxy for widgets and obtains the Want information required for re
> **NOTE**
>
->- Generally, for a widget added to the home screen, in the case of router-based redirection, the widget framework checks whether the destination is proper and whether the widget has the redirection permission, and then triggers redirection accordingly. For a widget that is added to a widget host and has a router proxy configured, in the case of router-based redirection, the widget framework does not trigger redirection for the widget. Instead, it returns the **want** parameter containing the destination to the widget host. Therefore, if the widget host wants to use the Want information for redirection, it must have the application redirection permission. For details, see [UIAbilityContext.startAbility()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability).
+>- Generally, for a widget added to the home screen, in the case of router-based redirection, the widget framework checks whether the destination is proper and whether the widget has the redirection permission, and then triggers redirection accordingly. For a widget that is added to a widget host and has a router proxy configured, in the case of router-based redirection, the widget framework does not trigger redirection for the widget. Instead, it returns the **want** parameter containing the destination to the widget host. Therefore, if the widget host wants to use the Want information for redirection, it must have the application redirection permission. For details, see [UIAbilityContext.startAbility()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#startability).
>
>- Only one router proxy can be set for a widget. If multiple proxies are set, only the last proxy takes effect.
@@ -2320,7 +2320,7 @@ import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct CardExample {
- private context = getContext(this) as common.UIAbilityContext;
+ private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
@State formId: number = 0;
@State fwidth: number = 420;
@State fheight: number = 280;
@@ -2748,7 +2748,7 @@ Updates the widget location.
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------- |
| formId | string | Yes | Widget ID.|
-| location |[formInfo.FormLocation](js-apis-app-form-formInfo-sys.md#formlocation) | Yes| Widget location.|
+| location |[formInfo.FormLocation](js-apis-app-form-formInfo-sys.md#formlocation12) | Yes| Widget location.|
**Error codes**
@@ -2796,7 +2796,7 @@ Sets the result for the operation of adding a widget to the home screen.
| Name| Type | Mandatory| Description |
| ------ | ------------------------------------------------------------ | ---- | ------------------ |
| formId | string | Yes | Widget ID. |
-| result | [PublishFormResult](js-apis-app-form-formInfo-sys.md#publishformresult) | Yes | Result of the operation.|
+| result | [formInfo.PublishFormResult](js-apis-app-form-formInfo-sys.md#publishformresult12) | Yes | Result of the operation.|
**Error codes**
@@ -2886,3 +2886,167 @@ try {
}
```
+
+## formHost.on('formOverflow')20+
+
+on(type: 'formOverflow', callback: Callback<formInfo.OverflowRequest>): void
+
+Subscribes to the interactive widget animation request event.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+**Parameters**
+
+| Name| Type | Mandatory| Description|
+|----------|--------|---|---------------------------------------|
+| type | string | Yes| Event type. Only **'formOverflow'** is supported, indicating the interactive widget animation request.|
+| callback | Callback<[formInfo.OverflowRequest](js-apis-app-form-formInfo-sys.md#overflowrequest20)> | Yes| Callback used by the widget host to process the animation request.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
+
+| Error Code ID| Error Message |
+|-------|-----------------------------------------------------------------------------------------------------------|
+| 202 | The application is not a system application. |
+| 801 | Capability not supported.function formOverflow can not work correctly due to limited device capabilities. |
+
+**Example**
+
+```ts
+import { formHost, formInfo } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+try {
+ formHost.on('formOverflow', (request: formInfo.OverflowRequest) => {
+ console.log(`formHost on formOverflow, formId is ${request.formId}`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
+}
+```
+
+## formHost.off('formOverflow')20+
+
+off(type: 'formOverflow', callback?: Callback<formInfo.OverflowRequest>): void
+
+Unsubscribes from the interactive widget animation request event.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ |----|----------------------------------------|
+| type | string | Yes | Event type. Only **'formOverflow'** is supported, indicating the interactive widget animation request.|
+| callback |Callback<[formInfo.OverflowRequest](js-apis-app-form-formInfo-sys.md#overflowrequest20)> | No | Callback function, which corresponds to the subscribed interactive widget animation request. By default, all registered interactive widget animation request events are deregistered.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
+
+| Error Code ID| Error Message |
+| --- |-----------------------------------------------------------------------------------------------------------|
+| 202 | The application is not a system application. |
+| 801 | Capability not supported.function formOverflow can not work correctly due to limited device capabilities. |
+
+**Example**
+
+```ts
+import { formHost, formInfo } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+try {
+ formHost.off('formOverflow', (request: formInfo.OverflowRequest) => {
+ console.log(`formHost off formOverflow, formId is ${request.formId}`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
+}
+```
+
+## formHost.on('changeSceneAnimationState')20+
+
+on(type: 'changeSceneAnimationState', callback: Callback<formInfo.ChangeSceneAnimationStateRequest>): void
+
+Subscribes to the event of switching the interactive widget state. An interactive widget can be in the active or inactive state. In the inactive state, the interactive widget is the same as a common widget. In the active state, the interactive widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement interactive widget animations.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- |------------------------------------------------------|
+| type | string | Yes | Event type. The event **'changeSceneAnimationState'** is triggered when the interactive widget state is switched.|
+| callback |Callback<[formInfo.ChangeSceneAnimationStateRequest](js-apis-app-form-formInfo-sys.md#changesceneanimationstaterequest20)> | Yes| Callback function, which is used by the widget host to process the state switching request.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
+
+| Error Code ID| Error Message |
+|-------|-----------------------------------------------------------------------------------------------------------|
+| 202 | The application is not a system application. |
+| 801 | Capability not supported.function formOverflow can not work correctly due to limited device capabilities. |
+
+**Example**
+
+```ts
+import { formHost, formInfo } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+try {
+ formHost.on('changeSceneAnimationState', (request: formInfo.ChangeSceneAnimationStateRequest): void => {
+ console.log(`formHost on changeSceneAnimationState, formId is ${request.formId}`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
+}
+```
+
+## formHost.off('changeSceneAnimationState')20+
+
+off(type: 'changeSceneAnimationState', callback: Callback<formInfo.changeSceneAnimationState>): void
+
+Unsubscribes from the event of switching the interactive widget state. An interactive widget can be in the active or inactive state. In the inactive state, the interactive widget is the same as a common widget. In the active state, the interactive widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement interactive widget animations.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ |----| ------- |
+| type | string | Yes | Event type. The event **'changeSceneAnimationState'** is triggered when the interactive widget state is switched.|
+| callback |Callback<[formInfo.ChangeSceneAnimationStateRequest](js-apis-app-form-formInfo-sys.md#changesceneanimationstaterequest20)> | No | Callback function, which corresponds to the request for switching the state of a subscribed interactive widget. By default, all registered interactive widget state switching events are deregistered.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
+
+| Error Code ID| Error Message|
+| -------- | -------- |
+| 202 | The application is not a system application. |
+| 801 | Capability not supported.function formOverflow can not work correctly due to limited device capabilities. |
+
+**Example**
+
+```ts
+import { formHost, formInfo } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+try {
+ formHost.off('changeSceneAnimationState', (request: formInfo.ChangeSceneAnimationStateRequest): void => {
+ console.log(`formHost off changeSceneAnimationState, formId is ${request.formId}`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`);
+}
+```
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo-sys.md b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo-sys.md
index 8a706e67b229da121600a0098baadd6c2a885416..66b5d59670b7d80951c40f0ea11cc24693b72162 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo-sys.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo-sys.md
@@ -13,6 +13,18 @@ The **formInfo** module provides types and enums related to the widget informati
import { formInfo } from '@kit.FormKit';
```
+## FormInfo
+
+Defines the widget information.
+
+**System capability**: SystemCapability.Ability.Form
+
+| Name | Type | Readable | Writable | Description |
+| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ |
+| previewImages18+ | Array<number> | Yes| No| Resource IDs of the preview images of the widget.
**Atomic service API**: This API can be used in atomic services since API version 18.|
+| enableBlurBackground18+ | boolean | Yes | No | Whether the widget uses a blur background.|
+| renderingMode18+|[RenderingMode](./js-apis-app-form-formInfo-sys.md#renderingmode18)|Yes|No|Widget rendering mode.|
+
## FormParam
@@ -71,11 +83,11 @@ Defines the information about the widget provider.
| Name | Type | Readable | Writable | Description |
| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ |
-| bundleName | string | Yes | No | Name of the bundle to which the widget provider belongs. |
-| formName | string | Yes | No | Widget name. |
-| moduleName | string | Yes | No | Name of the module to which the widget belongs. |
-| abilityName | string | Yes | No | Name of the ability to which the widget belongs. |
-| isUnusedIncluded11+ | boolean | Yes | No | Whether an unused widget is included. |
+| bundleName | string | Yes | Yes | Name of the bundle to which the widget provider belongs. |
+| formName | string | Yes | Yes | Widget name. |
+| moduleName | string | Yes | Yes | Name of the module to which the widget belongs. |
+| abilityName | string | Yes | Yes | Name of the ability to which the widget belongs. |
+| isUnusedIncluded11+ | boolean | Yes | Yes | Whether an unused widget is included.
- **true**: An unused widget is included.
- **false** (default): There is no unused widget.
|
## FormInfoFilter
@@ -133,3 +145,72 @@ Enumerates the result codes that may be used for the operation of adding a widge
| NO_SPACE | 1 | There is no space for adding widgets. |
| PARAM_ERROR | 2 | Parameter check fails. |
| INTERNAL_ERROR | 3 | An internal error occurs during widget processing.|
+
+## RenderingMode18+
+
+Enumerates the rendering modes supported by the widget.
+
+**Atomic service API**: This API can be used in atomic services since API version 18.
+
+**System capability**: SystemCapability.Ability.Form
+
+| Name | Value | Description |
+| ----------- | ---- | ------------ |
+| AUTO_COLOR | 0 | Auto mode. |
+| FULL_COLOR | 1 | Full-color mode. |
+| SINGLE_COLOR | 2 | Single-color mode. |
+
+## OverflowRequest20+
+
+Defines the request for interactive widget animations.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+| Name| Type| Read-Only| Optional| Description|
+|-----|-----|----|----|-----|
+| formId | string | Yes | No | Widget ID.|
+| isOverflow | boolean | Yes | No | Animation request type. The value **true** indicates the interactive widget requests to trigger the animation; the value **false** indicates the interactive widget requests to cancel the animation.|
+| overflowInfo | [formInfo.OverflowInfo](js-apis-app-form-formInfo.md#overflowinfo20) | Yes| Yes| Animation request parameters, including the animation duration (unit: ms) and animation area (the upper left corner of the widget is used as the origin of the animation area, in vp). The default value is empty.|
+
+## ChangeSceneAnimationStateRequest20+
+
+Defines the request for switching the status of an interactive widget. An interactive widget can be in the active or inactive state. In the inactive state, the interactive widget is the same as a common widget. In the active state, the interactive widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement interactive widget animations.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+| Name| Type| Read-Only| Optional| Description|
+|-----|-----|-----|-----|----------------------------------------|
+| formId | string | Yes| No| Widget ID. |
+| state | number | Yes| No| Status switching request type. The value **1** indicates that the switching request is activated, and the value **0** indicates that the switching request is deactivated.|
+
+## FunInteractionParams20+
+
+Defines the parameters for a fun-based widget.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+| Name| Type| Read-Only| Optional| Description |
+|-----|-----|----|-----|--------------------------------------------------------------------------------------------------------------------------------------|
+| abilityName | string | Yes | Yes | ExtensionAbility name of the interaction scenario. This parameter is left empty by default.|
+| targetBundleName | string | Yes | No | Bundle name. |
+| subBundleName | string | Yes | No | Sub bundle name.|
+| keepStateDuration | number | Yes | Yes | Duration of the activated state when there is no interaction. The default value is **10000**, in ms. The value should be an integer within the range [0, 10000]. If the value exceeds this range, it defaults to 10000 milliseconds.|
+
+## SceneAnimationParams20+
+
+Defines the parameters for a scene-based widget.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+| Name| Type| Read-Only| Optional| Description |
+|-----|-----|------|----|-------------------------------------------------------------------------------------------------------------------------------------------------|
+| abilityName | string | Yes| No | ExtensionAbility name, for example, LiveFormExtensionAbility name of the widget provider. |
+| disabledDesktopBehaviors | string | Yes| Yes | The options are **SWIPE_DESKTOP**, **PULL_DOWN_SEARCH**, **LONG_CLICK**, and **DRAG**. You can select one or more options. Use a vertical bar (\|) in between| to concatenate two different operations, for example, SWIPE_DESKTOP\|PULL_DOWN_SEARCH| By default, no operation is disabled.|
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo.md b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo.md
index ec7bc3abe671d0857eebfec3c154b00fad25fdfb..dfe4c2546bbcd8b664f63e6d1094185646d21f47 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formInfo.md
@@ -12,7 +12,7 @@ The **formInfo** module provides types and enums related to the widget informati
import { formInfo } from '@kit.FormKit';
```
-## formInfo.FormInfo
+## FormInfo
Defines the widget information.
@@ -23,14 +23,14 @@ Defines the widget information.
| bundleName | string | Yes | No | Name of the bundle to which the widget belongs.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| moduleName | string | Yes | No | Name of the module to which the widget belongs.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| abilityName | string | Yes | No | Name of the ability to which the widget belongs.
**Atomic service API**: This API can be used in atomic services since API version 11. |
-| name | string | Yes | No | Name of an application or atomic service.
**Atomic service API**: This API can be used in atomic services since API version 11.|
-| displayName11+ | string | Yes | No | Widget name.
**Atomic service API**: This API can be used in atomic services since API version 11.|
+| name | string | Yes | No | Widget name.
**Atomic service API**: This API can be used in atomic services since API version 11.|
+| displayName11+ | string | Yes | No | Widget display name.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| displayNameId11+ | number | Yes | No | ID of the widget name displayed during widget preview.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| description | string | Yes | No | Description of the widget.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| descriptionId10+ | number | Yes | No | ID of the widget description.
**Atomic service API**: This API can be used in atomic services since API version 11.|
-| type | [FormType](#forminfoformtype) | Yes | No | Type of the widget. Currently, JS and ArkTS widgets are supported.
**Atomic service API**: This API can be used in atomic services since API version 11.|
+| type | [FormType](#formtype) | Yes | No | Type of the widget. Currently, JS and ArkTS widgets are supported.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| jsComponentName | string | Yes | No | Name of the component used in the JS widget.
**Atomic service API**: This API can be used in atomic services since API version 11.|
-| colorMode | [ColorMode](#forminfocolormode) | Yes | No | Color mode of the widget.
**Atomic service API**: This API can be used in atomic services since API version 11.|
+| colorMode(deprecated) | [ColorMode](#colormodedeprecated) | Yes | No | Color mode of the widget.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| isDefault | boolean | Yes | No | Whether the widget is the default one.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| updateEnabled | boolean | Yes | No | Whether the widget is updatable.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| formVisibleNotify | boolean | Yes | No | Whether to send a notification when the widget is visible.
**Atomic service API**: This API can be used in atomic services since API version 11.|
@@ -38,16 +38,13 @@ Defines the widget information.
| formConfigAbility | string | Yes | No | Configuration ability of the widget, that is, the ability corresponding to the option in the selection box displayed when the widget is long pressed.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| updateDuration | number | Yes | No | Update period of the widget.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| defaultDimension | number | Yes | No | Widget specifications.
**Atomic service API**: This API can be used in atomic services since API version 11.|
-| supportDimensions | Array<number> | Yes | No | Dimensions supported by the widget. For details, see [FormDimension](#forminfoformdimension).
**Atomic service API**: This API can be used in atomic services since API version 11.|
+| supportDimensions | Array<number> | Yes | No | Dimensions supported by the widget. For details, see [FormDimension](#formdimension).
**Atomic service API**: This API can be used in atomic services since API version 11.|
| customizeData | Record\ | Yes | No | Custom data of the widget.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| isDynamic10+ | boolean | Yes | No | Whether the widget is a dynamic widget.
ArkTS widgets are classified into dynamic and static widgets. JS widgets are all dynamic widgets.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| transparencyEnabled11+ | boolean | Yes | No | Whether the widget supports the setting of the background transparency.
For ArkTS widgets, the support for the background transparency setting depends on user configurations. For JS widgets, the background transparency setting is not supported.
**Atomic service API**: This API can be used in atomic services since API version 11.|
-| supportedShapes12+ | Array<number> | Yes | No | Shapes supported by the widget. For details about the available shapes, see [FormShape12+](#forminfoformshape12).
**Atomic service API**: This API can be used in atomic services since API version 12. |
-| previewImages18+ | Array<number> | Yes| No| Resource IDs of the preview images of the widget.
**Atomic service API**: This API can be used in atomic services since API version 18.
-| enableBlurBackground18+ | boolean | Yes | No | Whether the widget uses a blur background.
**Atomic service API**: This API can be used in atomic services since API version 18.|
-|renderingMode18+|[RenderingMode](#forminforenderingmode18)|Yes|No|Widget rendering mode.
**Atomic service API**: This API can be used in atomic services since API version 18.|
+| supportedShapes12+ | Array<number> | Yes | No | Shapes supported by the widget. For details about the available shapes, see [FormShape12+](#formshape12).
**Atomic service API**: This API can be used in atomic services since API version 12. |
-## formInfo.FormType
+## FormType
Enumerates the widget types.
@@ -60,7 +57,9 @@ Enumerates the widget types.
| JS | 1 | JS widget. |
| eTS | 2 | ArkTS widget.|
-## formInfo.ColorMode
+## ColorMode(deprecated)
+
+This API is supported since API version 11 and deprecated since API version 20. The color mode follows the system color mode.
Enumerates the color modes supported by the widget.
@@ -74,7 +73,7 @@ Enumerates the color modes supported by the widget.
| MODE_DARK | 0 | Dark mode. |
| MODE_LIGHT | 1 | Light mode. |
-## formInfo.FormStateInfo
+## FormStateInfo
Describes the widget state information.
@@ -84,10 +83,10 @@ Describes the widget state information.
| Name | Type | Readable | Writable | Description |
| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ |
-| formState | [FormState](#forminfoformstate) | Yes | No | Widget state. |
+| formState | [FormState](#formstate) | Yes | No | Widget state. |
| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | No | Want text. |
-## formInfo.FormState
+## FormState
Enumerates the widget states.
@@ -101,7 +100,7 @@ Enumerates the widget states.
| DEFAULT | 0 | Default state. |
| READY | 1 | Ready state. |
-## formInfo.FormParam
+## FormParam
Enumerates the widget parameters.
@@ -110,7 +109,7 @@ Enumerates the widget parameters.
| Name | Value | Description |
| ----------- | ---- | ------------ |
| IDENTITY_KEY | 'ohos.extra.param.key.form_identity' | Widget ID.
**Atomic service API**: This API can be used in atomic services since API version 11.|
-| DIMENSION_KEY | 'ohos.extra.param.key.form_dimension' | Widget dimension.
**Atomic service API**: This API can be used in atomic services since API version 11.|
+| DIMENSION_KEY | 'ohos.extra.param.key.form_dimension' | Widget dimension. For details, see [FormDimension](#formdimension).
**Atomic service API**: This API can be used in atomic services since API version 11.|
| NAME_KEY | 'ohos.extra.param.key.form_name' | Widget name.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| MODULE_NAME_KEY | 'ohos.extra.param.key.module_name' | Name of the module to which the widget belongs.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| WIDTH_KEY | 'ohos.extra.param.key.form_width' | Widget width.
**Atomic service API**: This API can be used in atomic services since API version 11.|
@@ -122,11 +121,11 @@ Enumerates the widget parameters.
| PARAM_FORM_CUSTOMIZE_KEY10+ | 'ohos.extra.param.key.form_customize' | Custom data.
**Atomic service API**: This API can be used in atomic services since API version 11.|
| FORM_RENDERING_MODE_KEY11+ | 'ohos.extra.param.key.form_rendering_mode' | Widget rendering mode.
**Atomic service API**: This API can be used in atomic services since API version 12.|
| HOST_BG_INVERSE_COLOR_KEY12+ | 'ohos.extra.param.key.host_bg_inverse_color' | Inverse background color of the widget client.
**Atomic service API**: This API can be used in atomic services since API version 12.|
-| FORM_LOCATION_KEY12+ | 'ohos.extra.param.key.form_location' | Widget location.
OTHER -1 (other locations)
DESKTOP 0 (desktop)
FORM_CENTER 1 (widget center of the desktop)
FORM_MANAGER 2 (widget manager of the desktop)
NEGATIVE_SCREEN 3 (minus-one screen)
FORM_CENTER_NEGATIVE_SCREEN 4 (widget center of the minus-one screen)
FORM_MANAGER_NEGATIVE_SCREEN 5 (widget manager of the minus-one screen)
SCREEN_LOCK 6 (lock screen)
AI_SUGGESTION 7 (Celia suggestions area)
+| FORM_LOCATION_KEY12+ | 'ohos.extra.param.key.form_location' | Widget location.
OTHER -1 (Other locations)
DESKTOP 0 (Home screen)
FORM_CENTER 1 (Widget center of the home screen)
FORM_MANAGER 2 (Widget Manager of the home screen)
NEGATIVE_SCREEN 3 (Minus-one screen)
FORM_CENTER_NEGATIVE_SCREEN 4 (Widget center of the minus-one screen)
FORM_MANAGER_NEGATIVE_SCREEN 5 (Widget Manager of the minus-one screen)
SCREEN_LOCK 6 (Screen lock)
AI_SUGGESTION 7 (Celia suggestions area)|
| FORM_PERMISSION_NAME_KEY12+ | 'ohos.extra.param.key.permission_name' | Name of the permission.
**Atomic service API**: This API can be used in atomic services since API version 12.|
| FORM_PERMISSION_GRANTED_KEY12+ | 'ohos.extra.param.key.permission_granted' | Whether the permission is granted.
**Atomic service API**: This API can be used in atomic services since API version 12.|
-## formInfo.FormDimension
+## FormDimension
Enumerates the widget dimensions.
@@ -144,7 +143,7 @@ Enumerates the widget dimensions.
| DIMENSION_2_318+ | 8 | 2 x 3.
**Atomic service API**: This API can be used for wearable devices in atomic services since API version 18.|
| DIMENSION_3_318+ | 9 | 3 x 3.
**Atomic service API**: This API can be used for wearable devices in atomic services since API version 18.|
-## formInfo.FormShape12+
+## FormShape12+
Enumerates the widget shapes.
@@ -155,7 +154,7 @@ Enumerates the widget shapes.
| RECT | 1 | Rectangle.
**Atomic service API**: This API can be used in atomic services since API version 12.|
| CIRCLE | 2 | Circle.
**Atomic service API**: This API can be used in atomic services since API version 12.|
-## formInfo.FormInfoFilter
+## FormInfoFilter
Defines the widget information filter. Only the widget information that meets the filter is returned.
@@ -169,7 +168,7 @@ Defines the widget information filter. Only the widget information that meets th
-## formInfo.VisibilityType
+## VisibilityType
Enumerates the visibility types of the widget.
@@ -184,7 +183,7 @@ Enumerates the visibility types of the widget.
| FORM_INVISIBLE | 2 | The widget is invisible.|
-## formInfo.LaunchReason10+
+## LaunchReason10+
Enumerates the reasons for creating a widget.
@@ -197,16 +196,38 @@ Enumerates the reasons for creating a widget.
| FORM_DEFAULT | 1 | The widget is created by default.|
| FORM_SHARE | 2 | The widget is created for sharing.|
-## formInfo.RenderingMode18+
+## OverflowInfo20+
+
+Describes the widget animation information.
+
+**System capability**: SystemCapability.Ability.Form
+
+| Name| Type| Read-Only| Optional | Description |
+|-----|-----|------|-----|---------------------------------|
+| area | [Rect](#rect20) | Yes| No | Overflow animation area. The upper left corner of the widget is used as the origin, in vp. |
+| duration | number | Yes| No | Animation duration. The value is an integer greater than 0 and less than or equal to 3,500, in milliseconds.|
-Enumerates the rendering modes supported by the widget.
+## Rect20+
-**Atomic service API**: This API can be used in atomic services since API version 18.
+Defines the common rectangular area information, including the widget position and animation area.
**System capability**: SystemCapability.Ability.Form
-| Name | Value | Description |
-| ----------- | ---- | ------------ |
-| AUTO_COLOR | 0 | Auto mode. |
-| FULL_COLOR | 1 | Full-color mode. |
-| SINGLE_COLOR | 2 | Single-color mode. |
+| Name| Type| Read-Only| Optional | Description|
+|-----|-----|------|-----|-------|
+| left | number | Yes| No | X coordinate of the upper left vertex of the rectangle, in vp.|
+| top | number | Yes| No | Y coordinate of the upper left vertex of the rectangle, in vp.|
+| width | number | Yes| No | Width of the rectangle, in vp.|
+| height | number | Yes| No | Height of the rectangle, in vp.|
+## FormLocation20+
+
+Enumerates the widget locations.
+
+**System capability**: SystemCapability.Ability.Form
+
+| Name | Value | Description |
+| ---------------------------- | ---- | -------------------------------- |
+| DESKTOP | 0 | The widget is located on the home screen. |
+| FORM_CENTER | 1 | The widget is located in the widget center of the home screen. |
+| FORM_MANAGER | 2 | The widget is located in the Widget Manager of the home screen. |
+
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider-sys.md b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider-sys.md
index 66bdc2d7d39890286d3050069b989bff3f4b03a7..61c5e28fa91623b4a10af85fc58a89f5ca91a905 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider-sys.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider-sys.md
@@ -1,6 +1,6 @@
# @ohos.app.form.formProvider (formProvider) (System API)
-The **FormProvider** module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and request a widget release.
+The **formProvider** module provides APIs to obtain widget information, update widgets, set the update time, and request a widget release.
> **NOTE**
>
@@ -323,3 +323,117 @@ try {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}
```
+
+## activateSceneAnimation20+
+
+activateSceneAnimation(formId: string): Promise<void>
+
+Requests to activate a widget. This API takes effect only for [scene-based widgets](../../form/arkts-ui-widget-configuration.md#sceneanimationparams-field). This API uses a promise to return the result. An interactive widget can be in the active or inactive state. In the inactive state, the widget is the same as a common widget. In the active state, the widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement animations.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- |-------|
+| formId | string | Yes| Widget ID.|
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| Promise<void> | Promise that returns no value.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
+
+| Error Code ID| Error Message|
+| -------- | -------- |
+| 202 | The application is not a system application. |
+| 801 | Capability not supported.function activateSceneAnimation can not work correctly due to limited device capabilities. |
+| 16500050 | IPC connection error. |
+| 16500060 | Service connection error. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+| 16501001 | The ID of the form to be operated does not exist. |
+| 16501003 | The form cannot be operated by the current application. |
+| 16501011 | The form can not support this operation, please check your fom_config's sceneAnimationParams configuration infomation is correct or not. |
+
+**Example**
+
+```ts
+import { formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+let formId: string = '12400633174999288';
+
+try {
+ formProvider.activateSceneAnimation(formId).then(() => {
+ console.info('activateSceneAnimation succeed.');
+ }).catch((error: BusinessError) => {
+ console.error(`promise error, code: ${error.code}, message: ${error.message})`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
+}
+```
+
+## deactivateSceneAnimation20+
+
+deactivateSceneAnimation(formId: string): Promise<void>
+
+Requests to deactivate a widget. This API takes effect only for [scene-based widgets](../../form/arkts-ui-widget-configuration.md#sceneanimationparams-field). This API uses a promise to return the result. An interactive widget can be in the active or inactive state. In the inactive state, the widget is the same as a common widget. In the active state, the widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement animations.
+
+**System capability**: SystemCapability.Ability.Form
+
+**System API**: This is a system API.
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- |-------|
+| formId | string | Yes| Widget ID.|
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| Promise<void> | Promise that returns no value.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
+
+| Error Code ID| Error Message|
+| -------- | -------- |
+| 202 | The application is not a system application. |
+| 801 | Capability not supported.function deactivateSceneAnimation can not work correctly due to limited device capabilities. |
+| 16500050 | IPC connection error. |
+| 16500060 | Service connection error. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+| 16501001 | The ID of the form to be operated does not exist. |
+| 16501003 | The form cannot be operated by the current application. |
+| 16501011 | The form can not support this operation, please check your fom_config's sceneAnimationParams configuration infomation is correct or not. |
+
+**Example**
+
+```ts
+import { formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+let formId: string = '12400633174999288';
+
+try {
+ formProvider.deactivateSceneAnimation(formId).then(() => {
+ console.info('deactivateSceneAnimation succeed.');
+ }).catch((error: BusinessError) => {
+ console.error(`promise error, code: ${error.code}, message: ${error.message})`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
+}
+```
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider.md b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider.md
index a0c4fcf20c6b22644433b9873d5ef230de267964..0040829018f6c1ad8ff932704b9141f029161225 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-app-form-formProvider.md
@@ -1,6 +1,6 @@
# @ohos.app.form.formProvider (formProvider)
-The **FormProvider** module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and request a widget release.
+The **formProvider** module provides APIs to obtain widget information, update widgets, and set the update time.
> **NOTE**
>
@@ -387,3 +387,329 @@ try {
console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
}
```
+
+## formProvider.openFormEditAbility18+
+
+openFormEditAbility(abilityName: string, formId: string, isMainPage?: boolean): void
+
+Opens the widget editing page.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ |----|----------------------------------------------------|
+| abilityName | string | Yes | Ability name on the editing page. |
+| formId | string | Yes | Widget ID. |
+| isMainPage | boolean | No | Whether the page is the main editing page. The value **true** (default) means that the page is the main editing page; the value **false** means the opposite.
|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
+
+| Error Code ID | Error Message|
+|----------| -------- |
+| 801 | Capability not supported.function openFormEditAbility can not work correctly due to limited device capabilities. |
+| 16500050 | IPC connection error. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+| 16501003 | The form cannot be operated by the current application. |
+| 16501007 | Form is not trust. |
+
+**Example**
+
+```ts
+import { router } from '@kit.ArkUI';
+
+const TAG: string = 'FormEditDemo-Page] -->';
+
+@Entry
+@Component
+struct Page {
+ @State message: string = 'Hello World';
+
+ aboutToAppear(): void {
+ console.log(`${TAG} aboutToAppear.....`);
+ }
+
+ build() {
+ RelativeContainer() {
+ Text(this.message)
+ .id('PageHelloWorld')
+ .fontSize(50)
+ .fontWeight(FontWeight.Bold)
+ .alignRules({
+ center: { anchor: '__container__', align: VerticalAlign.Top },
+ middle: { anchor: '__container__', align: HorizontalAlign.Center }
+ })
+ .onClick(() => {
+ console.log(`${TAG} onClick.....`);
+ formProvider.openFormEditAbility('ability://EntryFormEditAbility', '1386529921');
+ })
+ }
+ .height('100%')
+ .width('100%')
+ }
+}
+```
+
+## formProvider.openFormManager18+
+
+openFormManager(want: Want): void
+
+Opens the Widget Manager page.
+
+**Atomic service API**: This API can be used in atomic services since API version 18.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Parameters**
+
+| Name | Type | Mandatory| Description |
+|------| ------ | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | Parameter that must contain the following fields:
**bundleName**: bundle name of widget.
**abilityName**: ability name of the widget.
**parameters**:
- **ohos.extra.param.key.form_dimension**: [Widget dimension](js-apis-app-form-formInfo.md#formdimension).
- **ohos.extra.param.key.form_name**: Widget name.
- **ohos.extra.param.key.module_name**: module name of the widget.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
+
+| Error Code ID| Error Message|
+| -------- | -------- |
+| 16500050 | IPC connection error. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+
+**Example**
+
+```ts
+import { formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+import { Want } from '@kit.AbilityKit';
+
+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})`);
+}
+```
+
+## formProvider.getPublishedFormInfoById18+
+
+getPublishedFormInfoById(formId: string): Promise<formInfo.FormInfo>
+
+Obtains the information of the widget that has been added to the home screen on the device. This API uses a promise to return the result.
+
+**Atomic service API**: This API can be used in atomic services since API version 18.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ |----| ------- |
+| formId | string | Yes| Widget ID.|
+
+**Return value**
+
+| Type | Description |
+|-------------------------------------------------------------------| ---------------------------------- |
+| Promise<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)> | Promise used to return the information obtained.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
+
+| Error Code ID| Error Message|
+| -------- | -------- |
+| 16500050 | IPC connection error. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+
+**Example**
+
+```ts
+import { formInfo, formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+const formId: string = '388344236';
+try {
+ formProvider.getPublishedFormInfoById(formId).then((data: formInfo.FormInfo) => {
+ console.log(`formProvider getPublishedFormInfoById, data: ${JSON.stringify(data)}`);
+ }).catch((error: BusinessError) => {
+ console.error(`promise error, code: ${error.code}, message: ${error.message})`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
+}
+```
+
+## formProvider.getPublishedFormInfos18+
+
+getPublishedFormInfos(): Promise<Array<formInfo.FormInfo>>
+
+Obtains the information of all widgets that have been added to the home screen on the device. This API uses a promise to return the result.
+
+**Atomic service API**: This API can be used in atomic services since API version 18.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Return value**
+
+| Type | Description |
+| ------------ | ---------------------------------- |
+| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.|
+
+**Error codes**
+
+For details about the error codes, see [Form Error Codes](errorcode-form.md).
+
+| Error Code ID| Error Message|
+| -------- | -------- |
+| 16500050 | IPC connection error. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+
+**Example**
+
+```ts
+import { formInfo, formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+try {
+ formProvider.getPublishedFormInfos().then((data: formInfo.FormInfo[]) => {
+ console.log(`formProvider getPublishedFormInfos, data: ${JSON.stringify(data)}`);
+ }).catch((error: BusinessError) => {
+ console.error(`promise error, code: ${error.code}, message: ${error.message})`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
+}
+```
+
+## formProvider.requestOverflow20+
+
+requestOverflow(formId: string, overflowInfo: formInfo.OverflowInfo): Promise<void>
+
+Requests an animation. This API takes effect only for [scene-based widgets](../../form/arkts-ui-widget-configuration.md#sceneanimationparams-field). This API uses a promise to return the result.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ |--------------------------------------------------------------------| ---- |-----------|
+| formId | string | Yes| Widget ID.|
+| overflowInfo | [formInfo.OverflowInfo](js-apis-app-form-formInfo.md#overflowinfo20) | Yes| Animation request parameter information.|
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| Promise<void> | Promise that returns no value.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
+
+| Error Code ID| Error Message|
+| -------- | -------- |
+| 801 | Capability not supported.function requestOverflow can not work correctly due to limited device capabilities. |
+| 16500050 | IPC connection error. |
+| 16500060 | Service connection error. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+| 16501001 | The ID of the form to be operated does not exist. |
+| 16501003 | The form cannot be operated by the current application. |
+| 16501011 | The form can not support this operation, please check your fom_config's sceneAnimationParams configuration infomation is correct or not. |
+
+**Example**
+
+```ts
+import { formInfo, formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+let formId: string = '12400633174999288';
+let overflowInfo: formInfo.OverflowInfo = {
+ area: {
+ left: -10,
+ top: -10,
+ width: 180,
+ height: 180
+ },
+ duration: 1000,
+};
+
+try {
+ formProvider.requestOverflow(formId, overflowInfo).then(() => {
+ console.info('requestOverflow succeed.');
+ }).catch((error: BusinessError) => {
+ console.error(`promise error, code: ${error.code}, message: ${error.message})`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
+}
+```
+
+## formProvider.cancelOverflow20+
+
+cancelOverflow(formId: string): Promise<void>
+
+Cancels an animation. This API takes effect only for [scene-based widgets](../../form/arkts-ui-widget-configuration.md#sceneanimationparams-field). This API uses a promise to return the result.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- |-------|
+| formId | string | Yes| Widget ID.|
+
+**Return value**
+
+| Type| Description|
+| -------- | -------- |
+| Promise<void> | Promise that returns no value.|
+
+**Error codes**
+
+For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md).
+
+| Error Code ID| Error Message|
+| -------- | -------- |
+| 801 | Capability not supported.function cancelOverflow can not work correctly due to limited device capabilities. |
+| 16500050 | IPC connection error. |
+| 16500060 | Service connection error. |
+| 16500100 | Failed to obtain the configuration information. |
+| 16501000 | An internal functional error occurred. |
+| 16501001 | The ID of the form to be operated does not exist. |
+| 16501003 | The form cannot be operated by the current application. |
+| 16501011 | The form can not support this operation, please check your fom_config's sceneAnimationParams configuration infomation is correct or not. |
+
+**Example**
+
+```ts
+import { formProvider } from '@kit.FormKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+
+let formId: string = '12400633174999288';
+
+try {
+ formProvider.cancelOverflow(formId).then(() => {
+ console.info('cancelOverflow succeed.');
+ }).catch((error: BusinessError) => {
+ console.error(`promise error, code: ${error.code}, message: ${error.message})`);
+ });
+} catch (error) {
+ console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
+}
+```
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-application-LiveFormExtensionContext.md b/en/application-dev/reference/apis-form-kit/js-apis-application-LiveFormExtensionContext.md
new file mode 100644
index 0000000000000000000000000000000000000000..2bdf3fa45eaca97c4c8fcbcd9133c46f0fb6cdfb
--- /dev/null
+++ b/en/application-dev/reference/apis-form-kit/js-apis-application-LiveFormExtensionContext.md
@@ -0,0 +1,81 @@
+# LiveFormExtensionContext
+
+**LiveFormExtensionContext**, inherited from [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md), is the context of [LiveFormExtensionAbility](./js-apis-app-form-LiveFormExtensionAbility.md).
+
+> **NOTE**
+>
+> The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version.
+>
+> The APIs of this module can be used only in the stage model.
+
+## Modules to Import
+```ts
+import { LiveFormExtensionAbility } from '@kit.FormKit';
+```
+
+## LiveFormExtensionContext
+
+Provides APIs to access specific **LiveFormExtensionAbility** resources.
+
+### setBackgroundImage
+
+setBackgroundImage(res: Resource): Promise<void>
+
+Sets the background image of an interactive widget. This API uses a promise to return the result.
+
+**Model restriction**: This API can be used only in the stage model.
+
+**System capability**: SystemCapability.Ability.Form
+
+**Atomic service API**: This API can be used in atomic services since API version 20.
+
+**Parameters**
+
+| Name| Type | Mandatory| Description |
+| ------ | ------ | ---- | ------------------------------------- |
+| res | [Resource](../apis-localization-kit/js-apis-resource.md) | Yes| Background image resources, including the resource ID and resource type.|
+
+**Return value**
+
+| Type | Description |
+| ------------ | ---------------------------------- |
+| Promise<void> | Promise that returns no value.|
+
+**Error codes**
+
+For details about the error codes, see [Form Error Codes](errorcode-form.md) and [Universal Error Codes](../errorcode-universal.md).
+
+| ID| Error Message |
+| -------- | ------------------------------------------------------------ |
+| 801 | Capability not supported. Failed to call the API due to limited device capabilities. |
+| 16501010 | Failed to set the live form background image. |
+
+**Example**
+
+```ts
+import { UIExtensionContentSession } from '@kit.AbilityKit';
+import { BusinessError } from '@kit.BasicServicesKit';
+import { LiveFormExtensionAbility, LiveFormInfo } from '@kit.FormKit';
+
+const TAG: string = '[testTag]LiveFormExtAbility';
+
+export default class LiveFormExtAbility extends LiveFormExtensionAbility {
+ onLiveFormCreate(liveFormInfo: LiveFormInfo, session: UIExtensionContentSession): void {
+ try {
+ // Add the background image to the scr/main/resources/base/media directory. Otherwise, an error will be reported due to missing resources.
+ this.context.setBackgroundImage($r('app.media.backgroundImage'))
+ .then(() => {
+ // Carry out normal service processing.
+ console.info(TAG, 'setBackgroundImage succeed');
+ })
+ .catch((err: BusinessError) => {
+ // Process service logic errors.
+ console.error(TAG, `setBackgroundImage failed, code is ${err?.code}, message is ${err?.message}`);
+ });
+ } catch (err) {
+ // Handle input parameter errors.
+ console.error(TAG, `setBackgroundImage failed, code is ${err?.code}, message is ${err?.message}`);
+ }
+ }
+};
+```
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md b/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md
index 26e0d7d4172e86bf114655cfcc14a41391d7767d..42b9f73cb054e3ccf04e5353bb4b1c1e088418b3 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formEditExtensionContext.md
@@ -14,7 +14,7 @@ You can use **FormEditExtensionContext** to access specific **FormEditExtensionA
```ts
import { FormEditExtensionAbility } from '@kit.FormKit';
```
-## FormEditExtensionAbility.startSecondPage
+## FormEditExtensionContext.startSecondPage
startSecondPage(want: Want): Promise<[AbilityResult](../apis-ability-kit/js-apis-inner-ability-abilityResult.md)>
@@ -22,8 +22,6 @@ Starts the widget provider page to be edited.
**Model restriction**: This API can be used only in the stage model.
-**Atomic service API**: This API can be used in atomic services since API version 18.
-
**System capability**: SystemCapability.Ability.Form
**Parameters**
@@ -44,7 +42,6 @@ For details about the error codes, see [Form Error Codes](errorcode-form.md) and
| ID| Error Message |
| -------- | ------------------------------------------------------------ |
| 202 | The application is not a system application. |
-| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
| 16500050 | An IPC connection error happened. |
| 16501000 | An internal functional error occurred. |
| 16500100 | Failed to obtain the configuration information. |
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formExtensionContext-sys.md b/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formExtensionContext-sys.md
index bc58f407466610c1db71b65e1c175e3b39b9f166..81a30f25ea7e8d5b433dfd292968423f20fb06d4 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formExtensionContext-sys.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formExtensionContext-sys.md
@@ -1,6 +1,6 @@
# FormExtensionContext (System API)
-The FormExtensionContext module, inherited from [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md), provides the context environment for the [FormExtensionAbility](js-apis-app-form-formExtensionAbility.md).
+The **FormExtensionContext** module, inherited from [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md), provides the context environment for the [FormExtensionAbility](js-apis-app-form-formExtensionAbility.md).
You can use the APIs of this module to start a FormExtensionAbility.
@@ -172,7 +172,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
| 16000001 | The specified ability does not exist. |
| 16000002 | Incorrect ability type. |
-| 16000004 | Can not start invisible component. |
+| 16000004 | Cannot start an invisible component. |
| 16000005 | The specified process does not have the permission. |
| 16000006 | Cross-user operations are not allowed. |
| 16000008 | The crowdtesting application expires. |
diff --git a/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formExtensionContext.md b/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formExtensionContext.md
index 30e95385c3e776760cc77bf27fd4d80114f3549f..0273c6351bce9899861056d5aae9b64659356a72 100644
--- a/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formExtensionContext.md
+++ b/en/application-dev/reference/apis-form-kit/js-apis-inner-application-formExtensionContext.md
@@ -9,10 +9,18 @@ You can use the APIs of this module to start a FormExtensionAbility.
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The APIs of this module can be used only in the stage model.
+## Modules to Import
+
+```ts
+import { FormExtensionAbility } from '@kit.FormKit';
+```
+
## FormExtensionContext
-The FormExtensionContext module provides the context environment for the [FormExtensionAbility](js-apis-app-form-formExtensionAbility.md).
+**FormExtensionContext** is the context of [FormExtensionAbility](js-apis-app-form-formExtensionAbility.md).
**System capability**: SystemCapability.Ability.Form
-**Atomic service API**: This API can be used in atomic services since API version 11.
\ No newline at end of file
+**Model restriction**: This API can be used only in the stage model.
+
+**Atomic service API**: This API can be used in atomic services since API version 11.