Flutter智能滚动插件smart_scroll的使用

重要性

由于与dart版本更新有关的问题，请重复使用smart_scroll。

特性

• 拉起加载和下拉刷新
• 几乎适用于所有滚动小部件，如GridView、ListView等
• 提供全局默认指示器和属性设置
• 提供一些最常用的指示器
• 支持Android和iOS的默认ScrollPhysics，可以控制过冲距离、自定义弹簧动画、阻尼、速度等
• 横向和纵向刷新，支持反向ScrollView（四个方向）

使用方法

添加依赖

在pubspec.yaml文件中添加以下依赖：

dependencies:
  smart_scroll: ^0.0.2

导入包

在需要使用的文件中导入包：

import 'package:smart_scroll/smart_scroll.dart';

示例代码

import 'package:flutter/material.dart';
import 'package:smart_scroll/smart_scroll.dart';

void main() {
  runApp(const MyApp());
}

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});
  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  List<String> items = ["1", "2", "3", "4", "5", "6", "7", "8"];
  final RefreshController _refreshController = RefreshController(initialRefresh: false);

  void _onRefresh() async {
    // 监控网络请求
    await Future.delayed(const Duration(milliseconds: 1000));
    // 如果失败，使用 refreshFailed()
    _refreshController.refreshCompleted();
  }

  void _onLoading() async {
    // 监控网络请求
    await Future.delayed(const Duration(milliseconds: 1000));
    // 如果失败，使用 loadFailed()，如果没有数据返回，使用 LoadNodata()
    items.add((items.length + 1).toString());
    if (mounted) setState(() {});
    _refreshController.loadComplete();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: SmartScroll(
        enablePullDown: true,
        enablePullUp: true,
        header: const WaterDropHeader(),
        controller: _refreshController,
        onRefresh: _onRefresh,
        onLoading: _onLoading,
        child: ListView.builder(
          itemBuilder: (c, i) => Card(child: Center(child: Text(items[i]))),
          itemExtent: 100.0,
          itemCount: items.length,
        ),
      ),
    );
  }
}

全局配置

RefreshConfiguration用于配置所有子树下的Smart Refresher。通常存储在MaterialApp的根节点，并且用法类似于ScrollConfiguration。

// 子树下的Smart Refresher，这里有几个特别重要的属性
RefreshConfiguration(
  headerBuilder: () => WaterDropHeader(), // 配置默认头部指示器。如果每个页面有相同的头部指示器，则需要设置此属性
  footerBuilder: () => ClassicFooter(), // 配置默认底部指示器
  headerTriggerDistance: 80.0, // 头部触发刷新的距离
  springDescription: SpringDescription(stiffness: 170, damping: 16, mass: 1.9), // 自定义回弹动画，属性含义见flutter api
  maxOverScrollExtent: 100, // 头部的最大拖动范围。如果发生视图区域外的冲出，则设置此属性
  maxUnderScrollExtent: 0, // 底部的最大拖动范围
  enableScrollWhenRefreshCompleted: true, // 此属性与PageView和TabBarView不兼容。如果需要TabBarView左右滑动，则需要将其设置为true
  enableLoadingWhenFailed: true, // 在加载失败的情况下，用户仍然可以通过手势向上拉动来触发更多加载
  hideFooterWhenNotFull: false, // 当Viewport小于一个屏幕时，禁用向上拉动加载更多功能
  enableBallisticLoad: true, // 通过BallisticScrollActivity触发更多加载
  child: MaterialApp(
    // ...
  )
);

国际化

从1.5.6开始，增加了一个新特性：国际化。你可以在MaterialApp或CupertinoApp中添加以下代码：

MaterialApp(
  localizationsDelegates: [
    // 这一行很重要
    RefreshLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalMaterialLocalizations.delegate
  ],
  supportedLocales: [
    const Locale('en'),
    const Locale('zh'),
  ],
  localeResolutionCallback: (Locale locale, Iterable<Locale> supportedLocales) {
    // print("change language");
    return locale;
  },
)

关于SmartScroll的child解释

从1.4.3开始，child属性从ScrollView更改为Widget，但这并不意味着所有小部件都会以相同的方式处理。SmartScroll的内部实现机制不同于NestedScrollView。

这里有两种主要的处理机制：

• 第一类是继承自ScrollView的组件。目前只有三种类型：ListView、GridView和CustomScrollView。
• 第二类是非继承自ScrollView的组件，通常放置空视图、不可滚动视图（将可滚动视图转换为不可滚动视图）、PageView，并且不需要自己估计高度。

对于第一种机制，组件会非法地取出系统中的slivers。第二种机制是直接将子组件放入类如SliverToBoxAdapter中。通过拼接头部和尾部形成slivers，然后将这些slivers放入CustomScrollView中。你可以理解SmartRefresher作为CustomScrollView的一部分，因为内部返回的是CustomScrollView。因此，child节点与ScrollView有很大的不同。

例如：

// 错误
SmartScroll(
  child: ScrollBar(
    child: ListView(
      // ...
    )
  )
)

// 正确
ScrollBar(
  child: SmartScroll(
    child: ListView(
      // ...
    )
  )
)

错误示范：将ScrollView放在另一个组件中

// 错误
SmartScroll(
  child: MainView()
)

class MainView extends StatelessWidget {
  [@override](/user/override)
  Widget build() {
    return ListView(
      // ...
    );
  }
}