!19725 数据代理刷新卡片资料

Merge pull request !19725 from 李伟峰/master

zh-cn/application-dev/application-models/Readme-CN.md

@@ -42,7 +42,8 @@
             - [通过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.md)
+            - [卡片代理刷新](arkts-ui-widget-update-by-proxy.md)
             - [刷新本地图片和网络图片](arkts-ui-widget-image-update.md)
             - [根据卡片状态刷新不同内容](arkts-ui-widget-update-by-status.md)
             - [使用方刷新卡片内容（仅对系统应用开放）](arkts-ui-widget-content-update.md)

zh-cn/application-dev/application-models/arkts-ui-widget-interaction-overview.md

 # 卡片数据交互说明
 
-ArkTS卡片框架提供了updateForm()接口和requestForm()接口主动触发卡片的页面刷新。  
+ArkTS卡片框架提供了updateForm()接口和requestForm()接口主动触发卡片的页面刷新。
 ![WidgetLocalStorageProp](figures/WidgetLocalStorageProp.png)
 
 
@@ -11,7 +11,8 @@ ArkTS卡片框架提供了updateForm()接口和requestForm()接口主动触发
 
 下面介绍卡片页面刷新的典型场景。
 
-- [定时刷新和定点刷新](arkts-ui-widget-update-by-time.md)
+- [卡片定时刷新和定点刷新](arkts-ui-widget-update-by-time.md)
+- [卡片代理刷新](arkts-ui-widget-update-by-proxy.md)
 - [刷新本地图片和网络图片](arkts-ui-widget-image-update.md)
 - [根据卡片状态刷新不同内容](arkts-ui-widget-update-by-status.md)
 - [使用方刷新卡片内容（仅对系统应用开放）](arkts-ui-widget-content-update.md)
\ No newline at end of file

zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md

