HarmonyOS 7.0 / API 26 互动卡片长按菜单桌面入口为什么要区分跳转、刷新和禁用态这篇只拆一个具体点互动卡片长按菜单的入口状态治理。版本边界先放前面下面的写法面向 HarmonyOS 7.0 / API 26。工程里如果还在混用旧 SDK、旧模拟器镜像或旧设备系统先不要直接照搬代码先把版本对齐。这个问题为什么值得单独拆互动卡片放到桌面以后入口不再只是一个普通按钮。用户可能点一下进入页面也可能长按查看操作也可能在网络差、账号失效、数据过期时看到不可用状态。如果跳转、刷新、禁用态都混在一个 onClick 里后面很容易出现点了没反应、重复刷新、状态恢复错误这类问题。这类问题的麻烦点是代码经常能编译页面第一次打开也像是正常的但一到折叠屏、多窗口、后台恢复、跨设备入口或审核机型上行为就开始不稳定。我的处理方式不是先改 UI而是先把能力边界、触发条件、失败原因和兜底方案拆开。先对齐官方能力边界参考点要确认什么落到代码里怎么处理HarmonyOS 7.0 互动卡片能力桌面入口、刷新和点击行为边界把卡片入口拆成 jump、refresh、disabled 三类状态ArkTS 状态建模状态枚举和原因字段让 UI 只消费 CardActionState不直接判断一堆布尔值应用体验与审核自检异常入口不能误导用户禁用态必须给出可见提示和日志原因这里要避免一个常见误区看到 7.0 新能力就直接在页面里调用。更稳的做法是先做一层能力判断判断通过再进入新能力分支判断失败就明确走兜底日志里也要能看出失败原因。两个容易复现的场景场景一卡片数据过期用户长按后先刷新再进入详情复现方式不要做得太复杂。先把页面打开到目标状态再连续触发两次能力入口。这个时候重点看三个点状态有没有丢、资源有没有重复申请、失败时有没有明确原因。场景二账号态失效长按菜单仍显示可用操作但点击后失败第二个场景更接近线上用户不会按开发者预设路径操作他会切后台、恢复、换方向、分屏、拖拽、锁屏再回来。只看单次点击问题很容易被遮住。拆法先决策再执行再兜底我会把实现拆成三层能力判断层只判断版本、设备形态、入口参数和依赖状态。执行层只负责调用具体 API不混入页面展示逻辑。兜底层能力不可用时给旧方案、提示或延迟重试不让页面进入半坏状态。这样拆的好处是后面升级 SDK 或换设备时不需要在每个页面里翻 if 判断。页面只拿一个明确结果能用、不能用、为什么不能用。Demo把能力判断收口到一个 guardtypeCardActionKindjump|refresh|disabled;typeCardBlockReasonnone|loginExpired|dataExpired|networkOffline;interfaceCardEntrySnapshot{loggedIn:boolean;online:boolean;dataVersion:number;latestVersion:number;}interfaceCardActionState{kind:CardActionKind;reason:CardBlockReason;label:string;nextRoute?:string;}classInteractiveCardActionResolver{resolve(snapshot:CardEntrySnapshot):CardActionState{if(!snapshot.online){return{kind:disabled,reason:networkOffline,label:网络不可用稍后再试};}if(!snapshot.loggedIn){return{kind:disabled,reason:loginExpired,label:登录状态失效请先打开应用};}if(snapshot.dataVersionsnapshot.latestVersion){return{kind:refresh,reason:dataExpired,label:数据已更新先刷新卡片};}return{kind:jump,reason:none,label:打开详情,nextRoute:pages/CardDetailPage};}}EntryComponentstruct CardMenuDemoPage{Stateprivatelabel:string等待判断;Stateprivatereason:stringnone;privateresolver:InteractiveCardActionResolvernewInteractiveCardActionResolver();privatehandleCard(snapshot:CardEntrySnapshot):void{conststatethis.resolver.resolve(snapshot);this.labelstate.label;this.reasonstate.reason;console.info([card-menu] kindstate.kind, reasonstate.reason, route(state.nextRoute??-));}build(){Column({space:12}){Text(this.label).fontSize(18).fontWeight(FontWeight.Medium)Text(reasonthis.reason).fontSize(13).fontColor(#667085)Button(模拟可跳转).onClick(()this.handleCard({loggedIn:true,online:true,dataVersion:3,latestVersion:3}))Button(模拟需刷新).onClick(()this.handleCard({loggedIn:true,online:true,dataVersion:2,latestVersion:3}))Button(模拟禁用态).onClick(()this.handleCard({loggedIn:false,online:true,dataVersion:3,latestVersion:3}))}.padding(20).width(100%)}}这个 Demo 只做一件事先判断能力条件再把结果交给页面。页面不直接关心 API 细节也不把版本判断散落在 build 里。后面要接真实页面时可以把 HarmonyFeatureGuard 放到公共模块里复用。异常日志应该长什么样[card-menu] kinddisabled, reasonloginExpired, route- [card-menu] kindrefresh, reasondataExpired, route- [card-menu] kindjump, reasonnone, routepages/CardDetailPage日志不要只打印“失败了”。至少要带上 scene、status、reason 和耗时。否则出了问题以后只能靠猜。验证矩阵场景输入条件预期结果关键日志数据版本一致loggedIntrue, onlinetrue, dataVersionlatestVersion直接跳转详情kindjump, reasonnone卡片数据过期dataVersion latestVersion先刷新卡片不直接跳转kindrefresh, reasondataExpired登录失效loggedInfalse禁用入口并提示打开应用kinddisabled, reasonloginExpired网络不可用onlinefalse禁用入口避免重复失败请求kinddisabled, reasonnetworkOffline跑完后应该看到的结果case jump_when_data_fresh - passed case refresh_when_data_expired - passed case disabled_when_login_expired - passed case disabled_when_network_offline - passed我会怎么选方案方案适合场景风险继续沿用旧写法旧页面、小范围兼容遇到 7.0 新能力边界时不好排查在页面内临时处理快速验证问题代码容易散后面不好复用抽成独立工具或组件多页面、多设备、多状态复用前期要把输入输出设计清楚我的选择是第三种。只要这个能力会被多个页面用到就不要把判断逻辑塞在页面里。页面只负责展示能力边界、异常兜底、版本判断放到独立函数或组件里。这样后面改 SDK、换设备、补兼容逻辑影响面会小很多。排查顺序先看入口状态是否被拆成枚举不要用多个布尔值互相覆盖。再看长按菜单和点击入口是否复用同一套 resolver避免两个入口判断不一致。再看失败原因是否写进日志不能只看到 disabled 却不知道为什么禁用。最后看刷新分支是否会重复触发数据未更新完成前不要继续跳转。可以怎么复用这个写法可以继续扩成一个小工具输入 featureName、apiLevel、deviceMode、entryState输出 passed / failed / fallback 和 reason。页面层只根据结果更新 UI。这样做虽然前期多写几行代码但后面接更多 HarmonyOS 7.0 能力时判断逻辑不会越写越散。最后总结互动卡片入口要先把状态分清楚能跳转就跳转数据过期先刷新条件不满足就禁用并给出原因。这样做不是为了多写几层代码而是为了让桌面入口在异常场景下也能解释清楚自己为什么不能继续。这类特性真正有价值的地方不是知道一个新名字而是知道它在什么场景该用、什么时候不该用、怎么复现问题、怎么把修复沉淀成可复用代码。后面再接复杂页面时先把这个小 Demo 跑通基本能避开一半低级返工。和旧写法的差别旧写法常见问题是把跳转、刷新、禁用都塞进点击回调里逻辑短期看着省事后面入口一多就开始互相打架。这里改成 resolver 后长按菜单、桌面点击、应用内入口都能共用同一套判断差异只留在展示层。
HarmonyOS 7.0 / API 26 互动卡片长按菜单：桌面入口为什么要区分跳转、刷新和禁用态
HarmonyOS 7.0 / API 26 互动卡片长按菜单桌面入口为什么要区分跳转、刷新和禁用态这篇只拆一个具体点互动卡片长按菜单的入口状态治理。版本边界先放前面下面的写法面向 HarmonyOS 7.0 / API 26。工程里如果还在混用旧 SDK、旧模拟器镜像或旧设备系统先不要直接照搬代码先把版本对齐。这个问题为什么值得单独拆互动卡片放到桌面以后入口不再只是一个普通按钮。用户可能点一下进入页面也可能长按查看操作也可能在网络差、账号失效、数据过期时看到不可用状态。如果跳转、刷新、禁用态都混在一个 onClick 里后面很容易出现点了没反应、重复刷新、状态恢复错误这类问题。这类问题的麻烦点是代码经常能编译页面第一次打开也像是正常的但一到折叠屏、多窗口、后台恢复、跨设备入口或审核机型上行为就开始不稳定。我的处理方式不是先改 UI而是先把能力边界、触发条件、失败原因和兜底方案拆开。先对齐官方能力边界参考点要确认什么落到代码里怎么处理HarmonyOS 7.0 互动卡片能力桌面入口、刷新和点击行为边界把卡片入口拆成 jump、refresh、disabled 三类状态ArkTS 状态建模状态枚举和原因字段让 UI 只消费 CardActionState不直接判断一堆布尔值应用体验与审核自检异常入口不能误导用户禁用态必须给出可见提示和日志原因这里要避免一个常见误区看到 7.0 新能力就直接在页面里调用。更稳的做法是先做一层能力判断判断通过再进入新能力分支判断失败就明确走兜底日志里也要能看出失败原因。两个容易复现的场景场景一卡片数据过期用户长按后先刷新再进入详情复现方式不要做得太复杂。先把页面打开到目标状态再连续触发两次能力入口。这个时候重点看三个点状态有没有丢、资源有没有重复申请、失败时有没有明确原因。场景二账号态失效长按菜单仍显示可用操作但点击后失败第二个场景更接近线上用户不会按开发者预设路径操作他会切后台、恢复、换方向、分屏、拖拽、锁屏再回来。只看单次点击问题很容易被遮住。拆法先决策再执行再兜底我会把实现拆成三层能力判断层只判断版本、设备形态、入口参数和依赖状态。执行层只负责调用具体 API不混入页面展示逻辑。兜底层能力不可用时给旧方案、提示或延迟重试不让页面进入半坏状态。这样拆的好处是后面升级 SDK 或换设备时不需要在每个页面里翻 if 判断。页面只拿一个明确结果能用、不能用、为什么不能用。Demo把能力判断收口到一个 guardtypeCardActionKindjump|refresh|disabled;typeCardBlockReasonnone|loginExpired|dataExpired|networkOffline;interfaceCardEntrySnapshot{loggedIn:boolean;online:boolean;dataVersion:number;latestVersion:number;}interfaceCardActionState{kind:CardActionKind;reason:CardBlockReason;label:string;nextRoute?:string;}classInteractiveCardActionResolver{resolve(snapshot:CardEntrySnapshot):CardActionState{if(!snapshot.online){return{kind:disabled,reason:networkOffline,label:网络不可用稍后再试};}if(!snapshot.loggedIn){return{kind:disabled,reason:loginExpired,label:登录状态失效请先打开应用};}if(snapshot.dataVersionsnapshot.latestVersion){return{kind:refresh,reason:dataExpired,label:数据已更新先刷新卡片};}return{kind:jump,reason:none,label:打开详情,nextRoute:pages/CardDetailPage};}}EntryComponentstruct CardMenuDemoPage{Stateprivatelabel:string等待判断;Stateprivatereason:stringnone;privateresolver:InteractiveCardActionResolvernewInteractiveCardActionResolver();privatehandleCard(snapshot:CardEntrySnapshot):void{conststatethis.resolver.resolve(snapshot);this.labelstate.label;this.reasonstate.reason;console.info([card-menu] kindstate.kind, reasonstate.reason, route(state.nextRoute??-));}build(){Column({space:12}){Text(this.label).fontSize(18).fontWeight(FontWeight.Medium)Text(reasonthis.reason).fontSize(13).fontColor(#667085)Button(模拟可跳转).onClick(()this.handleCard({loggedIn:true,online:true,dataVersion:3,latestVersion:3}))Button(模拟需刷新).onClick(()this.handleCard({loggedIn:true,online:true,dataVersion:2,latestVersion:3}))Button(模拟禁用态).onClick(()this.handleCard({loggedIn:false,online:true,dataVersion:3,latestVersion:3}))}.padding(20).width(100%)}}这个 Demo 只做一件事先判断能力条件再把结果交给页面。页面不直接关心 API 细节也不把版本判断散落在 build 里。后面要接真实页面时可以把 HarmonyFeatureGuard 放到公共模块里复用。异常日志应该长什么样[card-menu] kinddisabled, reasonloginExpired, route- [card-menu] kindrefresh, reasondataExpired, route- [card-menu] kindjump, reasonnone, routepages/CardDetailPage日志不要只打印“失败了”。至少要带上 scene、status、reason 和耗时。否则出了问题以后只能靠猜。验证矩阵场景输入条件预期结果关键日志数据版本一致loggedIntrue, onlinetrue, dataVersionlatestVersion直接跳转详情kindjump, reasonnone卡片数据过期dataVersion latestVersion先刷新卡片不直接跳转kindrefresh, reasondataExpired登录失效loggedInfalse禁用入口并提示打开应用kinddisabled, reasonloginExpired网络不可用onlinefalse禁用入口避免重复失败请求kinddisabled, reasonnetworkOffline跑完后应该看到的结果case jump_when_data_fresh - passed case refresh_when_data_expired - passed case disabled_when_login_expired - passed case disabled_when_network_offline - passed我会怎么选方案方案适合场景风险继续沿用旧写法旧页面、小范围兼容遇到 7.0 新能力边界时不好排查在页面内临时处理快速验证问题代码容易散后面不好复用抽成独立工具或组件多页面、多设备、多状态复用前期要把输入输出设计清楚我的选择是第三种。只要这个能力会被多个页面用到就不要把判断逻辑塞在页面里。页面只负责展示能力边界、异常兜底、版本判断放到独立函数或组件里。这样后面改 SDK、换设备、补兼容逻辑影响面会小很多。排查顺序先看入口状态是否被拆成枚举不要用多个布尔值互相覆盖。再看长按菜单和点击入口是否复用同一套 resolver避免两个入口判断不一致。再看失败原因是否写进日志不能只看到 disabled 却不知道为什么禁用。最后看刷新分支是否会重复触发数据未更新完成前不要继续跳转。可以怎么复用这个写法可以继续扩成一个小工具输入 featureName、apiLevel、deviceMode、entryState输出 passed / failed / fallback 和 reason。页面层只根据结果更新 UI。这样做虽然前期多写几行代码但后面接更多 HarmonyOS 7.0 能力时判断逻辑不会越写越散。最后总结互动卡片入口要先把状态分清楚能跳转就跳转数据过期先刷新条件不满足就禁用并给出原因。这样做不是为了多写几层代码而是为了让桌面入口在异常场景下也能解释清楚自己为什么不能继续。这类特性真正有价值的地方不是知道一个新名字而是知道它在什么场景该用、什么时候不该用、怎么复现问题、怎么把修复沉淀成可复用代码。后面再接复杂页面时先把这个小 Demo 跑通基本能避开一半低级返工。和旧写法的差别旧写法常见问题是把跳转、刷新、禁用都塞进点击回调里逻辑短期看着省事后面入口一多就开始互相打架。这里改成 resolver 后长按菜单、桌面点击、应用内入口都能共用同一套判断差异只留在展示层。