当前位置：首页 > news >正文

HarmonyOS ArkTS卡片开发：多种方式实现卡片信息刷新

news 2026/3/27 6:24:02

在移动应用生态中，卡片作为重要信息的快捷展示形式，极大地提升了用户体验。HarmonyOS的ArkTS卡片开发为开发者提供了强大的工具，本文将基于CardInfoRefresh示例项目，深入解析ArkTS卡片开发的核心原理与实践。

1. ArkTS卡片概述与优势

ArkTS卡片是HarmonyOS中一种创新的界面展示形式，它允许应用将重要信息或操作前置到卡片，以达到服务直达、减少体验层级的目的。与传统的JS卡片相比，ArkTS卡片带来了显著的优势：

统一开发范式：ArkTS卡片统一了卡片和页面的开发范式，页面的布局可以直接复用到卡片布局中，这大大提升了开发体验和开发效率。

增强的功能特性：ArkTS卡片新增了动效能力和自定义绘制能力，开放了Canvas画布组件，使卡片能够构建更多样的显示和交互效果。

逻辑代码执行：最重要的是，ArkTS卡片允许在卡片中运行逻辑代码，这意味着很多业务逻辑可以在卡片内部自闭环，极大地拓宽了卡片的业务适用场景。

2. ArkTS卡片运行机制

理解ArkTS卡片的运行机制对于开发至关重要。ArkTS卡片的架构包含四个核心角色：

卡片提供方：提供卡片显示内容的应用，控制卡片的显示内容、控件布局以及控件点击事件。
卡片使用方：显示卡片内容的宿主应用，控制卡片在宿主中展示的位置。
卡片管理服务：用于管理系统中所添加卡片的常驻代理服务，提供formProvider和formHost的接口能力。
卡片渲染服务：用于管理卡片渲染实例，运行卡片页面代码进行渲染。

与静态卡片相比，ArkTS卡片的核心区别在于渲染机制：卡片渲染服务将卡片内容渲染完毕后，卡片使用方会使用渲染数据，且卡片渲染服务中的卡片实例能够保持运行状态，支持动态更新。

3. 卡片刷新方式实战解析

CardInfoRefresh示例项目展示了四种主要的卡片信息刷新方式，每种方式都有其适用场景。

3.1 工程结构概览

在深入代码之前，先了解项目结构：

├──entry/src/main/ets/
│  ├──common/
│  │  ├──CommonConstants.ets              // 卡片数据常量
│  │  └──CommonData.ets                   // 卡片数据工具类
│  ├──entryability/
│  │  └──EntryAbility.ets                 // 程序入口类
│  ├──entryformability/
│  │  └──EntryFormAbility.ets             // 卡片生命周期类
│  ├──pages/
│  │  └──Index.ets                        // 首页
│  └──widget/
│     ├──pages/
│     │  └──WidgetCard.ets                // 卡片页面
│     ├──view/
│     │  └──CardListComponent.ets
│     └──viewmodel/
│        └──CardListParameter.ets
└──entry/src/main/resources/              // 应用静态资源目录

3.2 Router事件刷新

Router事件刷新通过应用路由切换触发卡片更新，当用户从卡片进入应用再返回桌面时，卡片信息会自动刷新。

实现原理：

在EntryAbility的生命周期回调中触发更新方法
使用formProvider的updateForm方法将内容更新到指定卡片

核心代码：

// EntryAbility.ets
onWindowStageCreate(windowStage: Window.WindowStage): void {// 初始化代码...// 监听应用生命周期，在应用返回后台时触发卡片更新this.updateFormData();
}private updateFormData(): void {const formProvider = formBindingData.createFormBindingData(formData);formProvider.updateForm(formId, formProvider).then(() => {console.info('FormProvider updateForm success');}).catch((err) => {console.error('FormProvider updateForm failed: ' + err);});
}

3.3 Call事件刷新

Call事件刷新提供了更实时的更新机制，通过在卡片添加时建立通信连接来实现即时更新。

实现原理：

在EntryFormAbility的onAddForm中更新卡片信息
触发卡片UI的onFormTimeChange方法
通过postCardAction方法携带的updateCardInfo信息触发EntryAbility中的callee监听

核心代码：

// EntryFormAbility.ets
onAddForm(want: Want): formBindingData.FormBindingData {// 创建卡片数据...let formData: formBindingData.FormBindingData = {};// 设置定时更新或即时更新this.scheduleUpdateForm(formId);return formData;
}// WidgetCard.ets
onFormTimeChange(): void {// 触发Call事件更新this.postCardAction({'action': 'updateCardInfo','params': {'cardInfo': this.getUpdatedCardInfo()}});
}

3.4 Message事件刷新

Message事件刷新适用于用户交互触发的更新，通过卡片内部事件直接触发刷新流程。

实现原理：

在EntryFormAbility的onFormEvent回调中进行刷新处理
直接调用updateForm方法更新卡片内容

配置权限：

{"name": "ohos.permission.KEEP_BACKGROUND_RUNNING"
}

call事件需要提供方应用具备后台运行权限。

3.5 定点定时刷新

除了事件驱动更新外，ArkTS卡片还支持基于时间的自动刷新机制。

定点刷新：
在form_config.json中配置scheduledUpdateTime字段，卡片即可在指定时间自动刷新。

{"scheduledUpdateTime": "09:00","updateDuration": 1
}

定时刷新：
通过配置updateDuration字段（单位分钟），设置卡片定时更新的时间间隔。

重要提示：如果同时配置了定时刷新和定点刷新，定点刷新会被忽略，因此需要根据业务需求选择合适的方式。

4. 完整开发流程

4.1 环境准备

支持设备：华为手机
HarmonyOS系统：HarmonyOS NEXT Developer Beta5及以上
DevEco Studio版本：DevEco Studio NEXT Developer Beta5及以上
HarmonyOS SDK版本：HarmonyOS NEXT Developer Beta5 SDK及以上

4.2 卡片创建步骤

定义卡片布局：在widget/pages/WidgetCard.ets中创建卡片UI布局
配置卡片信息：在src/main/resources/base/profile/form_config.json中配置卡片属性：

{"name": "WidgetCard","description": "示例卡片","src": "./widget/pages/WidgetCard","window": {"designWidth": 720,"autoDesignWidth": true},"colorMode": "auto","isDefault": true,"updateEnabled": true,"scheduledUpdateTime": "10:00","updateDuration": 0,"defaultDimension": "2*2","supportDimensions": ["2*2", "2*4"]
}