普通卡片如何发起互动区域
参考标题：
普通卡片自己不能直接展开互动区域。它要先发消息给 EntryFormAbility，再由 EntryFormAbility 调用 formProvider.requestOverflow()。
这篇讲的就是这条消息怎么发。
效果图
这篇开始进入“点一下普通卡片，怎么发起互动区域”。先看一个最典型的效果：普通卡片发出动作后，LiveForm 承接并展示展开反馈。
接下来重点看普通卡片怎么把这个动作发出去。
先看项目里的 ActionUtils
文件位置：
entry/src/main/ets/utils/ActionUtils.ets
这个工具类是卡片和应用通信的桥梁。项目里的普通卡片不会到处写 postCardAction，而是统一调用 ActionUtils。
这样做很重要。否则每张卡片都自己拼参数，后面维护会非常乱。
三类动作先分清
项目里定义了：
export enum FormCarAction {
CALL = 'call',
ROUTER = 'router',
MESSAGE = 'message'
}
小白可以这样理解：
- CALL：调用应用能力，比如播放音乐、收藏歌曲、开始运动。
- ROUTER：跳转到应用页面，比如 MusicPage、DeliveryPage。
- MESSAGE：发消息给 EntryFormAbility，比如请求展开互动区。
拉起 LiveForm 用的是 MESSAGE。
requestOverFlow 的代码
项目里的封装是：
public requestOverFlow(component: object, widthRatio: number, heightRatio: number, duration: number): void {
postCardAction(component, {
action: FormCarAction.MESSAGE,
abilityName: ENTRY_FORM_ABILITY,
params: {
message: 'requestOverflow',
widthRatio: widthRatio,
heightRatio: heightRatio,
duration: duration
}
});
}
逐个参数看。
component 一般传 this。它代表当前卡片组件上下文。
widthRatio 是互动区域宽度比例，比如快递卡片用 1.45。
heightRatio 是互动区域高度比例。
duration 是互动区域持续时间，项目里统一用 LIVE_CARD_DURATION。
abilityName 为什么是 EntryFormAbility
这里写的是：
abilityName: ENTRY_FORM_ABILITY
常量定义在 FormCardConstant.ets：
export const ENTRY_FORM_ABILITY = 'EntryFormAbility';
因为 requestOverflow 必须由 FormExtensionAbility 处理，不是普通 EntryAbility 处理。
这点很容易错。播放音乐用 ENTRY_ABILITY，展开互动区用 ENTRY_FORM_ABILITY。
普通卡片怎么调用
以快递卡片为例：
.onClick(() => {
ActionUtils.requestOverFlow(
this,
LiveCardScale.DELIVERY_WIDTH,
LiveCardScale.DELIVERY_HEIGHT,
LIVE_CARD_DURATION
);
});
以音乐卡片为例，播放时还会带触发动作：
ActionUtils.requestOverFlowWithAction(
this,
LiveCardScale.MUSIC_WIDTH,
LiveCardScale.MUSIC_HEIGHT,
LIVE_CARD_DURATION,
'PLAY',
this.songId
);
音乐为什么要多传 triggerAction 和 songId？
因为 LiveForm 需要知道这次是播放、上一首还是下一首，才能选择不同动画。
EntryFormAbility 怎么接收
EntryFormAbility.ets 里有：
async onFormEvent(formId: string, message: string): Promise<void> {
const params: Record<string, Object> = JSON.parse(message);
let shortMessage: string = params.message as string;
if (shortMessage === 'requestOverflow') {
let widthRatio: number = params.widthRatio as number;
let heightRatio: number = params.heightRatio as number;
let duration: number = params.duration as number;
this.requestOverflow(formId, widthRatio, heightRatio, duration);
return;
}
}
这就是普通卡片消息的接收点。
postCardAction 发送的 params 会变成 message 字符串，onFormEvent() 里再 JSON.parse() 解析回来。
小白练习：写一个最小触发按钮
你可以在任意普通卡片页面里写：
Button('展开互动区')
.onClick(() => {
ActionUtils.requestOverFlow(this, 1.3, 1.3, 3000);
})
前提是这张普通卡片的 form_config.json 里已经配置了：
"sceneAnimationParams": {
"abilityName": "你的LiveFormAbility"
}
否则按钮点了也不知道该展开哪个 LiveForm。
排查顺序
点击普通卡片没反应时，按这个顺序查：
写在最后
普通卡片不要直接操心 LiveForm 怎么加载。它只要把“我要展开互动区”这个意图发出去就行。
记住这条规则：普通卡片发 MESSAGE，EntryFormAbility 负责真正的 requestOverflow。
