鸿蒙静态卡片和动态卡片在食界探味项目里的分工

适合谁看

正在设计多张鸿蒙卡片的人
不确定什么卡片该动态、什么该静态的人
想控制鸿蒙卡片维护成本的人

问题背景

很多人一开始做鸿蒙卡片时，会默认：既然是卡片，那就都做成动态。

但动态卡片意味着：

需要数据更新策略
需要更复杂的生命周期管理
需要处理内容源稳定性
需要定时更新配置

并不是每一种入口都值得付出这个成本。

项目中的真实场景

食界探味当前有 3 张鸿蒙卡片：

鸿蒙卡片	类型	内容	更新策略
今日探味 (DailyRecommendCard)	动态	每日推荐一道环球美食	每天 00:05 自动更新
搜索美食 (SearchCard)	静态	快速跳转搜索页	不更新
美食许愿箱 (WishBoxCard)	静态	快速跳转心愿单	不更新

在 DailyRecommendFormAbility.ets 里，通过 STATIC_CARD_NAMES 实现分流：

复制代码

const STATIC_CARD_NAMES: Set<string> = new Set([
  'SearchCard',
  'AiAssistantCard',
  'WishBoxCard',
]);

export default class DailyRecommendFormAbility extends FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData {
    const formName = want.parameters?.['ohos.extra.param.key.form_name'] as string;

    // 静态卡片 → 返回空数据
    if (STATIC_CARD_NAMES.has(formName)) {
      return formBindingData.createFormBindingData({});
    }

    // 动态卡片 → 返回推荐数据
    const item = getRecommendOfToday();
    return formBindingData.createFormBindingData({
      dishName: item.name,
      dishRegion: item.region,
      dishImage: resolveImageResName(item.imageResName),
      dishId: item.id,
      dishHighlight: item.highlight,
      dishSummary: item.summary,
    });
  }
}

核心实现

一、鸿蒙静态卡片适合做什么

更适合静态鸿蒙卡片的，是明确入口型能力：

静态卡片	用途	为什么静态
SearchCard	打开搜索	功能固定，不需要内容更新
AiAssistantCard	进入 AI 助手	功能固定，不需要内容更新
WishBoxCard	打开心愿单	功能固定，不需要内容更新

这类鸿蒙卡片的价值来自"更快进入"，不是"展示动态内容"。

静态鸿蒙卡片的特点：

内容固定不变
不需要数据更新策略
生命周期简单（只需要 onAddForm）
维护成本低

二、鸿蒙动态卡片适合做什么

更适合动态鸿蒙卡片的，是内容型入口：

动态卡片	用途	为什么动态
DailyRecommendCard	今日推荐	内容每天变化
每日一题	每天一道题	内容每天变化
今日热榜	每天热榜	内容每天变化

它的价值来自"内容每天变"，而不是"入口在哪里"。

动态鸿蒙卡片的特点：

内容定期更新
需要数据更新策略
生命周期复杂（onAddForm + onUpdateForm）
需要处理内容源稳定性
需要配置 updateEnabled + scheduledUpdateTime

三、为什么要分开------三个好处

好处 1：动态更新逻辑只服务必要卡片

如果所有鸿蒙卡片都做成动态，每张卡片都需要：

数据源
更新算法
容错处理

但静态卡片根本不需要这些。分开后，只有 DailyRecommendCard 需要 getRecommendOfToday() 和 resolveImageResName()。

好处 2：静态入口卡片更稳定

静态鸿蒙卡片没有数据更新，所以：

不会因为数据源出错而显示异常
不会因为定时更新失败而显示空白
不会因为内容过期而误导用户

好处 3：后期内容和入口的迭代成本不会绑死在一起

复制代码

所有卡片都做动态时：
  改搜索入口 → 可能影响数据更新逻辑
  改推荐算法 → 可能影响搜索卡片

分开后：
  改搜索入口 → 只改 SearchCard
  改推荐算法 → 只改 DailyRecommendCard

四、在同一个 FormAbility 中实现分流

食界探味的设计很巧妙：3 张鸿蒙卡片共享同一个 DailyRecommendFormAbility，通过 STATIC_CARD_NAMES 分流。

复制代码

DailyRecommendFormAbility
  │
  ├─ onAddForm(want)
  │   │
  │   ├─ formName ∈ STATIC_CARD_NAMES？
  │   │   ├─ 是 → 返回空数据（静态卡片）
  │   │   └─ 否 → getRecommendOfToday()（动态卡片）
  │   │
  │   ▼
  │   formBindingData.createFormBindingData({...})
  │
  ├─ onUpdateForm(formId)
  │   │
  │   └─ 只有动态卡片会触发
  │       → getRecommendOfToday()
  │       → formProvider.updateForm(formId, data)
  │
  └─ onRemoveForm(formId)
      └─ 日志记录

这种设计的优势：

一个 FormAbility 管理所有卡片，不需要为每张卡片创建单独的 Ability
静态卡片的 onUpdateForm 不会被触发（因为配置了 updateEnabled: false）
静态卡片的 onAddForm 返回空数据，由卡片 UI 自己显示默认内容

五、配置层的分工

在 daily_recommend_form_config.json 中，静态和动态卡片的配置差异：

配置项	动态卡片 (DailyRecommendCard)	静态卡片 (SearchCard)
`updateEnabled`	`true`	`false`
`scheduledUpdateTime`	`00:05`	无
`isDefault`	`true`	`false`

