Scrollable

处理滚动逻辑的基础组件

Scrollable是Flutter中用于处理滚动逻辑的基础组件，它本身不直接渲染内容，而是作为可滚动区域的控制器。Scrollable的核心功能包括:

滚动逻辑管理: 处理手势(如拖动、滑动)、滚动动画和物理效果(如弹性滚动)。
内容适配: 通过Viewport和Sliver机制，动态调整子组件布局以支持大量数据。
灵活性: 可与ListView、GridView等高级滚动组件结合使用，或自定义滚动行为。

Scrollable基于Scrollable类(属于widgets库)，其核心逻辑通过ScrollController、ScrollPhysics和ScrollView等类协作实现。它适用于任何需要滚动交互的场景，如列表、图库或长文本显示。

使用场景

列表展示: 显示长列表数据(如聊天记录、商品列表)。
水平滚动: 实现横向图片轮播或选项卡。
自定义滚动: 需要精细控制滚动行为(如parallax效果、嵌套滚动)。
性能优化: 通过懒加载(如ListView.builder)处理大量数据。

示例

1. 基础垂直滚动

import 'package:flutter/material.dart';

class BasicScrollableExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scrollable(
      axisDirection: AxisDirection.down, // 垂直向下滚动
      viewportBuilder: (context, offset) {
        return Viewport(
          offset: offset,
          slivers: [
            SliverList(
              delegate: SliverChildListDelegate([
                Container(height: 100, color: Colors.red, child: Center(child: Text('Item 1'))),
                Container(height: 100, color: Colors.blue, child: Center(child: Text('Item 2'))),
                Container(height: 100, color: Colors.green, child: Center(child: Text('Item 3'))),
                // 添加更多项以测试滚动
              ]),
            ),
          ],
        );
      },
    );
  }
}

2. 水平滚动与交互

import 'package:flutter/material.dart';

class HorizontalScrollableExample extends StatefulWidget {
  @override
  _HorizontalScrollableExampleState createState() => _HorizontalScrollableExampleState();
}

class _HorizontalScrollableExampleState extends State<HorizontalScrollableExample> {
  final ScrollController _controller = ScrollController();
  double _scrollOffset = 0.0;

  @override
  void initState() {
    super.initState();
    _controller.addListener(() {
      setState(() {
        _scrollOffset = _controller.offset;
      });
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('滚动偏移: $_scrollOffset'),
        Expanded(
          child: Scrollable(
            axisDirection: AxisDirection.right, // 水平向右滚动
            controller: _controller,
            viewportBuilder: (context, offset) {
              return Viewport(
                offset: offset,
                slivers: [
                  SliverToBoxAdapter(
                    child: Row(
                      children: List.generate(10, (index) => 
                        Container(width: 150, height: 100, color: Colors.primaries[index], child: Center(child: Text('Card $index')))
                      ),
                    ),
                  ),
                ],
              );
            },
          ),
        ),
      ],
    );
  }

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

3. 自定义滚动物理效果

import 'package:flutter/material.dart';

class CustomPhysicsScrollable extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Theme(
      data: ThemeData.dark(),
      child: Scrollable(
        physics: ClampingScrollPhysics(), // 禁用 iOS 风格的弹性效果
        axisDirection: AxisDirection.down,
        viewportBuilder: (context, offset) {
          return Viewport(
            offset: offset,
            slivers: [
              SliverFixedExtentList(
                itemExtent: 50,
                delegate: SliverChildBuilderDelegate(
                  (context, index) => ListTile(title: Text('Item $index')),
                  childCount: 50,
                ),
              ),
            ],
          );
        },
      ),
    );
  }
}

注意点

使用 Scrollable 时需注意以下常见问题和优化建议：

常见问题

性能瓶颈: 直接使用SliverChildListDelegate加载大量子组件会导致内存溢出。优先使用SliverChildBuilderDelegate或ListView.builder实现懒加载。
嵌套滚动冲突: 当Scrollable嵌套在其他滚动组件内时，可能引发手势冲突。使用NestedScrollView或自定义ScrollBehavior解决。
控制器未释放: ScrollController需在dispose()中释放，避免内存泄漏。
方向适配: 水平滚动时需确保子组件宽度固定或可计算，否则布局可能出错。

优化技巧

懒加载: 对于动态数据，使用builder构造函数(如ListView.builder)减少内存占用。
物理效果选择:
- BouncingScrollPhysics: iOS风格弹性效果。
- ClampingScrollPhysics: Android风格clamping效果(默认)。
- NeverScrollableScrollPhysics: 禁用滚动。
监听滚动: 通过ScrollController实现分页加载或动画联动。

最佳实践

优先使用高级组件(如ListView、GridView)，它们封装了Scrollable的常见逻辑。
测试滚动性能时，使用Flutter DevTools的“Performance”面板分析帧率。
在Web或桌面端，考虑添加滚动条(如Scrollbar组件)提升用户体验。

构造函数

const Scrollable({
  Key? key,
  required this.viewportBuilder, // 必需：构建 Viewport 内容的回调
  this.axisDirection = AxisDirection.down, // 滚动方向
  this.controller, // 滚动控制器
  this.physics, // 滚动物理效果
  this.scrollBehavior, // 平台自适应滚动行为
  this.dragStartBehavior = DragStartBehavior.start, // 手势处理方式
  this.restorationId, // 状态恢复标识
  this.scrollDirection = Axis.vertical, // 滚动轴（已弃用，优先用 axisDirection）
})

属性

属性名	属性类型	说明
`axisDirection`	`AxisDirection`	滚动方向（默认 `AxisDirection.down`）。
`controller`	`ScrollController?`	控制滚动位置和监听事件。
`physics`	`ScrollPhysics?`	定义滚动物理效果（如弹性、阻尼）。
`viewportBuilder`	`ViewportBuilder`	构建滚动内容的回调函数（必需）。
`scrollBehavior`	`ScrollBehavior?`	平台自适应滚动行为（如桌面端显示滚动条）。
`dragStartBehavior`	`DragStartBehavior`	手势识别起始行为（默认 `DragStartBehavior.start`）。
`restorationId`	`String?`	用于状态恢复的标识符。

关键属性详解

viewportBuilder: 这是Scrollable的核心属性，必须返回一个Viewport组件。Viewport通过Sliver机制管理子组件的布局和渲染，确保滚动时仅渲染可见区域，提升性能。

示例:

viewportBuilder: (context, offset) => Viewport(
  offset: offset, // 传入滚动偏移量
  slivers: [SliverList(...)], // 使用 Sliver 组件
)

physics: 控制滚动行为的物理效果，常见选项包括:
- BouncingScrollPhysics: iOS风格弹性效果。
- ClampingScrollPhysics: Android风格clamping效果(默认)。
- FixedScrollPhysics: 禁用用户滚动，但允许编程控制。性能影响：复杂的物理效果(如SpringPhysics)可能增加计算开销，在低端设备上需谨慎使用。
controller: ScrollController用于编程控制滚动(如jumpTo()、animateTo())，并监听滚动事件(如偏移量变化)。

注意: 多个Scrollable组件共享同一controller时，需确保方向一致，否则可能引发异常。

LongPressDraggable

路由