企业官网建设流程全解析

HarmonyOS 7 标题栏滚动模糊没效果？检查 Navigation 的 backgroundColor 是否盖住了它

列表滑动时，想让 Navigation 标题栏从清透逐渐变成模糊玻璃。scrollEffectOptions已经配上，页面也确实在滚动，但看起来仍是一整块纯色。先别急着换模糊半径：API 26 的官方说明指出，同一组NavigationTitleOptions里如果还设置了backgroundColor，它会覆盖滚动模糊效果。本文把这个容易漏看的覆盖关系做成两个对照案例。

先确定 API 边界

scrollEffectOptions是 Navigation 的title选项，从 HarmonyOS 7 对应的 API 26.0.0 开始提供。它不是普通backgroundBlurStyle的别名。官方提供COMMON_BLUR与GRADUAL_BLUR两种滚动样式，并通过blurEffectiveStartOffset、blurEffectiveEndOffset指定起止距离。默认分别为 0vp、8vp；这两个参数不支持LengthMetrics.percent。

案例一：效果参数正确，却被背景色盖住

下面是可以放到 API 26 页面中的最小对照结构。核心错误不在列表，而在title选项最后一行的固定背景色。

import { LengthMetrics } from '@kit.ArkUI'; @Entry @Component struct ScrollBlurCovered { private items: number[] = []; aboutToAppear(): void { for (let i = 0; i < 40; i++) { this.items.push(i); } } build() { Navigation() { List({ space: 8 }) { ForEach(this.items, (item: number) => { ListItem() { Text(`第 ${item + 1} 行：向上滚动观察标题栏`) .width('100%') .height(72) .backgroundColor('#EEF1F4') } }, (item: number) => item.toString()) } .width('100%') .height('100%') } .title('滚动效果对照', { barStyle: BarStyle.STACK, scrollEffectOptions: { scrollEffectType: ScrollEffectType.COMMON_BLUR, blurEffectiveStartOffset: LengthMetrics.vp(0), blurEffectiveEndOffset: LengthMetrics.vp(8) }, backgroundColor: '#FFCC6655' // 固定色会盖住滚动模糊 }) .width('100%') .height('100%') } }

请先确认列表能滚动，再看标题栏：如果纯色始终占据标题区域，不能凭这个画面断言scrollEffectOptions没被识别。固定背景色已经足以解释为什么模糊看不出来。

案例二：去掉覆盖层，再检查起止距离

保留上面的列表与Navigation，只替换.title的选项。这里没有再给标题栏一个固定backgroundColor，并把滚动效果从 0vp 到 8vp 完整写出来。

.title('滚动效果对照', { barStyle: BarStyle.STACK, scrollEffectOptions: { scrollEffectType: ScrollEffectType.COMMON_BLUR, blurEffectiveStartOffset: LengthMetrics.vp(0), blurEffectiveEndOffset: LengthMetrics.vp(8) } })

如果去掉颜色后仍不明显，先把列表做长，确认滚动区域属于该 Navigation 内容；然后再比较COMMON_BLUR与GRADUAL_BLUR，不要一次同时改变标题布局、背景材质和偏移量。示意图表达的是“覆盖层遮挡”的关系，不代表不同设备的材质像素效果完全相同。

一个更快的排查顺序

1. 看 API 版本：scrollEffectOptions是 26.0.0 新选项，旧 SDK 工程不能照搬。
2. 看标题栏是否显示、列表是否真的产生滚动；静止页面没有滚动过渡可观察。
3. 搜同一个.title(..., options)是否写了backgroundColor，先去掉它再对比。
4. 起止距离先用 0vp 和 8vp。若设置了很大的起点，短列表可能永远达不到触发位置。
5. 最后再切换普通/渐进模糊样式，分别在浅色、深色与不同算力设备上观察。

这篇把官方 2026-09-09 更新的 API 定义与示例中的配置做成了最小对照；目前没有 API 26 SDK 编译和真机截图，因此不声称已在具体机型复现。实际交付时应保存“有背景色/无背景色”的同机截图，并记录系统、API、设备型号与标题栏配置。

官方依据：Navigation API 参考：ScrollEffectOptions 与 NavigationTitleOptions。