文章目录效果图文件在哪里先看音乐卡片配置name卡片的身份证src普通卡片页面路径isDynamic动态卡片能力defaultDimension 和 supportDimensions尺寸必须对上sceneAnimationParams互动卡片的关键快递卡片多了 metadata新增一张卡片怎么配排查清单写在最后form_config.json是小白最容易忽略的文件。你写了漂亮的 ArkUI 页面结果系统根本找不到它大概率就是这里没配对。这篇就专门讲它。目标很简单让你知道每个字段是干什么的改卡片时应该改哪里出了问题先查哪里。效果图form_config.json决定普通卡片和 LiveForm 怎么配对。配置对了点击普通卡片后系统才能拉起对应的展开效果。这篇就把“为什么配置能牵起普通卡片和 LiveForm”讲明白。文件在哪里项目里的配置文件在entry/src/main/resources/base/profile/form_config.json里面注册了四张普通卡片SleepCardDeliveryCardExerciseCardMusicCard它们分别对应睡眠、快递、运动、音乐四个互动卡片场景。先看音乐卡片配置{name:MusicCard,displayName:$string:MusicCard,description:$string:MusicCardDes,src:./ets/widget/pages/MusicCard.ets,uiSyntax:arkts,window:{designWidth:720,autoDesignWidth:true},colorMode:auto,isDynamic:true,isDefault:false,updateEnabled:false,scheduledUpdateTime:10:30,updateDuration:1,defaultDimension:2*4,supportDimensions:[2*4],sceneAnimationParams:{abilityName:MusicLiveCardAbility}}字段多但小白先抓住 5 个核心字段就够了namesrcisDynamicdefaultDimensionsceneAnimationParams.abilityNamename卡片的身份证name:MusicCardname是卡片名。主页添加卡片时传的form_name必须和这里一致。比如Index.ets里最终会传ohos.extra.param.key.form_name:config.cardName如果config.cardName是MusicCard那form_config.json里就必须有MusicCard。src普通卡片页面路径src:./ets/widget/pages/MusicCard.ets这个字段指向普通桌面卡片页面。注意不是 LiveForm 页面。也就是说音乐普通卡片是entry/src/main/ets/widget/pages/MusicCard.ets音乐互动页面是entry/src/main/ets/livecardability/pages/MusicLiveCard.etssrc写前者不写后者。isDynamic动态卡片能力isDynamic:true当前项目里四张卡片都设置为动态卡片。这样应用侧才能通过formProvider.updateForm()给桌面卡片下发数据。比如音乐播放状态、歌曲标题、收藏状态都是动态更新的。如果你做的是纯静态展示卡片可以不需要复杂刷新。但这个项目是互动卡片建议保持true。defaultDimension 和 supportDimensions尺寸必须对上音乐卡片是defaultDimension:2*4,supportDimensions:[2*4]快递卡片是defaultDimension:2*2,supportDimensions:[2*2]如果主页添加时传了2*4但这里的supportDimensions只有2*2就会出问题。小白改尺寸时记得同时改这两处form_config.json主页卡片配置CARD_ITEM_CONFIGSsceneAnimationParams互动卡片的关键这是互动卡片最重要的字段sceneAnimationParams:{abilityName:MusicLiveCardAbility}它告诉系统这张普通卡片展开互动区时应该找哪个 LiveForm Ability。MusicLiveCardAbility必须在module.json5里注册{ name: MusicLiveCardAbility, srcEntry: ./ets/livecardability/MusicLiveCardAbility.ets, type: liveForm }两个名字必须完全一致。快递卡片多了 metadata快递卡片配置里有metadata:[{name:isSupportShake,value:true}]这表示快递卡片支持摇动/传感器类交互。因为快递 LiveForm 里会用陀螺仪所以这里加了额外元信息。小白可以先不用深究 metadata但要知道某些卡片能力不是只靠页面代码还会在配置里声明。新增一张卡片怎么配假设你要新增一个天气卡片最小配置可以这样写{name:WeatherCard,displayName:$string:WeatherCard,description:$string:WeatherCardDes,src:./ets/widget/pages/WeatherCard.ets,uiSyntax:arkts,window:{designWidth:720,autoDesignWidth:true},colorMode:auto,isDynamic:true,isDefault:false,updateEnabled:false,defaultDimension:2*2,supportDimensions:[2*2],sceneAnimationParams:{abilityName:WeatherLiveCardAbility}}然后你还要去module.json5注册{ name: WeatherLiveCardAbility, srcEntry: ./ets/livecardability/WeatherLiveCardAbility.ets, type: liveForm }只改form_config.json不够。普通卡片和 LiveForm Ability 要一起补齐。排查清单互动卡片打不开时先查这几项name是否和添加时传入的form_name一致。src文件是否真实存在。defaultDimension是否在supportDimensions里。sceneAnimationParams.abilityName是否存在。module.json5是否注册了同名liveForm。type是否写成liveForm。写在最后form_config.json是普通卡片和 LiveForm 的牵线人。普通卡片能不能被系统识别、能不能展开互动区很多时候就卡在这里。小白记住一句话src找普通卡片abilityName找 LiveForm。