Riverpod 实战：优雅实现下拉刷新功能

Riverpod 实战：优雅实现下拉刷新功能

riverpod A simple way to access state while robust and testable. 项目地址: https://gitcode.com/gh_mirrors/ri/riverpod

下拉刷新（Pull-to-refresh）是现代移动应用中非常常见的交互模式，但实现起来却有不少技术细节需要考虑。本文将基于 Riverpod 状态管理库，手把手教你如何优雅地实现一个完整的下拉刷新功能。

下拉刷新的技术挑战

在实现下拉刷新时，我们通常会遇到以下几个技术难点：

1. 初始加载与刷新状态的区分：首次进入页面时应该显示加载指示器，而刷新时则应显示刷新指示器，两者不应同时出现
2. 数据连续性：刷新过程中应保留旧数据，而不是显示空白页面
3. 状态同步：刷新指示器需要与异步操作保持同步，确保指示器显示时长与刷新操作一致

项目准备：基础活动推荐应用

我们先构建一个简单的活动推荐应用作为基础，使用 Bored API 获取随机活动建议。

数据模型定义

首先定义活动数据模型：

@freezed
class Activity with _$Activity {
  factory Activity({
    required String key,
    required String activity,
    required double accessibility,
    required String type,
    required int participants,
    required double price,
  }) = _Activity;

  factory Activity.fromJson(Map<String, dynamic> json) =>
      _$ActivityFromJson(json);
}

这个模型使用 Freezed 和 json_serializable 实现 JSON 序列化/反序列化，虽然这不是必须的，但能大大简化开发工作。

数据获取逻辑

接下来创建获取活动数据的 Provider：

final activityProvider = FutureProvider<Activity>((ref) async {
  final response = await http.get(
    Uri.https('www.boredapi.com', '/api/activity'),
  );
  final json = jsonDecode(response.body) as Map<String, dynamic>;
  return Activity.fromJson(json);
});

这个 Provider 封装了 API 调用逻辑，返回一个 FutureProvider，非常适合处理异步数据获取。

基础界面实现

初始界面简单展示获取到的活动数据：

class ActivityView extends ConsumerWidget {
  const ActivityView({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final activity = ref.watch(activityProvider).valueOrNull;
    return Scaffold(
      appBar: AppBar(title: const Text('建议活动')),
      body: Center(
        child: Text(activity?.activity ?? '无活动'),
      ),
    );
  }
}

实现下拉刷新功能

添加 RefreshIndicator 组件

Material Design 提供了 RefreshIndicator 组件来实现下拉刷新效果。我们需要确保界面有可滚动区域：

body: RefreshIndicator(
  onRefresh: () => Future.value(),
  child: ListView(
    children: [
      Center(
        child: Text(activity?.activity ?? '无活动'),
      ),
    ],
  ),
),

实现刷新逻辑

关键点在于 onRefresh 回调的实现。我们需要：

1. 触发数据重新获取
2. 返回一个 Future，在数据加载完成后完成

onRefresh: () {
  return ref.refresh(activityProvider.future);
},

这里 ref.refresh 会强制 Provider 重新获取数据，而 .future 属性返回的 Future 会在新数据加载完成后完成。

完善状态处理

现在我们需要区分初始加载和刷新状态：

body: RefreshIndicator(
  onRefresh: () => ref.refresh(activityProvider.future),
  child: switch (ref.watch(activityProvider)) {
    AsyncData(:final valueOrNull?) => 
      ListView(children: [Center(child: Text(value.activity))]),
    AsyncError(:final error) => 
      Center(child: Text('错误: $error')),
    _ => const Center(child: CircularProgressIndicator()),
  },
),

这里使用了 Dart 3.0 的模式匹配语法，优雅地处理了各种状态：

• AsyncData：数据加载成功，显示内容
• AsyncError：加载失败，显示错误信息
• 其他状态（加载中）：显示加载指示器

完整实现代码

以下是整合了所有功能的完整实现：

// [完整代码示例，包含上述所有功能点]

最佳实践总结

1. 状态分离：Riverpod 的 AsyncValue 天然支持区分初始加载和刷新状态
2. 错误处理：始终考虑错误状态，提供良好的用户体验
3. 性能优化：使用 Freezed 等工具可以减少不必要的重建
4. 代码组织：将业务逻辑放在 Provider 中，保持 UI 层简洁

通过 Riverpod 的声明式特性，我们能够以非常直观的方式实现复杂的下拉刷新交互，同时保持代码的整洁和可维护性。这种模式可以轻松扩展到其他需要异步数据加载的场景中。

riverpod A simple way to access state while robust and testable. 项目地址: https://gitcode.com/gh_mirrors/ri/riverpod