HarmonyOS 7 / API 26 沉浸光感可读性排查：亮图背景下标题、按钮和弹层如何保持清晰
HarmonyOS 7 / API 26 沉浸光感可读性排查：亮图背景下标题、按钮和弹层如何保持清晰
先说这类问题为什么容易漏
沉浸光感看起来是视觉能力，但真正落到页面里，经常会变成可读性和操作层问题。背景图一亮，标题可能发灰；弹层一盖上来，按钮和遮罩可能互相抢层级；窗口一拖拽，刚才还能读清楚的区域又变得刺眼。
我这次不按“效果展示”的方式写，而是按一次排查来写：先复现坏结果，再拆策略，再给出能复用的代码。这样以后遇到类似的沉浸式标题栏、图片详情页、弹层浮层，也能用同一套检查方法。
版本边界和官方能力点
| 检查项 | 这篇的处理方式 |
|---|---|
| 系统版本 | 面向 HarmonyOS 7.0 / 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 去消费。
验收清单
- 亮图背景下，标题和返回按钮仍然能看清；
- 暗图背景下，遮罩不会把内容压得太脏；
- 弹层出现时，底层沉浸动效不会抢弹层焦点；
- 折叠屏、平板、鸿蒙电脑窗口宽度变化时，会重新计算策略；
- 日志里能看到本次样式变化的原因，而不是只看到一个布尔开关；
- 低电量或弱性能设备上，可以关闭非关键动效，但保留可读性保护。
最后总结
沉浸光感真正要做稳，重点不是把背景做得多炫，而是让页面在复杂状态下仍然清楚、可控、可回退。
我的经验是：先把亮度、弹层、窗口形态和主操作拆成输入，再统一产出文字、遮罩、按钮和动效策略。这样写出来的页面，视觉效果可以继续升级，底层逻辑也不会被越补越乱。