这说明鸿蒙系统层面也区分了静态和动态卡片：

动态卡片：系统会在指定时间触发 onUpdateForm()
静态卡片：系统只在用户添加时触发 onAddForm()，之后不再更新

六、卡片 UI 层的分工

动态鸿蒙卡片的 UI 需要处理数据绑定：

复制代码

// DailyRecommendCard.ets
@LocalStorageProp('dishName') dishName: string = '环球美食';
@LocalStorageProp('dishRegion') dishRegion: string = '世界';
@LocalStorageProp('dishImage') dishImage: string = 'dish_fallback';
// ... 数据来自 FormAbility

静态鸿蒙卡片的 UI 可以完全硬编码：

复制代码

// SearchCard.ets（示意）
@Component
struct SearchCard {
  build() {
    Row() {
      Image($r('app.media.icon_search')).width(48).height(48)
      Column() {
        Text('搜索美食').fontSize(16).fontWeight(FontWeight.Bold)
        Text('搜索全球美食与食材').fontSize(12)
      }
    }
    .onClick(() => {
      postCardAction(this, {
        action: 'router',
        abilityName: 'EntryAbility',
        params: { pageId: 'search' }
      });
    })
  }
}

静态卡片不需要 @LocalStorageProp，因为数据是固定的。

七、点击跳转的分工

两种鸿蒙卡片的点击跳转方式一致（都用 postCardAction），但跳转目标不同：

鸿蒙卡片	点击跳转	参数
DailyRecommendCard	dish_detail / explore	pageId + dishId
SearchCard	/search	pageId='search'
WishBoxCard	/wish-box	pageId='wish_box'

动态卡片需要传 dishId 参数（因为内容每天变），静态卡片只需要传 pageId。

关键代码位置

文件	作用
`app/ohos/entry/src/main/ets/formability/DailyRecommendFormAbility.ets`	鸿蒙卡片生命周期（含分流逻辑）
`app/ohos/entry/src/main/ets/formability/RecommendData.ets`	动态卡片数据源
`app/ohos/entry/src/main/resources/base/profile/daily_recommend_form_config.json`	卡片配置（区分静态/动态）

静态 vs 动态鸿蒙卡片对比表

维度	静态鸿蒙卡片	动态鸿蒙卡片
内容	固定不变	定期更新
数据源	无	getRecommendOfToday()
updateEnabled	false	true
scheduledUpdateTime	无	00:05
onAddForm	返回空数据	返回推荐数据
onUpdateForm	不触发	定时触发
UI 数据绑定	不需要	需要 @LocalStorageProp
点击参数	只需 pageId	pageId + 内容参数
维护成本	低	中
适用场景	功能入口	内容推荐

常见坑

把所有鸿蒙卡片都做成动态 --- 静态入口卡片不需要数据更新
动态卡片没有稳定内容来源 --- 数据源出错时需要兜底
静态鸿蒙卡片也强行维护更新逻辑 --- 浪费资源，增加复杂度
卡片分工不清，导致点击后入口语义混乱 --- 静态是功能入口，动态是内容入口
静态卡片的 onAddForm 返回了数据 --- 应该返回空数据，由 UI 显示默认内容
动态卡片没有配置 updateEnabled --- 鸿蒙系统不会触发定时更新

可复用模板

鸿蒙 FormAbility 分流模板

复制代码

const STATIC_CARD_NAMES: Set<string> = new Set(['SearchCard', 'WishBoxCard']);

export default class MyFormAbility extends FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData {
    const formName = want.parameters?.['ohos.extra.param.key.form_name'] as string;

    if (STATIC_CARD_NAMES.has(formName)) {
      return formBindingData.createFormBindingData({});  // 静态卡片
    }

    const item = getData();  // 动态卡片
    return formBindingData.createFormBindingData({
      title: item.title,
      content: item.content,
    });
  }

  onUpdateForm(formId: string): void {
    // 只有动态卡片会触发
    const item = getData();
    formProvider.updateForm(formId, formBindingData.createFormBindingData({
      title: item.title,
      content: item.content,
    }));
  }
}

配置模板（区分静态/动态）

复制代码

{
  "forms": [
    {
      "name": "DynamicCard",
      "updateEnabled": true,
      "scheduledUpdateTime": "00:05",
      "isDefault": true
    },
    {
      "name": "StaticCard",
      "updateEnabled": false,
      "isDefault": false
    }
  ]
}

卡片分工决策模板

复制代码

判断鸿蒙卡片类型：
  内容是否每天变化？ → 是 → 动态卡片
  是否只是功能入口？ → 是 → 静态卡片
  需要数据更新策略？ → 是 → 动态卡片
  内容固定不变？     → 是 → 静态卡片

本篇总结

鸿蒙静态卡片适合做入口，动态卡片适合做内容。食界探味当前的实现展示了如何在同一个 FormAbility 中通过 STATIC_CARD_NAMES 实现分流：

静态鸿蒙卡片 --- SearchCard、WishBoxCard，功能固定，不需要数据更新
动态鸿蒙卡片 --- DailyRecommendCard，内容每天变化，需要定时更新

这层分工能明显降低鸿蒙卡片系统复杂度：动态更新逻辑只服务必要卡片，静态入口卡片更稳定，后期迭代成本不会绑死在一起。食界探味当前的实现就是一个很实用的参考。