【共创季稿事节】HarmonyOS7 互动卡片开发实践：从 0 看懂 LiveCard 项目的主链路

如果你第一次看这个项目，千万别一上来就改MusicLiveCard.ets或DeliveryLiveCard.ets。互动卡片不是一个单页面功能，它更像一条接力赛：主页添加卡片，普通卡片显示在桌面，普通卡片发消息，EntryFormAbility接消息，系统再拉起 LiveForm。

这篇先不追动画细节，只把主链路讲透。小白把这一篇看明白，后面的音乐、运动、快递、睡眠四类卡片就都能顺着读下去了。

效果图

先看一眼最终效果。这里不把所有动效硬塞成一坨，而是按场景拆开看：音乐、运动、快递、睡眠各有自己的互动重点，后面的文章也会按这个顺序逐个拆。

状态切换反馈

音乐卡片：播放与切歌反馈

快递卡片：传感器驱动反馈

效果是不是很漂亮？接下来先不急着写动画，我们先把这条互动卡片主链路跑明白。

你先打开这几个文件

建议按这个顺序看：

• entry/src/main/ets/pages/Index.ets
• entry/src/main/module.json5
• entry/src/main/resources/base/profile/form_config.json
• entry/src/main/ets/entryformability/EntryFormAbility.ets
• entry/src/main/ets/utils/ActionUtils.ets
• entry/src/main/ets/livecardability/MusicLiveCardAbility.ets
• entry/src/main/ets/livecardability/pages/MusicLiveCard.ets

这几个文件正好对应一条完整链路。

Index.ets 添加卡片 -> form_config.json 找到普通卡片 -> EntryFormAbility.onAddForm 保存卡片实例 -> widget/pages/*.ets 显示桌面卡片 -> ActionUtils 发送点击动作 -> EntryFormAbility.onFormEvent 接收 requestOverflow -> formProvider.requestOverflow 请求展开互动区 -> LiveCardAbility.onLiveFormCreate 加载 LiveForm 页面

第一步：主页负责添加卡片

Index.ets里最关键的是openFormManager()。

constwant:Want={bundleName:BuildProfile.BUNDLE_NAME,abilityName:'EntryFormAbility',parameters:{'ohos.extra.param.key.form_dimension':config.cardDimension,'ohos.extra.param.key.form_name':config.cardName,'ohos.extra.param.key.module_name':MODULE_NAME,'ohos.extra.param.key.form_location':0}};formProvider.openFormManager(want);

这段代码的意思是：告诉系统“我要添加一张卡片，这张卡片归EntryFormAbility管”。

小白重点看parameters：

• form_dimension：卡片尺寸，比如2*2、2*4。
• form_name：卡片名，比如MusicCard、DeliveryCard。
• module_name：当前模块名，项目里是livecardsample。

如果这些参数传错，后面的EntryFormAbility.onAddForm()就拿不到正确卡片信息。

第二步：module.json5 注册能力

module.json5是能力注册表。互动卡片至少需要两类能力：

{ "name": "EntryFormAbility", "srcEntry": "./ets/entryformability/EntryFormAbility.ets", "type": "form" }

这个是普通卡片扩展入口。

{ "name": "MusicLiveCardAbility", "srcEntry": "./ets/livecardability/MusicLiveCardAbility.ets", "type": "liveForm" }

这个是互动区域入口。

注意type。普通卡片是form，互动卡片是liveForm。这两个写反，功能就跑不起来。

第三步：form_config.json 把两边绑起来

普通卡片和 LiveForm 的绑定关系在form_config.json：

{"name":"MusicCard","src":"./ets/widget/pages/MusicCard.ets","defaultDimension":"2*4","supportDimensions":["2*4"],"sceneAnimationParams":{"abilityName":"MusicLiveCardAbility"}}

这里最容易混的是src和abilityName。

src指普通桌面卡片页面。比如音乐卡片就是widget/pages/MusicCard.ets。

sceneAnimationParams.abilityName指 LiveForm 能力。比如音乐卡片展开后由MusicLiveCardAbility负责加载互动页。

第四步：EntryFormAbility 管生命周期

EntryFormAbility.ets是普通卡片的管家。

onAddForm(want:Want):formBindingData.FormBindingData{letformId=want.parameters?.['ohos.extra.param.key.form_identity']asstring;letformName=want.parameters?.['ohos.extra.param.key.form_name']asstring;letformDimension=want.parameters?.['ohos.extra.param.key.form_dimension']asstring;letformInfo=newFormInfo();formInfo.formId=formId;formInfo.formName=formName;formInfo.formDimension=formDimension;FormUtils.insertFormData(this.context,formInfo);returnformBindingData.createFormBindingData({formId});}

这段代码做了三件事：

1. 从系统want里拿到卡片 ID、名称、尺寸。
2. 通过FormUtils.insertFormData()保存到数据库。
3. 返回初始化数据给普通卡片。

为什么要保存formId？因为后面调用formProvider.updateForm(formId, data)时必须知道更新哪一张卡片。

第五步：普通卡片发起互动区

以音乐卡片为例，用户点击播放时会调用：

ActionUtils.requestOverFlowWithAction(this,LiveCardScale.MUSIC_WIDTH,LiveCardScale.MUSIC_HEIGHT,LIVE_CARD_DURATION,'PLAY',this.songId);

ActionUtils里最终会发postCardAction：

postCardAction(component,{action:FormCarAction.MESSAGE,abilityName:ENTRY_FORM_ABILITY,params:{message:'requestOverflow',widthRatio,heightRatio,duration}});

这里的MESSAGE会送到EntryFormAbility.onFormEvent()。

第六步：requestOverflow 真正打开互动区

EntryFormAbility收到requestOverflow后，会调用项目里的私有方法：

privateasyncrequestOverflow(formId:string,widthRatio:number,heightRatio:number,duration:number):Promise<void>{letformRect:formInfo.Rect=awaitformProvider.getFormRect(formId);letcardWidth=formRect.width*widthRatio;letcardHeight=formRect.height*heightRatio;letleftOffset=(formRect.width-cardWidth)/2;lettopOffset=(formRect.height-cardHeight)/2;formProvider.requestOverflow(formId,{area:{left:leftOffset,top:topOffset,width:cardWidth,height:cardHeight},duration});}

这就是互动卡片展开的核心。

它不是简单“打开一个页面”，而是在当前桌面卡片周围申请一个溢出区域。这个区域多大，由widthRatio和heightRatio决定。

小白排查顺序

如果互动区打不开，别乱改 UI。按这个顺序查：

1. module.json5里有没有EntryFormAbility，类型是不是form。
2. module.json5里有没有对应 LiveForm，类型是不是liveForm。
3. form_config.json的sceneAnimationParams.abilityName是否和 LiveForm 名称一致。
4. 普通卡片点击后，ActionUtils.requestOverFlow()有没有执行。
5. EntryFormAbility.onFormEvent()有没有收到requestOverflow。
6. formProvider.requestOverflow()有没有报错。

写在最后

互动卡片开发最怕“只看一个文件”。这个项目是多文件协作：配置、普通卡片、Ability、工具类、LiveForm 页面缺一不可。

记住这条线：

添加卡片 -> 保存 formId -> 普通卡片发消息 -> FormAbility 请求溢出 -> LiveForm 加载页面

后面所有教程，都是在这条主链路上继续加业务。