互动卡片实战：摸鱼鸭的“破框动效“是怎么做出来的

互动卡片实战摸鱼鸭的破框动效是怎么做出来的把一张只能看、不能摸的桌面卡片变成会顶破屏幕边框、撒花庆祝的小鸭子。本文记录我在 HarmonyOS「摸鱼鸭」项目里接入 Live Form互动卡片的全过程从怎么让卡片活起来到踩过的坑和对应的解法。读完你不仅能照着做还能少走很多弯路。一、先讲个痛点你的卡片是不是也死的最初我的「摸鱼鸭」桌面卡片长这样一张 2×2 的小卡上面写着周末倒计时 2 天配一只呆萌的鸭子。能用但很无聊。它不会动你戳它它没反应它永远缩在那个方方正正的圆角矩形里像被框住的囚徒。我想做的效果是用户一点卡片上的鸭子鸭子嘭地从卡片里钻出来顶破边框冲到屏幕上方还撒一把彩花1 秒多之后又缩回去。华为把这种效果叫做破框动效技术载体就是Live Form互动卡片。这篇文章要解决的就是怎么让这张卡片活过来。二、什么是互动卡片Live Form普通的桌面卡片FormExtensionAbility是静态渲染——系统把你的 UI 截图成一张图贴在桌面上你之后只能通过updateForm换内容没法做动画、也没法真正响应手势。互动卡片Live Form不一样它能在用户触发时临时加载一个真正的 ArkUI 页面这段时间里卡片可以播放动画、响应点击。触发方式有两种手势触发shake系统在module.json5里声明sceneAnimationParams由桌面如摇一摇、长按等系统手势自动唤起。卡片内主动触发点击卡片里的 UI 通过postCardAction发一条消息给FormExtensionAbility由它去调用requestOverflow申请破框。破框的本质是系统在不放大卡片本身的前提下临时在卡片周围多给你一圈溢出区overflow area让动画内容可以画到卡片边界之外——看起来就像内容钻出了卡片。三、整体链路一次点击是怎么变成破框动画的用一句话串起来用户点鸭子 → 卡片发MESSAGE→FormExtensionAbility.onFormEvent收消息 → 调requestOverflow申请溢出区 → 系统创建LiveFormExtensionAbility→ 加载DuckLiveCard页面 → 鸭子顶出边框 撒花 → 主动cancelOverflow收起。代码层面拆分三条角色角色文件职责普通卡片 UIwidgets/SmallCard2x2.ets展示文案 鸭子热区点击发消息卡片能力formextensions/WeekendFormExtension.ets收消息申请破框互动页面liveform/DuckLiveFormAbility.etsliveform/pages/DuckLiveCard.ets破框后加载的动画 UI四、手把手实现1. 注册 LiveForm 能力在module.json5的extensionAbilities里加一条类型填liveForm{name:DuckLiveFormAbility,srcEntry:./ets/liveform/DuckLiveFormAbility.ets,type:liveForm,exported:false}2. 给普通卡片声明手势触发在卡片的form_profile.jsonresources/base/profile/form_weekend.json里加上sceneAnimationParams把破框页面指过去sceneAnimationParams:{abilityName:DuckLiveFormAbility,triggerTypes:[shake]}⚠️ 这个配置是在卡片被添加到桌面那一刻就被系统读走了。改完之后必须把卡片从桌面删掉重新添加否则新配置不生效。3. 在卡片里点鸭子发消息鸭子是一个Builder用responseRegion把热区放大到 66px比实际图大一圈桌面才好点点击后postCardAction发一条messageBuilderDuckHotspot(size:number){Image(DuckImageUtil.getImageResource(this.duckState)).width(size).height(size).responseRegion({x:-14,y:-14,width:size28,height:size28}).hitTestBehavior(HitTestMode.Block)// 阻断冒泡避免同时跳转 App.onClick(()this.requestLiveForm())}privaterequestLiveForm():void{postCardAction(this,{action:message,params:{message:requestOverflow,widthRatio:1.45,heightRatio:1.45,duration:2200}})}4. FormExtension 收消息并申请破框onFormEvent(formId:string,message:string):Promisevoid{constparamsLiveFormOverflowUtil.parseMessage(message)if(params[message]requestOverflow){returnthis.activateLiveForm(formId,params)// 申请破框}returnthis.computeAndUpdate(formId)// 其他消息走普通刷新}privateasyncactivateLiveForm(formId:string,params:Recordstring,Object):Promisevoid{constokawaitLiveFormOverflowUtil.requestOverflow(formId,LiveFormOverflowUtil.readNumber(params,widthRatio,1.45),LiveFormOverflowUtil.readNumber(params,heightRatio,1.45),LiveFormOverflowUtil.readNumber(params,duration,2200))this.saveLiveFormData()// 数据落盘不 await避免拖慢响应if(!ok)awaitthis.computeAndUpdate(formId)// 不支持时降级为刷新}注意一个性能细节先申请破框用户立刻看到反应再把数据落盘而且不await落盘。否则点下去要等几百毫秒才有动静用户会以为没点上。5. 互动页面鸭子顶出 撒花DuckLiveFormAbility.onLiveFormCreate里同步loadContent把卡片信息塞进 payload系统随后加载DuckLiveCardonLiveFormCreate(liveFormInfo:LiveFormInfo,session:UIExtensionContentSession):void{constpayloadgetDuckLiveFormPayload()payload.rectWidthliveFormInfo.rect.width payload.rectHeightliveFormInfo.rect.height// ... 写 formId / cardType / 文案 / 圆角 ...session.loadContent(liveform/pages/DuckLiveCard,newLocalStorage())}页面里鸭子居中后上移露出上边界撒花用ForEachCircle().fill()做Stack({alignContent:Alignment.Center}){Column(){/* 原卡片文案底板居中 */}.width(this.rectWidth).height(this.rectHeight).borderRadius(this.radius).linearGradient({angle:180,colors:[...]})Image(this.duckImage()).scale({x:this.duckScale,y:this.duckScale}).offset({y:this.duckOffsetY()})// 向上偏移顶部钻出ForEach(this.confettiList,(item)Circle({width:item.size,height:item.size}).fill(item.color).offset({x:item.dx*this.confettiProgress,y:item.dy*this.confettiProgress-this.rectHeight*0.15}))}动画跑完约 1.3s主动cancelOverflow把系统的破框请求锁提前释放掉下次点击才能更快响应this.dismissTimersetTimeout((){formProvider.cancelOverflow(this.formId).catch((){})},1600)五、踩坑实录重点来了下面这些都是我用真机 hdc shell hilog | grep MoyuyaLiveForm一条条日志磨出来的。坑 1破框申请直接报错code16501000现象点卡片没反应日志里requestOverflow failed code16501000系统侧还提示overflow duration is out of range:3500。原因formProvider.requestOverflow有硬上限。我一开始设的duration4000、ratio1.8全部超限。解决把参数全部clamp到安全区间并预留余量privatestaticreadonlyMAX_RATIO:number1.5// 比例上限privatestaticreadonlyMAX_DURATION:number3500// 时长上限时长申请 2200ms永远 ≤ 3500ms比例申请 1.45 倍≤ 1.5。坑 22×4 大卡片反而破框失败现象2×2 卡片能破框换成 2×4高 300px就报area out of range, scaleRatio:1.5, overflowWidthHalf:37.5。原因系统限制的不是比例而是单边绝对溢出量。2×2150px按 1.45 倍算单边溢出约 33px刚好过线但 2×4 高 300px1.45 倍算出来单边要溢出 67px被系统策略直接拒绝。解决先按比例算再按单边绝对溢出上限钳一次。实测单边最多约 37.5px我留余量取 36privatestaticreadonlyMAX_OVERFLOW_HALF:number36constareaWidthMath.min(rect.width*w,rect.width2*MAX_OVERFLOW_HALF)constareaHeightMath.min(rect.height*h,rect.height2*MAX_OVERFLOW_HALF)这样无论 2×2、2×4 还是 4×4都不会超限。坑 3点完卡片消失约 3 秒又出现现象点击触发破框后整张卡变成一片白背景白色16777215大约 3 秒后才恢复。排查日志显示loadContent success但DuckLiveCard的aboutToAppear根本没打印——页面没真正渲染出来露出了默认白色底。两个根因都修了(a)loadContent必须在onLiveFormCreate中同步调用。我最初把它包在async逻辑后面导致系统认为页面没准备好直接上白底。改成同步立即调用即可所有数据准备走同步 payload 写入不 await 外部 IO。(b) rect 坐标语义陷阱。我一度想用rect.left / rect.top做绝对定位结果不同系统版本下这两个值有时是相对偏移、有时是屏幕绝对坐标用错就把内容推出可见区看着就像卡片消失。正确思路溢出区一定是以卡片为中心放大的所以溢出区中心 卡片中心。于是不依赖rect.left/top的坐标系直接用Stack居中布局 向上偏移即可privateduckOffsetY():number{consthalfCardthis.rectHeight/2consthalfDuckthis.duckSize()/2constrevealMath.min(this.rectHeight*0.17,26)// 露出量钳到 26不超每边 36px 额度return-(halfCardreveal-halfDuck)}坑 4互动页面拿不到最新文案现象破框后鸭子旁边的文案是空的或者显示的是上一次的旧数据。原因互动卡片LiveFormExtensionAbility和FormExtensionAbility不在同一个进程。普通卡片的Preferences共享在互动进程里读不到。解决跨进程数据走文件。FormExtension在申请破框前不阻塞地把最新文案写入LiveFormDataStore文件存储互动页面在aboutToAppear里读取读不到就用默认值兜底cardType fish ? 摸鱼中勿扰 : 冲鸭周末在前方。页面同时用Entry({ useSharedStorage: true })提升存储兼容性。坑 5摇一摇没反应现象声明了triggerTypes: [shake]但摇手机不触发。原因手势触发不是走onFormEvent而是系统回调onUpdateForm并带上shake相关参数。我一开始只在onFormEvent里接消息自然接不到。解决在onUpdateForm里也识别 shakeonUpdateForm(formId:string,wantParams?:Recordstring,Object):Promisevoid{if(wantParams!undefinedLiveFormOverflowUtil.isShakeTrigger(wantParams)){returnthis.activateLiveForm(formId,{})}returnthis.computeAndUpdate(formId)}isShakeTrigger做宽松匹配——遍历参数值只要包含shake就认为是摇一摇触发兼容不同系统版本的参数命名。坑 6消息解析在老版本下崩现象某些系统版本下postCardAction传来的message不是合法 JSON直接JSON.parse会抛异常。解决parseMessage加兜底——解析失败就把原串当作message字段返回保证后续params[message] requestOverflow的判断仍能走通。六、给排查者的小抄看互动链路卡在哪一步过滤日志hdc shell hilog | grep MoyuyaLiveForm从onFormEvent→requestOverflow→onLiveFormCreate→DuckLiveCard aboutToAppear一路追。看系统为什么拒绝破框看com.ohos.sceneboard/FORM相关日志会直接打印out of range、area out of range这类原因。改了sceneAnimationParams或动画 UI 后删卡重加再测。七、收尾从一张死气沉沉的静态卡到会破框、会撒花的互动卡核心就三件事声明能力module.json5注册liveFormform_profile.json配sceneAnimationParams打通触发链卡片postCardAction→FormExtension调requestOverflow→ 系统加载互动页面守住系统边界时长 ≤ 3500ms、比例 ≤ 1.5、单边溢出 ≤ 36px且loadContent必须同步。剩下的就是给鸭子选一张可爱的 PNG、调一调撒花的角度让用户在摸鱼间隙会心一笑。