Flutter下拉刷新上拉加载侧拉刷新插件：easy_refresh全面使用指南

easy_refresh 是 Flutter 生态中一款功能强大、高度可定制的下拉刷新与上拉加载更多插件，相比 Flutter 原生RefreshIndicator，它支持更多刷新样式、自定义动画、多状态切换等高级特性，已成为 Flutter 项目中处理刷新加载场景的首选方案之一。

1. 快速集成

在项目pubspec.yaml文件中添加最新版本依赖，可前往 pub.dev 查看最新版本：

dependencies:flutter:sdk:fluttereasy_refresh:^3.9.0# 以实际最新版本为准

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

import'package:easy_refresh/easy_refresh.dart';

2. 核心 API 介绍

以下表格汇总了 easy_refresh 的核心 API、功能说明及使用方式，覆盖核心组件与关键配置：

3. 常用内置样式

easy_refresh 提供了多种开箱即用的头部/底部样式，满足大部分常规场景需求，核心样式如下：

4. 完整使用案例

以下案例实现了一个带下拉刷新、上拉加载更多的列表页面，包含数据模拟、状态控制、样式配置等核心功能，代码简洁可直接运行。

4.1. 完整代码

import'package:flutter/material.dart';import'package:easy_refresh/easy_refresh.dart';voidmain(){runApp(constMyApp());}classMyAppextendsStatelessWidget{constMyApp({super.key});@overrideWidgetbuild(BuildContextcontext){returnMaterialApp(title:'easy_refresh 使用案例',theme:ThemeData(primarySwatch:Colors.blue),home:constEasyRefreshDemo(),);}}classEasyRefreshDemoextendsStatefulWidget{constEasyRefreshDemo({super.key});@overrideState<EasyRefreshDemo>createState()=>_EasyRefreshDemoState();}class_EasyRefreshDemoStateextendsState<EasyRefreshDemo>{// 1. 初始化 EasyRefresh 控制器finalEasyRefreshController_controller=EasyRefreshController();// 列表数据List<String>_listData=[];// 当前页码int _currentPage=1;// 每页数据量staticconstint _pageSize=10;@overridevoidinitState(){super.initState();// 初始化加载第一页数据_loadRefreshData();}// 2. 下拉刷新数据逻辑（重置页码，重新加载第一页）Future<void>_loadRefreshData()async{try{// 模拟网络请求延迟awaitFuture.delayed(constDuration(seconds:1));// 重置页码_currentPage=1;// 模拟数据List<String>newData=List.generate(_pageSize,(index)=>"刷新数据${index+1}");setState((){_listData=newData;});// 结束刷新状态（成功）_controller.finishRefresh(RefreshResult.success);}catch(e){// 结束刷新状态（失败）_controller.finishRefresh(RefreshResult.fail);if(mounted){ScaffoldMessenger.of(context).showSnackBar(constSnackBar(content:Text("刷新失败，请重试！")),);}}}// 3. 上拉加载更多数据逻辑（页码+1，加载下一页）Future<void>_loadMoreData()async{try{// 模拟网络请求延迟awaitFuture.delayed(constDuration(seconds:1));// 页码+1_currentPage++;// 模拟数据List<String>moreData=List.generate(_pageSize,(index)=>"加载数据${(_currentPage-1)*_pageSize+index+1}");setState((){_listData.addAll(moreData);});// 模拟无更多数据（第3页后无更多）if(_currentPage>=3){_controller.finishLoad(LoadResult.noMore);}else{_controller.finishLoad(LoadResult.success);}}catch(e){// 结束加载状态（失败）_controller.finishLoad(LoadResult.fail);// 页码回退_currentPage--;if(mounted){ScaffoldMessenger.of(context).showSnackBar(constSnackBar(content:Text("加载失败，请重试！")),);}}}@overridevoiddispose(){// 释放控制器资源_controller.dispose();super.dispose();}@overrideWidgetbuild(BuildContextcontext){returnScaffold(appBar:AppBar(title:constText("easy_refresh 示例")),body:EasyRefresh(// 控制器controller:_controller,// 下拉头部样式header:ClassicHeader(refreshText:"下拉可刷新",refreshingText:"正在刷新...",refreshedText:"刷新完成",textColor:Colors.black87,),// 上拉底部样式footer:ClassicFooter(loadText:"上拉可加载",loadingText:"正在加载...",loadedText:"加载完成",noMoreText:"已加载全部数据",textColor:Colors.black87,),// 下拉刷新回调onRefresh:_loadRefreshData,// 上拉加载回调onLoad:_loadMoreData,// 启用刷新/加载enableRefresh:true,enableLoad:true,// 列表内容child:ListView.builder(itemCount:_listData.length,itemBuilder:(context,index){returnListTile(title:Text(_listData[index]),leading:CircleAvatar(child:Text("${index+1}")),);},),),);}}

4.2. 案例说明

1. 控制器使用：通过EasyRefreshController手动控制刷新/加载状态，避免异步请求后状态未及时更新的问题；
2. 数据模拟：使用Future.delayed模拟网络请求延迟，List.generate生成测试数据，可直接替换为真实接口请求；
3. 状态处理：区分刷新/加载的成功、失败、无更多三种状态，提升用户体验；
4. 样式自定义：通过ClassicHeader/ClassicFooter自定义提示文字与文字颜色，适配不同主题风格；
5. 资源释放：在dispose方法中释放控制器资源，避免内存泄漏。

5. 核心特性总结

1. 高度可定制：支持自定义头部/底部样式、刷新动画、触发阈值等，满足个性化需求；
2. 功能全面：支持下拉刷新、上拉加载、手动触发刷新/加载、无更多数据状态提示等；
3. 性能优异：滚动监听优化，无冗余渲染，适配 ListView/GridView/ScrollView 等所有滚动组件；
4. 兼容性好：支持 Flutter 多平台（Android、iOS、Web、桌面端），兼容最新 Flutter 版本。

6. 扩展使用

• 自定义头部/底部：继承Header/Footer类，实现自定义布局与动画，满足特殊UI需求；
• 嵌套滚动支持：适配NestedScrollView，可实现折叠导航栏+下拉刷新的组合场景；
• 全局配置：通过EasyRefresh.defaultHeader/EasyRefresh.defaultFooter设置全局默认样式，减少重复代码。

7. 总结

easy_refresh是Flutter开发中轻量化、高适配、易拓展的下拉刷新与上拉加载插件，相比原生刷新组件，它解决了样式单一、状态控制繁琐、多端适配差的痛点，核心优势与使用要点总结如下：

1. 接入成本极低，仅需三步即可实现基础刷新加载功能，代码简洁无冗余，新手也能快速上手；
2. 内置多款开箱即用的刷新/加载样式，同时支持高度自定义头部、底部布局与动画，适配各类UI设计需求；
3. 提供完善的控制器API，可灵活实现手动触发刷新、多状态（成功/失败/无更多）管控，满足复杂业务场景；
4. 全平台兼容，适配Android、iOS、Web及桌面端，且性能优异，无冗余渲染，不影响列表滚动流畅度；
5. 支持嵌套滚动、全局样式配置等高级能力，可在项目中全局统一刷新风格，大幅减少重复开发工作。

该插件能完美覆盖Flutter项目中列表刷新、分页加载、数据重载等核心场景，是处理滚动刷新加载需求的最优选择之一。

7.1. 引用来源

1. easy_refresh 官方仓库：GitHub - flutter_easyrefresh
2. Flutter 官方包管理平台文档：pub.dev - easy_refresh
3. 官方接口参考文档：easy_refresh API 文档
4. 官方在线演示地址：easy_refresh 示例演示

本次分享就到这儿啦，我是鹏多多，深耕前端的技术创作者，如果您看了觉得有帮助，欢迎评论，关注，点赞，转发，我们下次见~

PS：在本页按F12，在console中输入document.querySelectorAll('.tool-item-href')[0].click()，有惊喜哦~

往期文章

• flutter图片选择库multi_image_picker_plus和image_picker的对比和使用解析

• Flutter框架GetX从入门到精通第一篇：初识GetX与环境搭建

• Flutter框架GetX从入门到精通第二篇：路由管理-告别繁琐的Navigator

• Flutter框架GetX从入门到精通第四篇：深入GetxController与生命周期

• 解锁flutter弹窗新姿势：dialog-flutter_smart_dialog插件解读+案例

• Flutter输入框TextField的属性与实战用法全面解析+示例

• Flutter屏幕自适应解决方案：flutter_screenutil全面指南

• Flutter应用商店评分功能实现：rate_my_app插件完全指南

• Flutter网络请求库Dio详解：强大的HTTP客户端解决方案

• flutter-使用flutter_animate制作各种动画

• flutter-使用url_launcher打开链接/应用/短信/邮件和评分跳转等

• flutter-获取父容器宽高及设置子元素百分比尺寸的教程

• flutter-本地存储和数据持久化全解析

• flutter-使用extended_image操作图片的加载和状态处理以及缓存和下载

• flutter-制作可缩放底部弹出抽屉评论区效果

• flutter-实现Tabs吸顶的PageView效果

• 纯前端人脸识别利器：face-api.js手把手深入解析教学

个人主页

• CSDN
• GitHub
• 掘金