Flutter实现水平滚动列表内子Widget父组件内粘性头部的方法

一、自定义实现思路 #

要实现水平滚动列表中，子组件C在其父组件P范围内保持粘性（滚动时固定在视口边缘，直到P组件完全移出视口），可以通过滚动监听+Stack定位的方式实现：

• 给每个P组件绑定GlobalKey，用来获取它在滚动视图中的位置与尺寸信息
• 用NotificationListener<ScrollNotification>包裹水平滚动列表，实时监听滚动偏移量
• 根据滚动偏移量判断当前需要固定的C组件，计算其应该固定的位置还是跟随父组件移动
• 通过Stack将C组件置于滚动列表上层，用Positioned动态调整位置实现粘性效果

简化代码示例 #

class HorizontalStickyHeader extends StatefulWidget {
  @override
  State<HorizontalStickyHeader> createState() => _HorizontalStickyHeaderState();
}

class _HorizontalStickyHeaderState extends State<HorizontalStickyHeader> {
  final ScrollController _scrollController = ScrollController();
  final List<GlobalKey> _pContainerKeys = List.generate(3, (_) => GlobalKey());
  int _currentStickyIndex = 0;

  @override
  void initState() {
    super.initState();
    _scrollController.addListener(_updateStickyHeaderPosition);
  }

  void _updateStickyHeaderPosition() {
    setState(() {
      final currentPBox = _pContainerKeys[_currentStickyIndex].currentContext?.findRenderObject() as RenderBox?;
      if (currentPBox == null) return;

      final pLeft = currentPBox.localToGlobal(Offset.zero).dx;
      final pRight = pLeft + currentPBox.size.width;
      final viewportWidth = MediaQuery.of(context).size.width;

      // 判断是否需要切换到下一个粘性头部
      if (_scrollController.offset > pRight - viewportWidth) {
        if (_currentStickyIndex < _pContainerKeys.length - 1) {
          _currentStickyIndex++;
        }
      }
      // 判断是否需要切换到上一个粘性头部
      else if (_scrollController.offset < pLeft) {
        if (_currentStickyIndex > 0) {
          _currentStickyIndex--;
        }
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    final viewportWidth = MediaQuery.of(context).size.width;
    return Stack(
      children: [
        ListView.builder(
          controller: _scrollController,
          scrollDirection: Axis.horizontal,
          itemCount: 3,
          itemBuilder: (context, index) {
            return Container(
              key: _pContainerKeys[index],
              width: 400,
              color: index % 2 == 0 ? Colors.grey[200] : Colors.grey[300],
              child: Column(
                children: [
                  // 占位，避免内容被粘性头部遮挡
                  const SizedBox(height: 50),
                  Expanded(child: Center(child: Text('P${index+1} 内容区域'))),
                ],
              ),
            );
          },
        ),
        // 粘性头部C组件
        Positioned(
          left: _getStickyLeftOffset(),
          top: 0,
          child: Container(
            width: viewportWidth,
            height: 50,
            color: Colors.blueAccent,
            child: Center(child: Text('C${_currentStickyIndex+1}')),
          ),
        ),
      ],
    );
  }

  double _getStickyLeftOffset() {
    final currentPBox = _pContainerKeys[_currentStickyIndex].currentContext?.findRenderObject() as RenderBox?;
    if (currentPBox == null) return 0;

    final pLeft = currentPBox.localToGlobal(Offset.zero).dx;
    final pRight = pLeft + currentPBox.size.width;
    final viewportWidth = MediaQuery.of(context).size.width;

    // 限制头部的左右偏移范围，确保在P组件范围内保持粘性
    return _scrollController.offset.clamp(
      pLeft,
      pRight - viewportWidth,
    );
  }

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

二、推荐工具包 #

如果不想自定义实现，可以尝试以下第三方包：

• flutter_sticky_header：支持垂直/水平方向的粘性头部，通过StickyHeader组件配置header为你的C组件，结合水平ListView即可快速实现效果，需要注意适配水平布局的尺寸计算。
• sticky_headers：原生支持粘性头部，虽然默认是垂直方向，但通过自定义滚动视图和布局参数，也能适配水平场景。

内容的提问来源于stack exchange，提问作者Baran S.