+# 卡片代理刷新
+
+卡片代理刷新是一种通过系统应用刷新卡片的机制。卡片提供方不在运行时，仍然可以通过开启了数据共享能力的系统应用完成卡片数据的更新。
+
+## 实现原理
+
+**图1** 代理刷新运行原理
+![UpdateWidgetByProxyPrinciple](figures/UpdateWidgetByProxyPrinciple.png)
+
+如图1，与[arkTS卡片实现原理图](../application-models/arkts-ui-widget-working-principles.md#实现原理)相比，新增了数据管理服务和数据提供方。
+
+- 数据管理服务：该场景下主要提供了多应用间的数据共享的机制。
+- 数据提供方（仅支持系统应用）：系统应用作为数据提供方，需要开启数据共享能力，同时需要自定义`key + subscriberId`作为共享数据的标识。
+
+卡片提供方处理流程（图中蓝色箭头）：
+
+1. 卡片提供方在卡片提供方的配置文件`form_config.json`中配置`dataProxyEnabled`字段为`true`，以开启卡片代理刷新功能。
+> **说明：**
+>
+> 卡片代理刷新开启后，[定时刷新](../application-models/arkts-ui-widget-update-by-time.md)和[下次刷新](../application-models/arkts-ui-widget-update-by-time.md)失效。
+
+2. 卡片提供方在[onAddForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#onaddform)回调中，把数据提供方定义的`key + subscriberId`返回给卡片管理服务。
+
+3. 卡片管理服务解析卡片提供方的订阅信息，并向数据管理服务注册订阅实例。
+
+卡片代理刷新运行流程（图中红色箭头）：
+
+1. 数据提供方以`key + subscriberId`作为数据的标识，将数据存储到数据库。
+2. 数据管理服务感知到数据库变化，将新的数据发布给当前注册的所有订阅实例。
+3. 卡片管理服务从订阅实例中解析出数据，发送给卡片渲染服务。
+4. 卡片渲染服务运行卡片页面代码widgets.abc，widgets.abc按新数据进行渲染，并将渲染后的数据发送至卡片使用方对应的[卡片组件](https://gitee.com/openharmony/docs/blob/fd489446c497c09d86ffa3beafd73dad90f1adb6/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md)。
+
+数据提供方提供的共享数据有两种类型：
+
+- 过程数据，不会一直存储，有老化期，普通应用可以订阅。
+
+- 持久化数据，仅系统应用可以订阅。
+
+相应的卡片代理刷新配置有所不同，下面分别介绍具体开发方式。
+
+
+## 卡片提供方开发步骤（过程数据）
+
+- 配置form_config.json文件中的`dataProxyEnabled`字段为`true`，以启用卡片代理刷新功能。
+  ```json
+  {
+    "forms": [
+      {
+        "name": "widget",
+        "description": "This is a service widget.",
+        "src": "./ets/widget/pages/WidgetCard.ets",
+        "uiSyntax": "arkts",
+        "window": {
+          "designWidth": 720,
+          "autoDesignWidth": true
+        },
+        "colorMode": "auto",
+        "isDefault": true,
+        "updateEnabled": true,
+        "scheduledUpdateTime": "10:30",
+        "defaultDimension": "2*2",
+        "supportDimensions": ["2*2"],
+        "dataProxyEnabled": true // 使能数据代理功能
+      }
+    ]
+  }
+  ```
+
+- 在[onAddForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#onaddform)回调中配置订阅信息[proxies](../reference/apis/js-apis-app-form-formBindingData.md#proxydata)，并通过[formBinding](../reference/apis/js-apis-app-form-formBindingData.md#formbindingdata)返回给卡片管理服务。示例中将key设置为"detail"，subscriberId设置为"11"。
+  > **说明：**
+  >
+  > key可以是uri也可以是简单字符串，subscriberId默认值为当前formId，实际取值都依赖于数据发布方的定义。
+  ```ts
+  import formBindingData from '@ohos.app.form.formBindingData';
+  
+  let dataShareHelper;
+  onAddForm(want) {
+    let formData = {};
+    let proxies = [
+      {
+        "key": "detail",
+        "subscriberId": "11"
+      }
+    ]
+    let formBinding = formBindingData.createFormBindingData(formData);
+    formBinding["proxies"] = proxies;
+    return formBinding;
+  }
+  ```
+
+- 在卡片页面代码widgets.abc中，通过LocalStorage变量获取订阅到的数据。示例中，通过'detail'获取订阅的数据，并在Text组件显示。
+  ```ts
+  let storage = new LocalStorage();
+  @Entry(storage)
+  @Component
+  struct Index {
+    @LocalStorageProp('detail') detail: string = '加载中...';
+  
+    build() {
+      Row() {
+        Column() {
+          Text(this.detail)
+            .fontSize('12vp')
+            .textAlign(TextAlign.Center)
+            .width('100%')
+            .height('15%')
+        }
+  	  .width('100%')
+      }
+  	.height('100%')
+    }
+  }
+  ```
+
+## 卡片提供方开发步骤（持久化数据，仅对系统应用开放）
+- 配置form_config.json文件中的`dataProxyEnabled`字段为`true`，以启用卡片代理刷新功能。
+  ```json
+  {
+    "forms": [
+      {
+        "name": "widget",
+        "description": "This is a service widget.",
+        "src": "./ets/widget/pages/WidgetCard.ets",
+        "uiSyntax": "arkts",
+        "window": {
+          "designWidth": 720,
+          "autoDesignWidth": true
+        },
+        "colorMode": "auto",
+        "isDefault": true,
+        "updateEnabled": true,
+        "scheduledUpdateTime": "10:30",
+        "defaultDimension": "2*2",
+        "supportDimensions": ["2*2"],
+        "dataProxyEnabled": true // 使能数据代理功能
+      }
+    ]
+  }
+  ```
+
+- 在[onAddForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#onaddform)回调中添加订阅模板[addTemplate]([../reference/apis/js-apis-data-dataShare.md#addtemplate10)，通过模板谓词告诉数据库订阅的数据条件。然后配置订阅信息[proxies](../reference/apis/js-apis-app-form-formBindingData.md#proxydata)，并通过[formBinding](../reference/apis/js-apis-app-form-formBindingData.md#formbindingdata)返回给卡片管理服务。示例中将谓词设置为`"list" : "select type from TBL00 limit 0,1"`，表示从TBL00数据库中获取type列的第一条数据，数据将会以`{"list":[{"type":"value0"}]}`格式返回到卡片页面代码widgets.abc中。
+
+  > **说明：**
+  >
+  > - key的取值是uri，依赖于数据发布方定义。
+  > - subscriberId可自定义，addTemplate中的subscriberId参数与proxies.subscriberId保持一致即可。
+  ```ts
+  import formBindingData from '@ohos.app.form.formBindingData';
+  import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
+  import dataShare from '@ohos.data.dataShare'
+
+  let dataShareHelper;
+  onAddForm(want) {
+    let template = {
+      predicates : {
+        "list" : "select type from TBL00 limit 0,1"
+      },
+      scheduler: ""
+    }
+    let subscriberId = "111";
+    dataShare.createDataShareHelper(this.context, "datashareproxy://com.example.myapplication", {isProxy : true}).then((data) => {
+      dataShareHelper = data;
+      dataShareHelper.addTemplate("datashareproxy://com.example.myapplication/test", subscriberId, template);
+    })
+
+    let formData = {};
+    let proxies = [
+      {
+        "key": "datashareproxy://com.example.myapplication/test",
+        "subscriberId": subscriberId
+      }
+    ]
+    let formBinding = formBindingData.createFormBindingData(formData);
+    formBinding["proxies"] = proxies;
+
+    return formBinding;
+  }
+  ```
+
+- 在卡片页面代码widgets.abc中，通过LocalStorage变量获取订阅到的数据。示例中，通过'list'获取订阅的数据，并把第一个元素的值显示在Text组件上。
+  ```ts
+  let storage = new LocalStorage();
+  @Entry(storage)
+  @Component
+  struct WidgetCard {
+    readonly ACTION_TYPE: string = 'router';
+    readonly ABILITY_NAME: string = 'EntryAbility';
+    readonly MESSAGE: string = 'add detail';
+    readonly FULL_WIDTH_PERCENT: string = '100%';
+    readonly FULL_HEIGHT_PERCENT: string = '100%';
+    @LocalStorageProp('list') list: Array<object> = [{"type": "a"}];
+  
+    build() {
+      Row() {
+        Column() {
+          Text((this.list[0]["type"]))
+            .fontSize($r('app.float.font_size'))
+        }
+        .width(this.FULL_WIDTH_PERCENT)
+      }
+      .height(this.FULL_HEIGHT_PERCENT)
+      .onClick(() => {
+        postCardAction(this, {
+          "action": this.ACTION_TYPE,
+          "abilityName": this.ABILITY_NAME,
+          "params": {
+            "message": this.MESSAGE
+          }
+        })
+      })
+    }
+  }
+  ```
+
+## 数据提供方开发步骤
+
+参考[数据管理](../database/data-mgmt-overview.md)开发指南。

zh-cn/application-dev/application-models/arkts-ui-widget-update-by-time.md

-# 定时刷新和定点刷新
+# 卡片定时刷新和定点刷新
 
 在使用定时和定点刷新功能之前，需要在form_config.json配置文件中设置`updateEnabled`字段为`true`，以启用周期性刷新功能。
 
@@ -6,11 +6,11 @@
 
 
 - 定时刷新：表示在一定时间间隔内调用[onUpdateForm](../reference/apis/js-apis-app-form-formExtensionAbility.md#onupdateform)的生命周期回调函数自动刷新卡片内容。可以在form_config.json配置文件的[`updateDuration`](arkts-ui-widget-configuration.md)字段中进行设置。例如，可以将刷新时间设置为每小时一次。
-  
+
   > **说明：**
   >
   > 当配置了`updateDuration`（定时刷新）后，该设置会优先于`scheduledUpdateTime`（定点刷新）生效，即使同时配置了两者，定点刷新也会被忽略。
-  
+
   ```json
   {
     "forms": [
@@ -26,7 +26,7 @@
         "colorMode": "auto",
         "isDefault": true,
         "updateEnabled": true, // 使能刷新功能
-        "scheduledUpdateTime": "10:30",                               
+        "scheduledUpdateTime": "10:30",
         "updateDuration": 2, // 设置卡片定时刷新的更新周期（单位为30分钟，取值为自然数）
         "defaultDimension": "2*2",
         "supportDimensions": ["2*2"]
@@ -34,14 +34,14 @@
     ]
   }
   ```
-  
+
 - 定点刷新：表示在每天的某个特定时间点自动刷新卡片内容。可以在form_config.json配置文件中的[`scheduledUpdateTime`](arkts-ui-widget-configuration.md)字段中进行设置。例如，可以将刷新时间设置为每天的上午10点30分。
-  
+
   > **说明：**
   >
   > 当同时配置了定时刷新（`updateDuration`）和定点刷新（`scheduledUpdateTime`)时，定时刷新的优先级更高。如果想要配置定点刷新，则需要将`updateDuration`配置为0。
-  
-  
+
+
   ```json
   {
     "forms": [
@@ -65,12 +65,12 @@
     ]
   }
   ```
-  
+
 - 下次刷新：表示指定卡片的下一次刷新时间。可以通过调用[`setFormNextRefreshTime()`](../reference/apis/js-apis-app-form-formProvider.md#setformnextrefreshtime)接口来实现。最短刷新时间为5分钟。例如，可以在接口调用后的5分钟内刷新卡片内容。
-  
+
   ```ts
   import formProvider from '@ohos.app.form.formProvider';
-  
+
   let formId = '123456789'; // 实际业务场景需要使用正确的formId
   try {
     // 设置过5分钟后更新卡片内容
@@ -93,7 +93,7 @@
 
 > **说明：**
 > 1. 定时刷新有配额限制，每张卡片每天最多通过定时方式触发刷新50次，定时刷新包含[卡片配置项updateDuration](arkts-ui-widget-configuration.md)和调用[`setFormNextRefreshTime()`](../reference/apis/js-apis-app-form-formProvider.md#setformnextrefreshtime)方法两种方式，当达到50次配额后，无法通过定时方式再次触发刷新，刷新次数会在每天的0点重置。
-> 
+>
 > 2. 当前定时刷新使用同一个计时器进行计时，因此卡片定时刷新的第一次刷新会有最多30分钟的偏差。比如第一张卡片A（每隔半小时刷新一次）在3点20分添加成功，定时器启动并每隔半小时触发一次事件，第二张卡片B(每隔半小时刷新一次)在3点40分添加成功，在3点50分定时器事件触发时，卡片A触发定时刷新，卡片B会在下次事件（4点20分）中才会触发。
-> 
+>
 > 3. 定时刷新和定点刷新仅在屏幕亮屏情况下才会触发，在灭屏场景下仅会将记录刷新动作，待亮屏时统一进行刷新。

zh-cn/application-dev/reference/apis/js-apis-app-form-formBindingData.md

@@ -12,6 +12,19 @@
 import formBindingData from '@ohos.app.form.formBindingData';
 ```
 
+
+## ProxyData<sup>10+</sup>
+
+卡片代理刷新订阅数据信息。
+
+**系统能力**：SystemCapability.Ability.Form
+
+| 名称 | 类型 | 必填 | 说明 |
+| -------- | -------- | -------- | -------- |
+| key | string | 是 | 卡片代理刷新的订阅标识，与数据发布者保持一致。|
+| subscriberId | string | 否 | 卡片代理刷新的订阅条件，默认值为当前卡片的formId。|
+
+
 ## FormBindingData
 
 FormBindingData相关描述。
@@ -21,6 +34,7 @@ FormBindingData相关描述。
 | 名称 | 类型 | 必填 | 说明 |
 | -------- | -------- | -------- | -------- |
 | data | Object | 是 | js卡片要展示的数据。可以是包含若干键值对的Object或者 json 格式的字符串。|
+| proxies<sup>10+</sup> | Array<[ProxyData](#proxydata)> | 否 | 卡片代理刷新的订阅信息，默认为空数组。|
 
 
 ## createFormBindingData