Flutter NestedScrollView 中吸顶 Header 与内层滚动的处理

问题描述

Flutter 里有一类页面很常见：顶部是一段介绍、搜索区或快捷入口，中间有一个吸顶的 tab/header，下面的内容还可以左右切换。每个 tab 内部又可能是列表、网格或自定义滚动内容。

结构大概是这样：

外层纵向滚动
  顶部内容
  pinned header / tabs

内部区域
  PageView
    page 1: ListView / GridView / CustomScrollView
    page 2: ListView / GridView / CustomScrollView

这类页面最容易出现的问题是：header 吸顶以后，内层列表继续往上滚，内容会“钻到”header 下面，看起来像是被 tab 遮住了。

很多时候第一反应是加 padding：

GridView.builder(
  padding: const EdgeInsets.only(top: 80),
  // ...
)

或者把 padding 套在 PageView 外面：

Padding(
  padding: const EdgeInsets.only(top: 80),
  child: PageView(
    children: [
      GridView.builder(
        // ...
      ),
    ],
  ),
)

这些写法有时看起来能暂时对齐，但并不稳定。header 高度一变、tab 切换一次、页面快速滚动一次，问题很容易又回来。

原因分析

这个问题的本质不是 padding 少了，而是两个滚动区域没有正确同步。

NestedScrollView 里通常存在两个滚动世界：

外层滚动：负责顶部内容和吸顶 header
内层滚动：负责每个 tab/page 里的列表内容

当外层 SliverPersistentHeader(pinned: true) 吸顶时，它会占住顶部一块空间。可是内层的 GridView 或 ListView 并不知道这块空间存在。

如果直接这样写：

NestedScrollView(
  headerSliverBuilder: (context, innerBoxIsScrolled) {
    return [
      SliverPersistentHeader(
        pinned: true,
        delegate: YourHeaderDelegate(),
      ),
    ];
  },
  body: PageView(
    children: [
      GridView.builder(
        // ...
      ),
    ],
  ),
)

外层 header 和内层列表实际上没有建立 overlap 关系。内层列表只知道自己要滚到顶部，却不知道顶部已经被 pinned header 占了一部分。

所以这里不应该靠手动判断吸顶状态，也不应该靠猜一个固定 padding。更稳的方式是使用 Flutter 为 NestedScrollView 提供的 overlap 机制。

解决方案

Flutter 提供了两个关键 sliver：

SliverOverlapAbsorber
SliverOverlapInjector

可以这样理解：

外层用 SliverOverlapAbsorber 记录 header 产生的 overlap，内层用 SliverOverlapInjector 把这个 overlap 注入回来。

也就是说：

外层 header：我吸顶后占了多少空间
内层列表：我从正确的位置开始布局

一个比较稳的结构是：

NestedScrollView(
  headerSliverBuilder: (context, innerBoxIsScrolled) {
    return [
      SliverToBoxAdapter(
        child: topContent,
      ),
      SliverOverlapAbsorber(
        handle: NestedScrollView.sliverOverlapAbsorberHandleFor(context),
        sliver: SliverPersistentHeader(
          pinned: true,
          delegate: YourPinnedHeaderDelegate(
            child: pinnedTabs,
          ),
        ),
      ),
    ];
  },
  body: Builder(
    builder: (nestedContext) {
      return PageView.builder(
        itemBuilder: (context, index) {
          return CustomScrollView(
            slivers: [
              SliverOverlapInjector(
                handle: NestedScrollView
                    .sliverOverlapAbsorberHandleFor(nestedContext),
              ),
              const SliverToBoxAdapter(
                child: SizedBox(height: 12),
              ),
              SliverPadding(
                padding: const EdgeInsets.symmetric(horizontal: 24),
                sliver: SliverGrid(
                  // ...
                ),
              ),
            ],
          );
        },
      );
    },
  ),
)

这里有几个关键点。

