diff --git a/zh-cn/application-dev/form/Readme-CN.md b/zh-cn/application-dev/form/Readme-CN.md index 8c9e99e73af3a98189fa4ce46af6996d227e3077..2ae5db40520102fd193d855de132d4bd54efdcff 100644 --- a/zh-cn/application-dev/form/Readme-CN.md +++ b/zh-cn/application-dev/form/Readme-CN.md @@ -18,14 +18,12 @@ - [拉起卡片提供方的UIAbility到后台(call事件)](arkts-ui-widget-event-call.md) - [通过message事件刷新卡片内容](arkts-ui-widget-event-formextensionability.md) - [通过router或call事件刷新卡片内容](arkts-ui-widget-event-uiability.md) - - 卡片数据交互 - - [卡片内容更新](arkts-ui-widget-interaction-overview.md) - - [卡片定时刷新](arkts-ui-widget-update-by-time.md) - - [卡片定点刷新](arkts-ui-widget-update-by-time-point.md) + - ArkTS卡片页面刷新 + - [ArkTS卡片页面刷新概述](arkts-ui-widget-overview-refresh.md) + - [ArkTS卡片主动刷新](arkts-ui-widget-active-refresh.md) + - [ArkTS卡片被动刷新](arkts-ui-widget-passive-refresh.md) - - [卡片代理刷新](arkts-ui-widget-update-by-proxy.md) - - [卡片条件刷新](arkts-ui-widget-update-by-conditions.md) - - [卡片使用方主动请求刷新卡片内容（仅对系统应用开放）](arkts-ui-widget-content-update.md) + - [ArkTS卡片代理刷新](arkts-ui-widget-update-by-proxy.md) - [刷新本地图片和网络图片](arkts-ui-widget-image-update.md) - [根据卡片状态刷新不同内容](arkts-ui-widget-update-by-status.md) diff --git a/zh-cn/application-dev/form/arkts-ui-widget-content-update.md b/zh-cn/application-dev/form/arkts-ui-widget-active-refresh.md similarity index 87% rename from zh-cn/application-dev/form/arkts-ui-widget-content-update.md rename to zh-cn/application-dev/form/arkts-ui-widget-active-refresh.md index 0f9f9dc1f734545f3e92dc2bbb920d59378d43bb..a811a668d1b4a7f0af42bac731a857c9204235ab 100644 --- a/zh-cn/application-dev/form/arkts-ui-widget-content-update.md +++ b/zh-cn/application-dev/form/arkts-ui-widget-active-refresh.md @@ -1,3 +1,12 @@ +# ArkTS卡片主动刷新 +## 点击卡片时刷新 +通过message事件刷新卡片内容\ +通过router或call事件刷新卡片内容 +## 启动应用时刷新 +通过message事件刷新卡片内容\ +通过router或call事件刷新卡片内容 + + # 卡片使用方主动请求刷新卡片内容（仅对系统应用开放） @@ -41,3 +50,4 @@ struct Index { } } ``` + diff --git a/zh-cn/application-dev/form/arkts-ui-widget-image-update.md b/zh-cn/application-dev/form/arkts-ui-widget-image-update.md index 1268a0b1771f94d077438871a42af03416a7e919..6f191804ad930fc6997a5ba4f23a23c50cb7684a 100644 --- a/zh-cn/application-dev/form/arkts-ui-widget-image-update.md +++ b/zh-cn/application-dev/form/arkts-ui-widget-image-update.md @@ -1,5 +1,7 @@ # 刷新本地图片和网络图片 - +>- 本地图片的刷新 +>- 本地到网络图片的刷新 +>- 网络图片的刷新 在卡片上通常需要展示本地图片或从网络上下载的图片，获取本地图片和网络图片需要通过FormExtensionAbility来实现，如下示例代码介绍了如何在卡片上显示本地图片和网络图片。 diff --git a/zh-cn/application-dev/form/arkts-ui-widget-interaction-overview.md b/zh-cn/application-dev/form/arkts-ui-widget-overview-refresh.md similarity index 81% rename from zh-cn/application-dev/form/arkts-ui-widget-interaction-overview.md rename to zh-cn/application-dev/form/arkts-ui-widget-overview-refresh.md index fa794ebec2a0c05bc2ae47b1dd35b0b90476fab8..3d5e35724da77c5b7e464ffa3b263648667cecc7 100644 --- a/zh-cn/application-dev/form/arkts-ui-widget-interaction-overview.md +++ b/zh-cn/application-dev/form/arkts-ui-widget-overview-refresh.md @@ -1,4 +1,15 @@ -# 卡片内容更新 +# ArkTS卡片页面刷新概述 + +## 使用场景 +## 运行机制 +## 刷新内容的范围 +## 页面刷新方式 + +> 按照触发的方式不同 +> - 1)主动刷新，分为点击卡片/启动应用时刷新，分别通过message/router/call事件触发； +> - 2)被动刷新，又可以分为定时刷新、定点刷新、条件刷新； +> +> 简介及差异 ArkTS卡片框架为卡片提供方提供了[updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#updateform)接口、为卡片使用方提供了requestForm接口来实现主动触发卡片的页面刷新能力；另外卡片框架还会通过开发者声明的定时信息按需通知卡片提供方进行卡片刷新。 @@ -37,8 +48,8 @@ ArkTS卡片框架为卡片提供方提供了[updateForm](../reference/apis-form- 下面介绍卡片页面刷新的典型场景。 -- [卡片定时刷新](arkts-ui-widget-update-by-time.md) -- [卡片定点刷新](arkts-ui-widget-update-by-time-point.md) +- [ArkTS卡片主动刷新](arkts-ui-widget-active-refresh.md) +- [ArkTS卡片被动刷新](arkts-ui-widget-passive-refresh.md) - [刷新本地图片和网络图片](arkts-ui-widget-image-update.md) - [根据卡片状态刷新不同内容](arkts-ui-widget-update-by-status.md) diff --git a/zh-cn/application-dev/form/arkts-ui-widget-update-by-time.md b/zh-cn/application-dev/form/arkts-ui-widget-passive-refresh.md similarity index 54% rename from zh-cn/application-dev/form/arkts-ui-widget-update-by-time.md rename to zh-cn/application-dev/form/arkts-ui-widget-passive-refresh.md index 3ced721913fe70bb079726c4f6a22c7d8b6b5f95..f6314e2c3f895613c23213cbbe3b44eff6b75e24 100644 --- a/zh-cn/application-dev/form/arkts-ui-widget-update-by-time.md +++ b/zh-cn/application-dev/form/arkts-ui-widget-passive-refresh.md @@ -1,4 +1,8 @@ -# 卡片定时刷新 +# ArkTS卡片被动刷新 +## 适用场景 +> 如何选择定时刷新与定点刷新 +## 卡片定时刷新 +> 新增配置文件的配置 当前卡片框架提供了如下几种按时间刷新卡片的方式： @@ -85,3 +89,122 @@ 3. 定时刷新在卡片可见情况下才会触发，在卡片不可见时仅会记录刷新动作和刷新数据，待可见时统一刷新布局。 > 4. 如果使能了卡片代理刷新，定时刷新和下次刷新不生效。 + +## 卡片定点刷新 +> 新增配置文件的配置 + +当前卡片框架提供了如下两种定点刷新卡片的方式： + +- 单定点刷新：表示在每天的某个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的`scheduledUpdateTime`字段中进行设置。例如，可以将刷新时间设置为每天的上午10点30分。 + + + ```json + { + "forms": [ + { + "name": "ScheduledUpdateTime", + "description": "$string:widget_scheupdatetime_desc", + "src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets", + "uiSyntax": "arkts", + "window": { + "designWidth": 720, + "autoDesignWidth": true + }, + "colorMode": "auto", + "isDefault": true, + "updateEnabled": true, + "scheduledUpdateTime": "10:30", + "updateDuration": 0, + "defaultDimension": "2*2", + "supportDimensions": [ + "2*2" + ] + } + ] + } + ``` + +- 多定点刷新：表示在每天的多个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的`multiScheduledUpdateTime`字段中进行设置，例如，可以将刷新时间设置为每天的上午11点30分和下午4点30分。 + ```json + { + "forms": [ + { + "name": "ScheduledUpdateTime", + "description": "$string:widget_scheupdatetime_desc", + "src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets", + "uiSyntax": "arkts", + "window": { + "designWidth": 720, + "autoDesignWidth": true + }, + "colorMode": "auto", + "isDefault": true, + "updateEnabled": true, + "scheduledUpdateTime": "10:30", + "multiScheduledUpdateTime": "11:30,16:30,", + "updateDuration": 0, + "defaultDimension": "2*2", + "supportDimensions": [ + "2*2" + ] + } + ] + } + ``` + +在触发定点刷新后，系统会调用FormExtensionAbility的[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onupdateform)生命周期回调，在回调中，可以使用[updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#updateform)进行提供方刷新卡片。`onUpdateForm`生命周期回调的使用请参见[卡片生命周期管理](./arkts-ui-widget-lifecycle.md)。 + +> **说明：** +> 1. 当同时配置了定时刷新`updateDuration`和定点刷新`scheduledUpdateTime`时，定时刷新的优先级更高且定点刷新不会执行。如果想要配置定点刷新，则需要将`updateDuration`配置为0。 +> 2. `multiScheduledUpdateTime`的配置最多可设置24个时间。 +> 3. 同时配置了单定点和多定点刷新，多定点刷新配置生效，单定点刷新配置不生效。 +> 4. 考虑到向前兼容的问题，尽量保留`scheduledUpdateTime`字段，不要直接删除。 + +**约束限制：** +1. 定点刷新在卡片可见情况下才会触发，在卡片不可见时仅会记录刷新动作和刷新数据，待可见时统一刷新布局。 + + +## 卡片条件刷新 +> 新增配置文件的配置，包含网络状态变化时 + +当前卡片框架提供了如下按条件刷新卡片的方式： + +- 网络刷新：表示在网络变化的场景下调用[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onupdateform)的生命周期回调函数自动刷新卡片内容。可以在[form_config.json](arkts-ui-widget-configuration.md)配置文件的`conditionUpdate`字段中进行设置，设置字段为network。 + +> **说明：** +> 1. 当从无网络到有网络连接时会触发刷新。而网络间切换（例如：WiFi间切换，WiFi到流量，流量到WiFi），或从有网络连接到无网络连接时不会触发刷新。 +> +> 2. 为减少卡片在频繁开关网络场景进程启动次数，无网判定需要网络连续断开十分钟后，才会认为无网，下次联网后触发网络刷新。 +> +> 3. 仅对系统应用的卡片生效。 + + + ```json + { + "forms": [ + { + "name": "UpdateDuration", + "description": "$string:widget_updateduration_desc", + "src": "./ets/updateduration/pages/UpdateDurationCard.ets", + "uiSyntax": "arkts", + "window": { + "designWidth": 720, + "autoDesignWidth": true + }, + "colorMode": "auto", + "isDefault": true, + "updateEnabled": true, + "scheduledUpdateTime": "10:30", + "updateDuration": 2, + "defaultDimension": "2*2", + "supportDimensions": [ + "2*2" + ], + "conditionUpdate": [ + "network" + ] + } + ] + } + ``` + \ No newline at end of file diff --git a/zh-cn/application-dev/form/arkts-ui-widget-update-by-conditions.md b/zh-cn/application-dev/form/arkts-ui-widget-update-by-conditions.md deleted file mode 100644 index d2c6036213c0cb0612a26768e1c819d361d4397b..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/form/arkts-ui-widget-update-by-conditions.md +++ /dev/null @@ -1,42 +0,0 @@ -# 卡片条件刷新 - -当前卡片框架提供了如下按条件刷新卡片的方式： - -- 网络刷新：表示在网络变化的场景下调用[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onupdateform)的生命周期回调函数自动刷新卡片内容。可以在[form_config.json](arkts-ui-widget-configuration.md)配置文件的`conditionUpdate`字段中进行设置，设置字段为network。 - -> **说明：** -> 1. 当从无网络到有网络连接时会触发刷新。而网络间切换（例如：WiFi间切换，WiFi到流量，流量到WiFi），或从有网络连接到无网络连接时不会触发刷新。 -> -> 2. 为减少卡片在频繁开关网络场景进程启动次数，无网判定需要网络连续断开十分钟后，才会认为无网，下次联网后触发网络刷新。 -> -> 3. 仅对系统应用的卡片生效。 - - - ```json - { - "forms": [ - { - "name": "UpdateDuration", - "description": "$string:widget_updateduration_desc", - "src": "./ets/updateduration/pages/UpdateDurationCard.ets", - "uiSyntax": "arkts", - "window": { - "designWidth": 720, - "autoDesignWidth": true - }, - "colorMode": "auto", - "isDefault": true, - "updateEnabled": true, - "scheduledUpdateTime": "10:30", - "updateDuration": 2, - "defaultDimension": "2*2", - "supportDimensions": [ - "2*2" - ], - "conditionUpdate": [ - "network" - ] - } - ] - } - ``` \ No newline at end of file diff --git a/zh-cn/application-dev/form/arkts-ui-widget-update-by-proxy.md b/zh-cn/application-dev/form/arkts-ui-widget-update-by-proxy.md index fa26a39322f7d1ce13d0d98b930ab053451863bb..6f15cb80d64ad2dafdfda9e874a8a7b7e6d93127 100644 --- a/zh-cn/application-dev/form/arkts-ui-widget-update-by-proxy.md +++ b/zh-cn/application-dev/form/arkts-ui-widget-update-by-proxy.md @@ -1,8 +1,9 @@ -# 卡片代理刷新 +# ArkTS卡片代理刷新 +## 数据代理刷新 卡片代理刷新是一种通过系统应用刷新卡片的机制。卡片提供方不在运行时，仍然可以通过开启了数据共享能力的系统应用完成卡片数据的更新。 -## 实现原理 +### 实现原理 **图1** 代理刷新运行原理 ![UpdateWidgetByProxyPrinciple](figures/UpdateWidgetByProxyPrinciple.png) @@ -42,11 +43,11 @@ 相应的卡片代理刷新配置有所不同，下面分别介绍具体开发方式。 -## 数据提供方开发步骤 +### 数据提供方开发步骤 参考[数据管理](../database/share-data-by-silent-access.md)开发指南。 -## 卡片提供方开发步骤（过程数据） +### 卡片提供方开发步骤（过程数据） - 配置form_config.json文件中的`dataProxyEnabled`字段为`true`，以启用卡片代理刷新功能，当订阅的过程数据更新时，系统会自动更新卡片数据。 ```json @@ -130,7 +131,7 @@ } ``` -## 卡片提供方开发步骤（持久化数据，仅对系统应用开放） +### 卡片提供方开发步骤（持久化数据，仅对系统应用开放） - 配置form_config.json文件中的`dataProxyEnabled`字段为`true`，以启用卡片代理刷新功能。 ```json { @@ -230,9 +231,12 @@ } ``` -## 相关实例 +### 相关实例 针对卡片代理开发，有以下相关实例可供参考： - [应用主动添加数据代理卡片到桌面（ArkTS）（Full SDK）（API10）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/SystemFeature/Widget/RequestAddForm) - \ No newline at end of file + + +## push代理刷新 +> 在pushkit里有，加说明链接跳转 diff --git a/zh-cn/application-dev/form/arkts-ui-widget-update-by-status.md b/zh-cn/application-dev/form/arkts-ui-widget-update-by-status.md index a43c4ceb59bfb738f973625e22b64fd2b9f0b730..37e7a852256f3eea833a8913d41cd7ae8bf26081 100644 --- a/zh-cn/application-dev/form/arkts-ui-widget-update-by-status.md +++ b/zh-cn/application-dev/form/arkts-ui-widget-update-by-status.md @@ -1,5 +1,5 @@ # 根据卡片状态刷新不同内容 - +> 结合formEditExtension刷新内容 相同的卡片可以添加到桌面上实现不同的功能，比如添加两张桌面的卡片，一张显示杭州的天气，一张显示北京的天气，设置每天早上7点触发定时刷新，卡片需要感知当前的配置是杭州还是北京，然后将对应城市的天气信息刷新到卡片上，以下示例介绍了如何根据卡片的状态动态选择需要刷新的内容。 diff --git a/zh-cn/application-dev/form/arkts-ui-widget-update-by-time-point.md b/zh-cn/application-dev/form/arkts-ui-widget-update-by-time-point.md deleted file mode 100644 index 4feafd2ae8d5bd09131faf69024bd7a1d6306d66..0000000000000000000000000000000000000000 --- a/zh-cn/application-dev/form/arkts-ui-widget-update-by-time-point.md +++ /dev/null @@ -1,71 +0,0 @@ -# 卡片定点刷新 - -当前卡片框架提供了如下两种定点刷新卡片的方式： - -- 单定点刷新：表示在每天的某个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的`scheduledUpdateTime`字段中进行设置。例如，可以将刷新时间设置为每天的上午10点30分。 - - - ```json - { - "forms": [ - { - "name": "ScheduledUpdateTime", - "description": "$string:widget_scheupdatetime_desc", - "src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets", - "uiSyntax": "arkts", - "window": { - "designWidth": 720, - "autoDesignWidth": true - }, - "colorMode": "auto", - "isDefault": true, - "updateEnabled": true, - "scheduledUpdateTime": "10:30", - "updateDuration": 0, - "defaultDimension": "2*2", - "supportDimensions": [ - "2*2" - ] - } - ] - } - ``` - -- 多定点刷新：表示在每天的多个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的`multiScheduledUpdateTime`字段中进行设置，例如，可以将刷新时间设置为每天的上午11点30分和下午4点30分。 - ```json - { - "forms": [ - { - "name": "ScheduledUpdateTime", - "description": "$string:widget_scheupdatetime_desc", - "src": "./ets/scheduledupdatetime/pages/ScheduledUpdateTimeCard.ets", - "uiSyntax": "arkts", - "window": { - "designWidth": 720, - "autoDesignWidth": true - }, - "colorMode": "auto", - "isDefault": true, - "updateEnabled": true, - "scheduledUpdateTime": "10:30", - "multiScheduledUpdateTime": "11:30,16:30,", - "updateDuration": 0, - "defaultDimension": "2*2", - "supportDimensions": [ - "2*2" - ] - } - ] - } - ``` - -在触发定点刷新后，系统会调用FormExtensionAbility的[onUpdateForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onupdateform)生命周期回调，在回调中，可以使用[updateForm](../reference/apis-form-kit/js-apis-app-form-formProvider.md#updateform)进行提供方刷新卡片。`onUpdateForm`生命周期回调的使用请参见[卡片生命周期管理](./arkts-ui-widget-lifecycle.md)。 - -> **说明：** -> 1. 当同时配置了定时刷新`updateDuration`和定点刷新`scheduledUpdateTime`时，定时刷新的优先级更高且定点刷新不会执行。如果想要配置定点刷新，则需要将`updateDuration`配置为0。 -> 2. `multiScheduledUpdateTime`的配置最多可设置24个时间。 -> 3. 同时配置了单定点和多定点刷新，多定点刷新配置生效，单定点刷新配置不生效。 -> 4. 考虑到向前兼容的问题，尽量保留`scheduledUpdateTime`字段，不要直接删除。 - -**约束限制：** -1. 定点刷新在卡片可见情况下才会触发，在卡片不可见时仅会记录刷新动作和刷新数据，待可见时统一刷新布局。 \ No newline at end of file diff --git a/zh-cn/application-dev/website.md b/zh-cn/application-dev/website.md index 8ed8107c1ce595bbd1bae98dd19554cc6a185fe2..b5d27dac0b0883b84736d31ee38a672f0d9cd405 100644 --- a/zh-cn/application-dev/website.md +++ b/zh-cn/application-dev/website.md @@ -796,14 +796,12 @@ - [拉起卡片提供方的UIAbility到后台(call事件)](form/arkts-ui-widget-event-call.md) - [通过message事件刷新卡片内容](form/arkts-ui-widget-event-formextensionability.md) - [通过router或call事件刷新卡片内容](form/arkts-ui-widget-event-uiability.md) - - 卡片数据交互 - - [卡片内容更新](form/arkts-ui-widget-interaction-overview.md) - - [卡片定时刷新](form/arkts-ui-widget-update-by-time.md) - - [卡片定点刷新](form/arkts-ui-widget-update-by-time-point.md) + - ArkTS卡片页面刷新 + - [ArkTS卡片页面刷新概述](form/arkts-ui-widget-overview-refresh.md) + - [ArkTS卡片主动刷新](form/arkts-ui-widget-active-refresh.md) + - [ArkTS卡片被动刷新](form/arkts-ui-widget-passive-refresh.md) - - [卡片代理刷新](form/arkts-ui-widget-update-by-proxy.md) - - [卡片条件刷新](form/arkts-ui-widget-update-by-conditions.md) - - [卡片使用方主动请求刷新卡片内容（仅对系统应用开放）](form/arkts-ui-widget-content-update.md) + - [ArkTS卡片代理刷新](form/arkts-ui-widget-update-by-proxy.md) - [刷新本地图片和网络图片](form/arkts-ui-widget-image-update.md) - [根据卡片状态刷新不同内容](form/arkts-ui-widget-update-by-status.md)