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。

参数	作用	排查时关注
scrollEffectType	普通模糊或渐进模糊	先用默认普通模糊排除样式差异
blurEffectiveStartOffset	开始进入效果的滚动距离	测试时别设得超过列表可滚动距离
blurEffectiveEndOffset	达到最终样式的距离	应比起点更晚，便于肉眼观察过渡
backgroundColor	标题栏背景色	与滚动效果同时设置时，可能把效果挡住

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

下面是可以放到 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。

补成可独立运行的无覆盖版本

上面的第二段只展示了差异项。真正回归时，建议保留一份完整页面，避免复制时漏掉可滚动内容或把效果配到错误的 Navigation 上。

import { LengthMetrics } from '@kit.ArkUI';

@Entry
@Component
struct ScrollBlurVisible {
  private rows: number[] = [];

  aboutToAppear(): void {
    for (let index = 0; index < 40; index++) {
      this.rows.push(index);
    }
  }

  build() {
    Navigation() {
      List({ space: 8 }) {
        ForEach(this.rows, (row: number) => {
          ListItem() {
            Text('第 ' + (row + 1) + ' 行：继续向上滑动')
              .width('100%')
              .height(72)
              .padding({ left: 16, right: 16 })
              .backgroundColor(row % 2 === 0 ? '#F4F7FA' : '#E9EEF3')
          }
        }, (row: number) => row.toString())
      }
      .width('100%')
      .height('100%')
    }
    .title('滚动模糊可见版本', {
      barStyle: BarStyle.STACK,
      scrollEffectOptions: {
        scrollEffectType: ScrollEffectType.COMMON_BLUR,
        blurEffectiveStartOffset: LengthMetrics.vp(0),
        blurEffectiveEndOffset: LengthMetrics.vp(8)
      }
    })
    .width('100%')
    .height('100%')
  }
}

这份代码与案例一只有一个关键差异：标题选项没有固定的 backgroundColor。在同一台设备、同一系统版本和同一滚动距离下分别运行两份代码，才能把“材质效果不明显”和“固定颜色确实覆盖效果”区分开。

不要只靠肉眼：用四组证据验收

检查点	失败表现	应保留的证据
可滚动距离	手指滑了但内容没有位移	首尾行号和滚动前后截图
配置归属	参数写在了另一个 Navigation	页面结构和 .title() 调用位置
覆盖层	去掉固定色后效果才出现	同机同距离 A/B 截图
起止偏移	短列表始终未到触发距离	实际滚动距离与 0vp/8vp 配置

回归记录至少写清系统版本、API 版本、设备型号、标题栏配置、滚动距离和截图时间。这样后续换机型或升级 SDK 时，能判断是平台材质差异、参数覆盖，还是页面根本没有进入有效滚动区间。

封装时保留一个明确边界

项目里可以统一保存模糊类型和起止距离，但不要在公共标题栏封装中默认注入不透明背景色。确实需要纯色标题栏的页面，应当显式选择“纯色模式”；需要滚动模糊的页面则选择“滚动材质模式”。两种模式互斥，比把 backgroundColor 和 scrollEffectOptions 同时塞进一份通用配置更容易评审，也更不容易在后续改主题时把效果重新盖住。