HarmonyOS 7 / API 26 沉浸光感可读性排查：亮图背景下标题、按钮和弹层如何保持清晰

先说这类问题为什么容易漏

沉浸光感看起来是视觉能力，但真正落到页面里，经常会变成可读性和操作层问题。背景图一亮，标题可能发灰；弹层一盖上来，按钮和遮罩可能互相抢层级；窗口一拖拽，刚才还能读清楚的区域又变得刺眼。

我这次不按“效果展示”的方式写，而是按一次排查来写：先复现坏结果，再拆策略，再给出能复用的代码。这样以后遇到类似的沉浸式标题栏、图片详情页、弹层浮层，也能用同一套检查方法。

版本边界和官方能力点

我自己的判断是：沉浸光感不能只看“背景有没有动效”。如果页面承载的是阅读、购买、提交、返回这些关键操作，就必须把背景亮度、文字对比度、弹层优先级和窗口变化放到同一个策略里处理。

案例一：亮图背景下，标题和主按钮变得不清楚

先造一个最容易踩坑的场景：详情页顶部是一张亮色大图，标题、收藏按钮和返回按钮都浮在图上。刚开始用固定白字看起来还行，一换成浅色图片就不稳。

typeLightLevel='dark'|'normal'|'bright';interfaceImmersiveInput{imageLuma:number;// 0 到 1，越大越亮hasPrimaryAction:boolean;isDialogShowing:boolean;}interfaceImmersiveDecision{textTone:'light'|'dark';maskOpacity:number;actionStyle:'solid'|'outline'|'hidden';reason:string;}functiongetLightLevel(luma:number):LightLevel{if(luma>=0.72)return'bright';if(luma<=0.32)return'dark';return'normal';}functiondecideImmersiveStyle(input:ImmersiveInput):ImmersiveDecision{constlevel=getLightLevel(input.imageLuma);if(input.isDialogShowing){return{textTone:'dark',maskOpacity:0.52,actionStyle:'solid',reason:'dialog-needs-stable-readable-layer'};}if(level==='bright'){return{textTone:'dark',maskOpacity:input.hasPrimaryAction?0.38:0.28,actionStyle:'solid',reason:'bright-image-needs-dark-text-and-mask'};}return{textTone:'light',maskOpacity:level==='dark'?0.18:0.26,actionStyle:input.hasPrimaryAction?'outline':'hidden',reason:'normal-immersive-display'};}

这段代码的关键不是公式多复杂，而是把“为什么这么选”一起返回。后面排查时，只要日志里出现bright-image-needs-dark-text-and-mask，就知道这次不是按钮样式随机变化，而是亮图触发了可读性保护。

案例二：弹层叠加后，沉浸背景不能继续抢视觉焦点

第二个场景更常见：页面本身已经做了沉浸光感，用户又打开了筛选弹层、分享弹层或确认弹层。如果底层背景还很强，弹层的标题和按钮就会不稳定。

interfaceLayerState{pageImmersiveEnabled:boolean;dialogVisible:boolean;sheetVisible:boolean;windowWidthVp:number;}interfaceLayerPolicy{keepBackgroundMotion:boolean;dimBackground:boolean;lockMainAction:boolean;layoutMode:'phone'|'tablet'|'pc';}functionresolveLayerPolicy(state:LayerState):LayerPolicy{consthasOverlay=state.dialogVisible||state.sheetVisible;constlayoutMode=state.windowWidthVp>=1280?'pc':state.windowWidthVp>=840?'tablet':'phone';return{keepBackgroundMotion:state.pageImmersiveEnabled&&!hasOverlay,dimBackground:hasOverlay,lockMainAction:hasOverlay,layoutMode};}functionshouldRecalculateStyle(prev:LayerPolicy,next:LayerPolicy):boolean{returnprev.keepBackgroundMotion!==next.keepBackgroundMotion||prev.dimBackground!==next.dimBackground||prev.layoutMode!==next.layoutMode;}

我更推荐这种写法：弹层出现后，底层沉浸动效先让位，主操作区锁住，等弹层关闭再恢复。这样做的好处是结果可解释，也方便写自动化检查。

三种方案对比

我会选第三种。沉浸光感这种能力越靠近视觉，越不能只靠“看起来差不多”。只要页面里有关键按钮、关键标题或弹层，就应该让策略函数输出明确结果，再让 UI 去消费。

验收清单

• 亮图背景下，标题和返回按钮仍然能看清；
• 暗图背景下，遮罩不会把内容压得太脏；
• 弹层出现时，底层沉浸动效不会抢弹层焦点；
• 折叠屏、平板、鸿蒙电脑窗口宽度变化时，会重新计算策略；
• 日志里能看到本次样式变化的原因，而不是只看到一个布尔开关；
• 低电量或弱性能设备上，可以关闭非关键动效，但保留可读性保护。

最后总结

沉浸光感真正要做稳，重点不是把背景做得多炫，而是让页面在复杂状态下仍然清楚、可控、可回退。

我的经验是：先把亮度、弹层、窗口形态和主操作拆成输入，再统一产出文字、遮罩、按钮和动效策略。这样写出来的页面，视觉效果可以继续升级，底层逻辑也不会被越补越乱。