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

文章目录效果图状态切换反馈音乐卡片播放与切歌反馈快递卡片传感器驱动反馈你先打开这几个文件第一步主页负责添加卡片第二步module.json5 注册能力第三步form_config.json 把两边绑起来第四步EntryFormAbility 管生命周期第五步普通卡片发起互动区第六步requestOverflow 真正打开互动区小白排查顺序写在最后如果你第一次看这个项目千万别一上来就改MusicLiveCard.ets或DeliveryLiveCard.ets。互动卡片不是一个单页面功能它更像一条接力赛主页添加卡片普通卡片显示在桌面普通卡片发消息EntryFormAbility接消息系统再拉起 LiveForm。这篇先不追动画细节只把主链路讲透。小白把这一篇看明白后面的音乐、运动、快递、睡眠四类卡片就都能顺着读下去了。效果图先看一眼最终效果。这里不把所有动效硬塞成一坨而是按场景拆开看音乐、运动、快递、睡眠各有自己的互动重点后面的文章也会按这个顺序逐个拆。状态切换反馈音乐卡片播放与切歌反馈快递卡片传感器驱动反馈效果是不是很漂亮接下来先不急着写动画我们先把这条互动卡片主链路跑明白。你先打开这几个文件建议按这个顺序看entry/src/main/ets/pages/Index.etsentry/src/main/module.json5entry/src/main/resources/base/profile/form_config.jsonentry/src/main/ets/entryformability/EntryFormAbility.etsentry/src/main/ets/utils/ActionUtils.etsentry/src/main/ets/livecardability/MusicLiveCardAbility.etsentry/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管”。小白重点看parametersform_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{letformIdwant.parameters?.[ohos.extra.param.key.form_identity]asstring;letformNamewant.parameters?.[ohos.extra.param.key.form_name]asstring;letformDimensionwant.parameters?.[ohos.extra.param.key.form_dimension]asstring;letformInfonewFormInfo();formInfo.formIdformId;formInfo.formNameformName;formInfo.formDimensionformDimension;FormUtils.insertFormData(this.context,formInfo);returnformBindingData.createFormBindingData({formId});}这段代码做了三件事从系统want里拿到卡片 ID、名称、尺寸。通过FormUtils.insertFormData()保存到数据库。返回初始化数据给普通卡片。为什么要保存formId因为后面调用formProvider.updateForm(formId, data)时必须知道更新哪一张卡片。第五步普通卡片发起互动区以音乐卡片为例用户点击播放时会调用ActionUtils.requestOverFlowWithAction(this,LiveCardScale.MUSIC_WIDTH,LiveCardScale.MUSIC_HEIGHT,LIVE_CARD_DURATION,PLAY,this.songId);ActionUtils里最终会发postCardActionpostCardAction(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):Promisevoid{letformRect:formInfo.RectawaitformProvider.getFormRect(formId);letcardWidthformRect.width*widthRatio;letcardHeightformRect.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。按这个顺序查module.json5里有没有EntryFormAbility类型是不是form。module.json5里有没有对应 LiveForm类型是不是liveForm。form_config.json的sceneAnimationParams.abilityName是否和 LiveForm 名称一致。普通卡片点击后ActionUtils.requestOverFlow()有没有执行。EntryFormAbility.onFormEvent()有没有收到requestOverflow。formProvider.requestOverflow()有没有报错。写在最后互动卡片开发最怕“只看一个文件”。这个项目是多文件协作配置、普通卡片、Ability、工具类、LiveForm 页面缺一不可。记住这条线添加卡片 - 保存 formId - 普通卡片发消息 - FormAbility 请求溢出 - LiveForm 加载页面后面所有教程都是在这条主链路上继续加业务。