diff --git a/README.en.md b/README.en.md index 60ee076bc20a16a48d6d87a47e2995ec86731fb9..92523cd9b7cdd3321087f538bd400e965fbb1e0a 100644 --- a/README.en.md +++ b/README.en.md @@ -1,71 +1,76 @@ -# Widget Update +# Widget Update and Data Interaction ### Overview -The first card in this example uses three events: router, call, and message, as well as a fixed-point refresh method to refresh card information. The second card implements the functions of timed refresh of cards and application triggered refresh of cards. +Service widgets provide users with clear information, which is easy to use, intelligent, and diversified. This sample uses Form Kit to describe how to create, interact with, update, and manage widgets, helping you efficiently develop personalized service widgets. ### Preview -| First Card | Second Card | +| Widget 1 | Widget 2 | |-------------------------------------|--------------------------------------------| | ![](screenshots/device/form.en.png) | ![](screenshots/device/form_second.en.png) | + +### How to Use + +**Widget 1** +1. Install the sample app, and touch and hold the app icon to add a widget. +2. Touch the router event button to go to the app page. When you return to the home screen, you can see that the widget information is updated. +3. Touch the call event. The widget information is updated. +4. Touch the message event. The widget information is updated. +5. Set the **scheduledUpdateTime** field in the **src/main/resources/base/profile/form_config.json** file to a time point. The widget information is updated at the specified time point. + +**Widget 2** +1. Install the sample app, and touch the heart-shaped icon in the upper right corner after the image and text list is displayed on the app home screen. +2. Touch and hold the app image to create widget 2, and touch the widget to start the app. +3. Select the same data entry in the app for widget display, and touch the heart-shaped icon to return to the home screen. The heart-shaped status is updated to the widget. +4. Configure the **updateDuration** field in the **src/main/resources/base/profile/form_config.json** file. The interval for updating the widget is 30 minutes. If **1** is set in the sample, the widget is updated every 30 minutes. + ### Project Directory ``` -├──entry/src/main/ets // Core code +├──entry/src/main/ets // Code area │ ├──common +│ │ ├──utils +│ │ │ ├──Logger.ets // Logger +│ │ │ └──PreferencesUtil.ets // Preference utility │ │ ├──CommonConstants.ets // Widget data -│ │ └──CommonData.ets // Utility class for widget data +│ │ └──CommonData.ets // Widget data utilities │ ├──entryability -│ │ └──EntryAbility.ets // Entry ability +│ │ └──EntryAbility.ets // Entry ability │ ├──entrybackupability │ │ └──EntryBackupAbility.ets │ ├──entryformability -│ │ └──EntryFormAbility.ets // Widget lifecycle class +│ │ └──EntryFormAbility.ets // Widget lifecycle │ ├──pages -│ │ ├──Index.ets // Home page +│ │ └──Index.ets // Home page │ └──widget │ ├──pages -│ │ └──WidgetCard.ets // Widget page +│ │ ├──WidgetCard.ets // Page of widget 1 +│ │ └──WidgetCardUpdate.ets // Page of widget 2 │ ├──view │ │ └──CardListComponent.ets │ └──viewmodel │ └──CardListParameter.ets -└──entry/src/main/resources // Static resources +└──entry/src/main/resources // Static resources of the app ``` -### How to Use - -**First Card** -1. Install the sample app, and touch and hold the app icon to add a widget. -2. Touch the router event button to go to the app page. When you return to the home screen, you can see that the widget information is updated. -3. Touch the call event. The widget information is updated. -4. Touch the message event. The widget information is updated. -5. Set the **scheduledUpdateTime** field in the **src/main/resources/base/profile/form_config.json** file to a time point. The widget information is updated at the specified time point. - -**Second Card** -1. After installing the application, the homepage of the application displays a list of images and text, and the heart-shaped icon in the upper right corner supports clicking. -2. Long press the application image to select create a second card, click on the card to pull up the application. -3. Select the same data displayed on the card within the application, click the heart-shaped button, return to the desktop, and update the heart-shaped status to the card. -4. Configure the **updateDuration** field in the **src/main/resources/base/profile/form_config.json** file. The update cycle unit for card scheduled refresh is 30 minutes. The example configuration is set to 1, which means that after any update of the card, it will be refreshed at a scheduled time after 30 minutes. - ### How to Implement 1. The router event calls the **updateForm** method of **formProvider** in the lifecycle callback of the EntryAbility to update the widget information. 2. The call event updates the widget information in the **onAddForm** method of the EntryFormAbility and triggers the **onFormTimeChange** method of the widget UI. The **updateCardInfo** information carried in the **postCardAction** method is used to trigger the callee listening in the EntryAbility, thereby updating the widget information in the listening method. 3. The message event updates the widget information in the **onFormEvent** callback of the EntryFormAbility. -4. After creating the second card, use the call event to pass the card ID to the Entry Ability and save it to the preferences. The application side retrieves the card ID from the preferences and updates the specified card using the updateForm method. +4. After widget 2 is created, the call event transfers the widget ID to EntryAbility and save the widget ID to the preferences. The app obtains the widget ID from the preferences and uses the **updateForm** method to update the specified widget. -#### NOTE -1. The widget information in this project uses the data configured in the code. In actual scenarios, you can encapsulate a method to obtain the information. +#### Notes: +1. The widget information in this project uses the data configured in the code. In practice, you can encapsulate a method to obtain the information. -### Required Permissions +### Permissions -**ohos.permission.KEEP_BACKGROUND_RUNNING**: allows a ServiceAbility to keep running in the background. The provider app must have the permission to run the call event in the background. +**ohos.permission.KEEP_BACKGROUND_RUNNING**: allows a service ability to keep running in the background. The provider app must have the permission to run the call event in the background. ### Constraints -1. The sample app is supported only on Huawei phones running the standard system. +1. The sample is only supported on Huawei phones with standard systems. 2. The HarmonyOS version must be HarmonyOS 5.0.0 Release or later. 3. The DevEco Studio version must be DevEco Studio 5.0.0 Release or later. -4. The HarmonyOS SDK version must be HarmonyOS 5.0.0 Release or later. +4. The HarmonyOS SDK version must be HarmonyOS 5.0.0 Release SDK or later. \ No newline at end of file diff --git a/README.md b/README.md index 02a8440cb02f694b073efe704218e000fccc4a24..db152b2cf5393bca62a865f8a3e4e89d2bd032f9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# 基于FormKit实现系统卡片 +# 实现卡片更新与数据交互功能 ### 介绍 diff --git a/screenshots/device/form.en.png b/screenshots/device/form.en.png index cd997728506888bba72b4eebb0f26f58b20bdd06..9f7588bd1855d63801438ccc0ad1fe72d7ee266e 100644 Binary files a/screenshots/device/form.en.png and b/screenshots/device/form.en.png differ diff --git a/screenshots/device/form_second.en.png b/screenshots/device/form_second.en.png index 0b9ed6eef873332cde951dbd7464640c38ecc7d1..942116d7e747de3f6b6d4358602e9e90415b575f 100644 Binary files a/screenshots/device/form_second.en.png and b/screenshots/device/form_second.en.png differ