1. 卡片交互机制
1.1 事件类型
-
router事件:跳转到应用指定页面
phpFormLink({ action: 'router', abilityName: 'EntryAbility', params: { 'target': 'detail' } }) { // 卡片内容 }
-
message事件:发送消息不跳转
kotlinpostCardAction(this, { 'action': 'message', 'params': { 'cmd': 'refresh' } });
1.2 交互原则
- 热区设计:单个卡片建议不超过3个可点击区域
- 防冲突:避免使用长按(系统保留用于卡片管理)
- 反馈明确:点击后应有视觉反馈(如颜色变化)
2. 数据更新机制
2.1 刷新类型
类型 | 触发方式 | 应用场景 |
---|---|---|
定时刷新 | updateDuration配置 | 股票行情(每30分钟) |
定点刷新 | scheduledUpdateTime配置 | 天气卡片(每天08:00) |
主动刷新 | FormProvider.updateForm() | 用户交互触发(如点赞) |
代理刷新 | 数据订阅机制 | 低功耗场景(如锁屏卡片) |
2.2 FormProvider核心API
typescript
import formProvider from '@ohos.app.form.formProvider';
// 更新卡片数据
formProvider.updateForm(formId, formBindingData.createFormBindingData(newData))
.then(() => console.log('Update success'))
.catch(error => console.error(`Update failed: ${error.code}`));
// 设置下次刷新时间
formProvider.setFormNextRefreshTime(formId, 10); // 10分钟后刷新
3. 数据同步策略
3.1 进程间通信
- 应用主进程与卡片进程通过LocalStorage共享数据
- 使用数据库持久化存储卡片状态(如SQLite)
3.2 多实例管理
当添加多个相同卡片实例时:
javascript
// 在onAddForm中区分实例
onAddForm(want: Want) {
const instanceId = want.parameters[formInfo.FormParam.IDENTITY_KEY];
// 为不同实例存储独立数据
}
4. 实时性优化
- 批量更新:合并短时间内多次updateForm调用
- 增量更新:仅传输变化字段(如仅更新温度数值)
- 缓存策略:使用FormProvider.setFormNextRefreshTime减少刷新次数
5. 典型场景实现
5.1 天气卡片定时刷新
json
// form_config.json
{
"updateEnabled": true,
"scheduledUpdateTime": "08:00",
"updateDuration": 4 // 每2小时刷新(4*30分钟)
}
5.2 音乐卡片播放状态同步
typescript
// 应用侧更新卡片播放状态
updatePlayStatus(isPlaying: boolean) {
const formData = { isPlaying, songName: currentSong.name };
formProvider.updateForm(formId, formBindingData.createFormBindingData(formData));
}
5.3 新闻卡片下拉刷新
csharp
// 卡片页面添加刷新按钮事件
async refreshNews() {
this.isRefreshing = true;
await fetchLatestNews(); // 获取最新数据
formProvider.updateForm(this.formId, newData);
this.isRefreshing = false;
}
6. 常见问题处理
- 数据不一致:在onCastToNormal中持久化临时卡片数据
- 刷新失败:检查formId有效性(使用getFormsInfo()验证)
- 性能问题:避免在onUpdate中执行耗时操作(建议<100ms)