Flutter：如何创建带灵活头部、列表项平滑显隐的CustomScrollView

我明白你遇到的问题了——在SliverAppBar的flexibleSpace里用Stack叠加渐变确实会踩坑，毕竟SliverAppBar的滚动布局逻辑和普通Widget不一样，直接套用底部渐变的方法肯定行不通。下面给你两个可行的实现方案，既能保留灵活头部的特性，又能让列表项在滚动时通过渐变平滑消失/显示。

方案一：用Stack+滚动监听实现精准渐变定位 #

这个方案适合需要完全控制渐变层位置的场景，能让渐变始终贴合SliverAppBar的底部，不管头部是展开还是收缩状态。

import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(home: const GradientScrollDemo());
  }
}

class GradientScrollDemo extends StatefulWidget {
  const GradientScrollDemo({super.key});

  @override
  State<GradientScrollDemo> createState() => _GradientScrollDemoState();
}

class _GradientScrollDemoState extends State<GradientScrollDemo> {
  final ScrollController _scrollController = ScrollController();
  final double _expandedHeaderHeight = 200;
  late double _headerBottomPosition;

  @override
  void initState() {
    super.initState();
    _headerBottomPosition = _expandedHeaderHeight;
    _scrollController.addListener(_updateHeaderPosition);
  }

  void _updateHeaderPosition() {
    final collapsedHeaderHeight = AppBar().preferredSize.height;
    final scrollableRange = _expandedHeaderHeight - collapsedHeaderHeight;
    final currentScroll = _scrollController.offset.clamp(0.0, scrollableRange);
    
    setState(() {
      _headerBottomPosition = _expandedHeaderHeight - currentScroll;
    });
  }

  @override
  void dispose() {
    _scrollController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final bgColor = Theme.of(context).scaffoldBackgroundColor;
    return Stack(
      clipBehavior: Clip.none, // 允许渐变层超出CustomScrollView边界
      children: [
        CustomScrollView(
          controller: _scrollController,
          slivers: [
            // 灵活头部
            SliverAppBar(
              expandedHeight: _expandedHeaderHeight,
              flexibleSpace: FlexibleSpaceBar(
                background: Container(
                  color: Colors.deepPurple,
                  child: const Center(
                    child: Text(
                      "Flexible Header",
                      style: TextStyle(color: Colors.white, fontSize: 26),
                    ),
                  ),
                ),
                title: const Text("Smooth Scroll Demo"),
              ),
            ),
            // 列表内容
            SliverList(
              delegate: SliverChildBuilderDelegate(
                (context, index) => ListTile(
                  title: Text("List Item $index"),
                  tileColor: index % 2 == 0 ? Colors.grey[100] : Colors.white,
                ),
                childCount: 50,
              ),
            ),
            // 底部渐变：直接加在列表末尾
            SliverToBoxAdapter(
              child: Container(
                height: 35,
                decoration: BoxDecoration(
                  gradient: LinearGradient(
                    begin: Alignment.topCenter,
                    end: Alignment.bottomCenter,
                    colors: [bgColor.withOpacity(0), bgColor],
                  ),
                ),
              ),
            ),
          ],
        ),
        // 顶部渐变：始终贴在头部底部
        Positioned(
          top: _headerBottomPosition,
          left: 0,
          right: 0,
          height: 35,
          child: Container(
            decoration: BoxDecoration(
              gradient: LinearGradient(
                begin: Alignment.bottomCenter,
                end: Alignment.topCenter,
                colors: [bgColor.withOpacity(0), bgColor],
              ),
            ),
          ),
        ),
      ],
    );
  }
}

关键细节说明：

1. 滚动监听：通过ScrollController计算头部当前的底部位置，让渐变层始终贴合头部，不会出现错位。
2. Stack的clipBehavior：必须设为Clip.none，否则渐变层会被CustomScrollView的边界裁剪掉。
3. 底部渐变简化：直接用SliverToBoxAdapter加在列表末尾，比Stack叠加到外部更简单，效果一致。

方案二：用SliverPersistentHeader实现纯Sliver体系的渐变 #

如果你更倾向于用CustomScrollView原生的Sliver组件来实现，这个方案更简洁，不需要额外的Stack和滚动监听。

import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(home: const GradientScrollDemo());
  }
}

class GradientScrollDemo extends StatelessWidget {
  const GradientScrollDemo({super.key});

  @override
  Widget build(BuildContext context) {
    final bgColor = Theme.of(context).scaffoldBackgroundColor;
    return CustomScrollView(
      slivers: [
        // 灵活头部
        SliverAppBar(
          expandedHeight: 200,
          flexibleSpace: FlexibleSpaceBar(
            background: Container(
              color: Colors.deepPurple,
              child: const Center(
                child: Text(
                  "Flexible Header",
                  style: TextStyle(color: Colors.white, fontSize: 26),
                ),
              ),
            ),
            title: const Text("Smooth Scroll Demo"),
          ),
        ),
        // 顶部渐变：用SliverPersistentHeader固定在头部下方
        SliverPersistentHeader(
          pinned: true,
          delegate: GradientHeaderDelegate(
            backgroundColor: bgColor,
            gradientHeight: 35,
          ),
        ),
        // 列表内容
        SliverList(
          delegate: SliverChildBuilderDelegate(
            (context, index) => ListTile(
              title: Text("List Item $index"),
              tileColor: index % 2 == 0 ? Colors.grey[100] : Colors.white,
            ),
            childCount: 50,
          ),
        ),
        // 底部渐变
        SliverToBoxAdapter(
          child: Container(
            height: 35,
            decoration: BoxDecoration(
              gradient: LinearGradient(
                begin: Alignment.topCenter,
                end: Alignment.bottomCenter,
                colors: [bgColor.withOpacity(0), bgColor],
              ),
            ),
          ),
        ),
      ],
    );
  }
}

// 自定义SliverPersistentHeader代理类
class GradientHeaderDelegate extends SliverPersistentHeaderDelegate {
  final Color backgroundColor;
  final double gradientHeight;

  GradientHeaderDelegate({
    required this.backgroundColor,
    required this.gradientHeight,
  });

  @override
  Widget build(BuildContext context, double shrinkOffset, bool overlapsContent) {
    return Container(
      decoration: BoxDecoration(
        gradient: LinearGradient(
          begin: Alignment.bottomCenter,
          end: Alignment.topCenter,
          colors: [backgroundColor.withOpacity(0), backgroundColor],
        ),
      ),
    );
  }

  @override
  double get maxExtent => gradientHeight;

  @override
  double get minExtent => gradientHeight;

  @override
  bool shouldRebuild(covariant SliverPersistentHeaderDelegate oldDelegate) {
    return oldDelegate.maxExtent != gradientHeight;
  }
}

优势说明：

• 完全基于CustomScrollView的Sliver体系，没有额外的布局嵌套，性能更优。
• 渐变层会自动跟随列表滚动，不需要手动计算位置，代码更简洁。

为什么不能直接在flexibleSpace里加渐变？ #

SliverAppBar的flexibleSpace在头部收缩时会触发缩放、位移的动画，直接在里面叠加渐变会导致渐变跟着头部一起收缩变形，无法实现“列表项滚动时被渐变覆盖”的效果。所以必须把渐变层和flexibleSpace分开处理。

内容的提问来源于stack exchange，提问作者Thomas