1# 卡片代理刷新 2 3卡片代理刷新是一种通过系统应用刷新卡片的机制。卡片提供方不在运行时，仍然可以通过开启了数据共享能力的系统应用完成卡片数据的更新。 4 5## 实现原理 6 7**图1** 代理刷新运行原理 8 9 10如图1，与[ArkTS卡片实现原理图](arkts-ui-widget-working-principles.md#实现原理)相比，卡片代理刷新原理新增了数据管理服务和数据提供方。 11 12- 数据管理服务：该场景下主要提供了多应用间的数据共享的机制。 13- 数据提供方（仅支持系统应用）：系统应用作为数据提供方，需要开启数据共享能力，同时需要自定义`key + subscriberId`作为共享数据的标识。 14 15> **说明：** 16> 17> 只有系统提供了作为数据提供方的应用，同时提供公开可获得的共享数据标识，才能正常使用该特性。 18 19卡片提供方处理流程（图中蓝色箭头）： 20 211. 卡片提供方在卡片提供方的配置文件`form_config.json`中配置`dataProxyEnabled`字段为`true`，以开启卡片代理刷新功能。 22> **说明：** 23> 24> 卡片代理刷新开启后，[定时刷新](arkts-ui-widget-update-by-time.md)和[下次刷新](arkts-ui-widget-update-by-time.md)失效。 25 262. 卡片提供方在[onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onaddform)回调中，把数据提供方定义的`key + subscriberId`返回给卡片管理服务。 27 283. 卡片管理服务解析卡片提供方的订阅信息，并向数据管理服务注册订阅实例。 29 30卡片代理刷新运行流程（图中红色箭头）： 31 321. 数据提供方以`key + subscriberId`作为数据的标识，将数据存储到数据库。 332. 数据管理服务感知到数据库变化，将新的数据发布给当前注册的所有订阅实例。 343. 卡片管理服务从订阅实例中解析出数据，发送给卡片渲染服务。 354. 卡片渲染服务运行卡片页面代码widgets.abc，widgets.abc按新数据进行渲染，并将渲染后的数据发送至卡片使用方对应的[卡片组件](../reference/apis-arkui/arkui-ts/ts-basic-components-formcomponent-sys.md)。 36 37数据提供方提供的共享数据有两种类型： 38 39- 过程数据，不会一直存储，有老化期，所有应用都可以订阅。 40 41- 持久化数据，仅系统应用可以订阅。 42 43相应的卡片代理刷新配置有所不同，下面分别介绍具体开发方式。 44 45## 数据提供方开发步骤 46 47参考[数据管理](../database/share-data-by-silent-access.md)开发指南。 48 49## 卡片提供方开发步骤（过程数据） 50 51- 配置form_config.json文件中的`dataProxyEnabled`字段为`true`，以启用卡片代理刷新功能，当订阅的过程数据更新时，系统会自动更新卡片数据。 52 ```json 53 { 54 "forms": [ 55 { 56 "name": "WidgetProcessData", 57 "description": "$string:ProcessDataEntryAbility_desc", 58 "src": "./ets/widgetprocessdata/pages/WidgetProcessDataCard.ets", 59 "uiSyntax": "arkts", 60 "window": { 61 "designWidth": 720, 62 "autoDesignWidth": true 63 }, 64 "colorMode": "auto", 65 "isDefault": true, 66 "updateEnabled": true, 67 "scheduledUpdateTime": "10:30", 68 "defaultDimension": "2*2", 69 "supportDimensions": [ 70 "2*2" 71 ], 72 "dataProxyEnabled": true 73 } 74 ] 75 } 76 ``` 77 78- 在[onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onaddform)回调中配置订阅信息[proxyData](../reference/apis-form-kit/js-apis-app-form-formBindingData.md#proxydata10)，并通过[formBinding](../reference/apis-form-kit/js-apis-app-form-formBindingData.md#formbindingdata)返回给卡片管理服务。示例中将key设置为"datashareproxy://com.samples.widgetupdatebyproxy/weather"，subscriberId设置为"11"。 79 > **说明：** 80 > 81 > key可以是uri也可以是简单字符串，subscriberId默认值为当前formId，实际取值都依赖于数据发布方的定义。 82 ```ts 83 import formBindingData from '@ohos.app.form.formBindingData'; 84 import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 85 import hilog from '@ohos.hilog'; 86 import type Want from '@ohos.app.ability.Want'; 87 88 const TAG: string = 'ProcessDataFormAbility'; 89 const DOMAIN_NUMBER: number = 0xFF00; 90 91 export default class ProcessDataFormAbility extends FormExtensionAbility { 92 onAddForm(want: Want): formBindingData.FormBindingData { 93 let formData: Record<string, Object> = {}; 94 let proxies: formBindingData.ProxyData[] = [ 95 { 96 key: 'datashareproxy://com.samples.widgetupdatebyproxy/weather', 97 subscriberId: '11' 98 } 99 ]; 100 let formBinding = formBindingData.createFormBindingData(formData); 101 formBinding.proxies = proxies; 102 hilog.info(DOMAIN_NUMBER, TAG, 'onAddForm'); 103 return formBinding; 104 } 105 } 106 ``` 107 108- 在[卡片页面文件](arkts-ui-widget-creation.md)中，通过LocalStorage变量获取订阅到的数据，LocalStorage绑定了一个字符串，以key:value的键值对格式来刷新卡片订阅数据，其中key必须与卡片提供方订阅的key保持一致。示例中，通过'detail'获取订阅的数据，并在Text组件显示。 109 ```ts 110 let storageProcess = new LocalStorage(); 111 112 @Entry(storageProcess) 113 @Component 114 struct WidgetProcessDataCard { 115 @LocalStorageProp('datashareproxy://com.samples.widgetupdatebyproxy/weather') city: ResourceStr = $r('app.string.loading'); 116 117 build() { 118 Column() { 119 Column() { 120 Text(this.city) 121 .fontColor('#FFFFFF') 122 .opacity(0.9) 123 .fontSize(14) 124 .margin({ top: '8%', left: '10%' }) 125 }.width('100%') 126 .alignItems(HorizontalAlign.Start) 127 }.width('100%').height('100%') 128 .backgroundImage($r('app.media.CardEvent')) 129 .backgroundImageSize(ImageSize.Cover) 130 } 131 } 132 ``` 133 134## 卡片提供方开发步骤（持久化数据，仅对系统应用开放） 135- 配置form_config.json文件中的`dataProxyEnabled`字段为`true`，以启用卡片代理刷新功能。 136 ```json 137 { 138 "forms": [ 139 { 140 "name": "WidgetPersistentData", 141 "description": "This is a service widget update by proxy using persistent data.", 142 "src": "./ets/widgetpersistentdata/pages/WidgetPersistentDataCard.ets", 143 "uiSyntax": "arkts", 144 "window": { 145 "designWidth": 720, 146 "autoDesignWidth": true 147 }, 148 "colorMode": "auto", 149 "isDefault": true, 150 "updateEnabled": true, 151 "scheduledUpdateTime": "10:30", 152 "updateDuration": 1, 153 "defaultDimension": "2*2", 154 "supportDimensions": [ 155 "2*2" 156 ], 157 "dataProxyEnabled": true 158 } 159 ] 160 } 161 ``` 162 163- 在[onAddForm](../reference/apis-form-kit/js-apis-app-form-formExtensionAbility.md#onaddform)回调中添加订阅模板[addTemplate](../reference/apis-arkdata/js-apis-data-dataShare-sys.md#addtemplate10)，通过模板谓词告诉数据库订阅的数据条件。然后配置订阅信息[proxyData](../reference/apis-form-kit/js-apis-app-form-formBindingData.md#proxydata10)，并通过[formBinding](../reference/apis-form-kit/js-apis-app-form-formBindingData.md#formbindingdata)返回给卡片管理服务。示例中将谓词设置为`"list" : "select type from TBL00 limit 0,1"`，表示从TBL00数据库中获取type列的第一条数据，数据将会以`{"list":[{"type":"value0"}]}`格式返回到卡片页面代码widgets.abc中。当订阅的持久化数据更新时，系统会自动更新卡片数据。 164 165 > **说明：** 166 > 167 > - key的取值是uri，依赖于数据发布方定义。 168 > - subscriberId可自定义，addTemplate中的subscriberId参数与proxies.subscriberId保持一致即可。 169 ```ts 170 import dataShare from '@ohos.data.dataShare'; 171 import type formBindingData from '@ohos.app.form.formBindingData'; 172 import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 173 import type Want from '@ohos.app.ability.Want'; 174 175 export default class PersistentDataFormAbility extends FormExtensionAbility { 176 onAddForm(want: Want): formBindingData.FormBindingData { 177 let dataShareHelper; 178 let subscriberId = '111'; 179 let template = { 180 predicates: { 181 'list': `select type from TBL00 where cityId = ${subscriberId}` 182 }, 183 scheduler: '' 184 }; 185 dataShare.createDataShareHelper(this.context, 'datashareproxy://com.samples.widgetupdatebyproxy', { 186 isProxy: true 187 }).then((data) => { 188 dataShareHelper = data; 189 dataShareHelper.addTemplate('datashareproxy://com.samples.widgetupdatebyproxy/test', subscriberId, template); 190 }); 191 let formData = {}; 192 let proxies = [ 193 { 194 key: 'datashareproxy://com.samples.widgetupdatebyproxy/test', 195 subscriberId: subscriberId 196 } 197 ]; 198 199 let formBinding = { 200 data: JSON.stringify(formData), 201 proxies: proxies 202 }; 203 return formBinding; 204 } 205 } 206 ``` 207 208- 在[卡片页面文件](arkts-ui-widget-creation.md)中，通过LocalStorage变量获取订阅到的数据，LocalStorage绑定了一个字符串，以key:value的键值对格式来刷新卡片订阅数据，其中key必须与卡片提供方订阅的key保持一致。示例中，通过'list'获取订阅的数据，并把第一个元素的值显示在Text组件上。 209 ```ts 210 let storagePersis = new LocalStorage(); 211 212 @Entry(storagePersis) 213 @Component 214 struct WidgetPersistentDataCard { 215 readonly FULL_WIDTH_PERCENT: string = '100%'; 216 readonly FULL_HEIGHT_PERCENT: string = '100%'; 217 @LocalStorageProp('list') list: Record<string, string>[] = [{ 'type': 'a' }]; 218 219 build() { 220 Column() { 221 Column() { 222 Text((this.list[0]['type'])) 223 .fontColor('#FFFFFF') 224 .opacity(0.9) 225 .fontSize(14) 226 .margin({ top: '8%', left: '10%' }) 227 }.width('100%') 228 .alignItems(HorizontalAlign.Start) 229 }.width(this.FULL_WIDTH_PERCENT).height(this.FULL_HEIGHT_PERCENT) 230 .backgroundImage($r('app.media.CardEvent')) 231 .backgroundImageSize(ImageSize.Cover) 232 } 233 } 234 ``` 235 236## 相关实例 237 238针对卡片代理开发，有以下相关实例可供参考： 239 240- [应用主动添加数据代理卡片到桌面（ArkTS）（Full SDK）（API10）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/SuperFeature/Widget/RequestAddForm)
