1# 桌面卡片进入案例 2 3### 介绍 4 5桌面卡片是比较常见的功能，本案例详细列举了卡片开发的大部分功能，如使用postCardAction接口快速拉起卡片提供方应用的指定UIAbility，通过message事件刷新卡片内容等，为开发者提供了卡片功能的展示。 6 7### 效果预览 8 9| 卡片 | 案例| 10|--------|-----------| 11| <img src="screenshots/devices/Widget.jpg" width="270" /> | <img src="screenshots/devices/Case.jpg" width="270" />| 12 13### 使用说明 14 151. 长按应用，添加卡片到桌面。 162. 卡片内可滑动选择案例，点击可进入案例详情。 17 18### 实现思路 19 201. 新建卡片 212. 配置formconfig 223. 编写卡片UI代码 234. 触发刷新事件 245. 触发点击事件 25 26### 实现步骤 27 28本例涉及的关键特性和实现方案如下： 29 301. 新建卡片。右键点击entry目录，选择新建->Service Widget->Dynamic Widget，其中Dynamic Widget为动态卡片，Static Widget为静态卡片。此时会生成几个文件：配置文件[```form_config.json```](entry/src/main/resources/base/profile/form_config.json)；卡片Ability[```EntryFormAbility.ets```](entry/src/main/ets/entryformability/EntryFormAbility.ets)；卡片组件[```CasesSwiperCard.ets```](entry/src/main/ets/widget/pages/CasesSwiperCard.ets)。 31 322. 新建卡片后，根据需要（如卡片大小，刷新时间，动态静态卡片设置）配置```form_config.json```。 33 34```json5 35{ 36 "forms": [ 37 { 38 "name": "widget", // 卡片的名称。 39 "displayName": "$string:widget_display_name", // 卡片的显示名称。 40 "description": "$string:widget_desc", // 卡片的描述。 41 "src": "./ets/widget/pages/CasesSwiperCard.ets", // 卡片对应的UI代码的完整路径。 42 "uiSyntax": "arkts", // 卡片的类型 43 "window": { // 用于定义与显示窗口相关的配置。 44 "designWidth": 720, 45 "autoDesignWidth": true 46 }, 47 "colorMode": "auto", // 卡片的主题样式。 48 "isDynamic": true, // 卡片是否为动态卡片。 49 "isDefault": true, // 卡片是否为默认卡片。 50 "updateEnabled": true, // 卡片是否支持周期性刷新。 51 "scheduledUpdateTime": "10:30", // 卡片的定点刷新的时刻。 52 "updateDuration": 1, // 卡片定时刷新的更新周期，单位为30分钟，取值为自然数。 53 "defaultDimension": "6*4", // 卡片的默认外观规格。 54 "supportDimensions": [ // 卡片支持的外观规格，取值范围。 55 "6*4" 56 ] 57 } 58 ] 59} 60``` 61 623. 编写卡片UI代码。在主文件```CasesSwiperCard.ets```中添加UI组件，需要注意的是：ArkTS卡片存在较多约束（如不支持导入共享包），较多逻辑不可在卡片中使用，在使用时需要根据文档进行操作。 63 644. 编写跳转事件：当应用未被拉起时，点击某个卡片时跳转到具体的案例页面。在```EntryAbility.ets```中补充逻辑：onCreate生命周期内获取want.parameters.params判断卡片内容的跳转。 65 66```typescript 67// EntryAbility.ets 68export default class EntryAbility extends UIAbility { 69 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 70 // ... 71 // 桌面卡片判断跳转内容 72 if (want?.parameters?.params) { 73 // want.parameters.params 对应 postCardAction() 中 params 内容 74 let params: Record<string, Object> = JSON.parse(want.parameters.params as string); 75 this.selectPage = params.targetPage as string; 76 } 77 // ... 78 } 79} 80``` 81 825. 编写跳转事件：当应用在后台时，点击某个卡片时跳转到具体的案例页面。可从onNewWant生命周期获取want.parameters.params判断卡片内容的跳转。 83 84```typescript 85// EntryAbility.ets 86export default class EntryAbility extends UIAbility { 87 // 如果UIAbility已在后台运行，在收到Router事件后会触发onNewWant生命周期回调 88 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 89 if (want.parameters!['ability.params.stream'] !== undefined) { 90 AppStorage.setOrCreate('imageUri', want.parameters!["ability.params.stream"].toString()); 91 return; 92 } 93 if (want?.parameters?.params) { 94 // want.parameters.params 对应 postCardAction() 中 params 内容 95 let params: Record<string, Object> = JSON.parse(want.parameters.params as string); 96 this.selectPage = params.targetPage as string; 97 if (this.currentWindowStage !== null) { 98 // 存在窗口时点击卡片后进行页面跳转 99 this.currentWindowStage.loadContent(`pages/${this.selectPage}`, (err) => { 100 if (err.code) { 101 hilog.error(0x0000, 'testTagSelectPage', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 102 return; 103 } 104 hilog.info(0x0000, 'testTagSelectPage', 'Succeeded in loading the content.'); 105 }); 106 this.selectPage = ''; 107 } 108 } else { 109 this.selectPage = ''; 110 } 111 } 112} 113``` 114 1156. 具体跳转逻辑编写。在onWindowStageCreate生命周期内进行具体的跳转逻辑。 116 117```typescript 118// EntryAbility.ets 119export default class EntryAbility extends UIAbility { 120 onWindowStageCreate(windowStage: window.WindowStage): void { 121 // Main window is created, set main page for this ability 122 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 123 // 判断是否存在窗口可进行页面跳转 124 if (this.currentWindowStage === null) { 125 this.currentWindowStage = windowStage; 126 } 127 // 点击卡片后进行页面跳转 128 if (this.selectPage) { 129 windowStage.loadContent(`pages/${this.selectPage}`, (err) => { 130 if (err.code) { 131 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 132 return; 133 } 134 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 135 }); 136 } else { 137 windowStage.loadContent('pages/Index', (err) => { 138 if (err.code) { 139 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 140 return; 141 } 142 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content.'); 143 }); 144 } 145 } 146} 147``` 148 1497. 编写刷新事件：当定时更新或定点更新触发时，需要更新卡片内容。onUpdateForm生命周期发生在定时更新/定点更新/卡片使用方主动请求更新时，在方法内增加获取案例数据的功能。 150 151```typescript 152// EntryFormAbility.ets 153export default class EntryFormAbility extends FormExtensionAbility { 154 // 获取数据并利用formProvider.updateForm更新到卡片 155 async getData(formId: string) { 156 let detail: CASES[] = []; 157 let message = ''; 158 try { 159 let value = await this.context.resourceManager.getRawFileContent('CasesData.txt'); 160 console.log('decodeToStringdecodeToString') 161 message = util.TextDecoder.create().decodeToString(value); 162 detail = CaseCardUtils.formatData(message); 163 hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onFormEvent' + 'result:' + message); 164 hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] getData' + 'detail:' + JSON.stringify(detail)); 165 class FormDataClass { 166 public detail: CASES[] = detail; 167 } 168 let formData = new FormDataClass(); 169 let formInfo = formBindingData.createFormBindingData(formData); 170 await formProvider.updateForm(formId, formInfo); 171 } catch (error) { 172 hilog.error(DOMAIN_NUMBER, TAG, `FormAbility updateForm failed: ${JSON.stringify(error)}`); 173 } 174 } 175 176 async onUpdateForm(formId: string): Promise<void> { 177 // 若卡片支持定时更新/定点更新/卡片使用方主动请求更新功能，则提供方需要重写该方法以支持数据更新 178 hilog.info(DOMAIN_NUMBER, TAG, '[EntryFormAbility] onUpdateForm'); 179 this.getData(formId); 180 } 181} 182``` 183 1848. 编写刷新事件：参数传到卡片组件内，组件接收参数。处理```CasesSwiperCard.ets```卡片内逻辑。卡片页面中使用LocalStorageProp装饰需要刷新的卡片数据。 185 186```ts 187let casesCardInfo = new LocalStorage(); 188@Entry(casesCardInfo) 189@Component 190struct Widget_DynamicCard { 191 @LocalStorageProp('detail') detail: CASES[] = []; // 卡片对象集合 192 private swiperController: SwiperController = new SwiperController(); 193 194 build() { 195 // ... 196 } 197} 198``` 199 200### 工程结构&模块类型 201 202``` 203CardInteractionCase // har 204|---entryability 205| |---EntryAbility.ets // EntryAbility 206|---entryformability 207| |---EntryFormAbility.ets //EntryFormAbility 208|---pages 209| |---DealStrideSolution.ets // 解决相机预览花屏案例页面 210| |---EncapsulationDialog.ets // 弹窗封装案例页面 211| |---Index.ets // 首页页面 212| |---ShareButton.ets // 分享二维码按钮案例页面 213| |---SmartFill.ets // 智能填充案例页面 214| |---VideoTrimmer.ets // 视频下载保存及剪辑压缩上传案例页面 215|---widget 216| |---pages 217| |---CasesSwiperCard.ets // 卡片页面 218| |---utils 219| |---CaseCardUtils.ets // 卡片公共方法页面 220``` 221 222### 参考资料 223 224[创建一个ArkTS卡片](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/form/arkts-ui-widget-creation.md) 225 226[配置卡片的配置文件](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/form/arkts-ui-widget-configuration.md) 227 228[使用router事件跳转到指定UIAbility](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/form/arkts-ui-widget-event-router.md) 229 230[通过message事件刷新卡片内容](https://docs.openharmony.cn/pages/v5.0/zh-cn/application-dev/form/arkts-ui-widget-event-formextensionability.md) 231 232### 依赖 233 234不涉及。 235 236### 约束与限制 237 2381.本示例仅支持标准系统上运行。 239 2402.本示例已适配API version 12版本SDK。 241 2423.本示例需要使用DevEco Studio 5.0.0 Release及以上版本才可编译运行。 243 244### 下载 245 246如需单独下载本工程，执行如下命令： 247 248``` 249git init 250git config core.sparsecheckout true 251echo code/SuperFeature/Widget/ArkTSCard/CardInteractionCase/ > .git/info/sparse-checkout 252git remote add origin https://gitee.com/openharmony/applications_app_samples.git 253git pull origin master 254``` 255