外层 pinned header 要被 Absorber 包住

SliverOverlapAbsorber 应该包住会产生 overlap 的 sliver。通常就是那个 pinned: true 的 SliverPersistentHeader。

SliverOverlapAbsorber(
  handle: NestedScrollView.sliverOverlapAbsorberHandleFor(context),
  sliver: SliverPersistentHeader(
    pinned: true,
    delegate: YourPinnedHeaderDelegate(),
  ),
)

内层页面用 CustomScrollView

如果 body 里有 PageView，不要直接让每个 page 返回 GridView 或 ListView。更推荐让每个 page 返回 CustomScrollView，这样才能在 sliver 列表的最前面放 SliverOverlapInjector。

CustomScrollView(
  slivers: [
    SliverOverlapInjector(
      handle: NestedScrollView.sliverOverlapAbsorberHandleFor(nestedContext),
    ),
    SliverGrid(
      // ...
    ),
  ],
)

视觉间距放在 Injector 后面

如果内容和吸顶 header 之间需要留一点距离，不要把 padding 加到 PageView 外层。那个位置影响的是横向翻页区域，而不是每一页内部内容的真实滚动起点。

更合适的位置是在 SliverOverlapInjector 后面加一个很小的 gap：

const SliverToBoxAdapter(
  child: SizedBox(height: 12),
)

这个值可以抽成 UI 常量：

static const double pageTopGap = 12;

以后调视觉间距只改这个常量，不要改滚动结构。

常见错误

给 PageView 加 top padding

PageView 负责的是左右切换，不负责每个页面内部内容的顶部同步。把 padding 放在 PageView 外层，经常会让横向滑动区域和纵向内容位置绑在一起，后面会很难维护。

直接给 GridView 猜一个 padding

给 GridView 写 padding: EdgeInsets.only(top: 80) 只是把内容视觉上推下去。它没有解决外层 header 和内层滚动之间的 overlap 同步问题。

一旦 header 高度变化，或者不同 tab 的内容结构不同，这个 padding 就会变成新的问题。

用错 context 获取 handle

NestedScrollView.sliverOverlapAbsorberHandleFor(context) 必须拿到 NestedScrollView 下面的 context。

如果在 body 里需要 handle，通常用 Builder 创建一个 nestedContext：

body: Builder(
  builder: (nestedContext) {
    return CustomScrollView(
      slivers: [
        SliverOverlapInjector(
          handle: NestedScrollView
              .sliverOverlapAbsorberHandleFor(nestedContext),
        ),
      ],
    );
  },
)

否则可能遇到类似错误：

NestedScrollView.sliverOverlapAbsorberHandleFor must be called with a context that contains a NestedScrollView.

排查清单

遇到吸顶 header 和内层列表错位时，可以按这个顺序看：

检查项	重点
是否用了 `NestedScrollView`	外层和内层滚动需要协作
是否有 `SliverPersistentHeader(pinned: true)`	pinned header 会产生顶部占位
body 内是否还有滚动组件	例如 `PageView`、`ListView`、`GridView`
pinned header 是否被 `SliverOverlapAbsorber` 包住	外层要记录 overlap
内层第一个 sliver 是否是 `SliverOverlapInjector`	内层要消费 overlap
内层是否使用 `CustomScrollView`	方便组合 injector、gap 和内容 sliver
视觉间距是否放在 injector 后面	不要放在 `PageView` 外层

如果 absorber 和 injector 没有成对出现，优先修结构，不要先调 padding。

总结

这类布局可以记住一句话：

外层吸顶用 Absorber，内层滚动用 Injector。
PageView 只管横向切换，CustomScrollView 负责纵向内容。

NestedScrollView 本身不是问题，问题通常出在外层 header 和内层列表没有建立 overlap 关系。

一旦结构理顺，很多看起来像“遮挡”“穿透”“padding 不生效”的问题，其实都会变成可控的 sliver 布局问题。