Flutter分页加载工具插件riverpod_paging_utils的使用

riverpod_paging_utils 是一个为Flutter应用提供分页功能的工具包，基于Riverpod状态管理库。它包括一个通用的 PagingHelperView 小部件和用于基于页面、偏移量和游标的分页逻辑的混入（mixin）。

Demo

特性

• PagingHelperView: 简化Flutter应用中分页实现的通用小部件。
• PagePagingNotifierMixin: 用于实现基于页面的分页逻辑的混入。
• OffsetPagingNotifierMixin: 用于实现基于偏移量的分页逻辑的混入。
• CursorPagingNotifierMixin: 用于实现基于游标的分页逻辑的混入。

开始使用

安装

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

dependencies:
  riverpod_paging_utils: ^{latest}

然后运行 flutter pub get 来安装这个包。

使用示例

下面是一个如何使用 PagingHelperView 小部件与 Riverpod 提供者程序（使用 CursorPagingNotifierMixin 混入）的简单例子：

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_paging_utils/riverpod_paging_utils.dart';

// 假设 SampleItem 和 SampleRepository 已经定义
class SampleItem {
  final String id;
  final String name;

  SampleItem({required this.id, required this.name});
}

class SampleRepository {
  Future<(List<SampleItem>, String?)> getByCursor(String? cursor) async {
    // 实现获取数据的逻辑
    return ([], null);
  }
}

@riverpod
class SampleNotifier extends _$SampleNotifier with CursorPagingNotifierMixin<SampleItem> {
  @override
  Future<CursorPagingData<SampleItem>> build() => fetch(cursor: null);

  @override
  Future<CursorPagingData<SampleItem>> fetch({
    required String? cursor,
  }) async {
    final repository = SampleRepository();
    final (items, nextCursor) = await repository.getByCursor(cursor);
    final hasMore = nextCursor != null && nextCursor.isNotEmpty;

    return CursorPagingData(
      items: items,
      hasMore: hasMore,
      nextCursor: nextCursor,
    );
  }
}

final sampleNotifierProvider = SampleNotifier.new;

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Sample Screen'),
      ),
      body: PagingHelperView(
        provider: sampleNotifierProvider,
        futureRefreshable: sampleNotifierProvider.future,
        notifierRefreshable: sampleNotifierProvider.notifier,
        contentBuilder: (data, widgetCount, endItemView) => ListView.builder(
          itemCount: widgetCount,
          itemBuilder: (context, index) {
            if (index == widgetCount - 1) {
              return endItemView;
            }

            return ListTile(
              title: Text(data.items[index].name),
              subtitle: Text(data.items[index].id),
            );
          },
        ),
      ),
    );
  }
}

UI自定义

基本自定义

可以使用 ThemeExtension 轻松定制加载和错误状态的外观。例如，如果使用 loading_animation_widget 包，代码设置如下：

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        extensions: [
          PagingHelperViewTheme(
            loadingViewBuilder: (context) => Padding(
              padding: const EdgeInsets.all(16),
              child: Align(
                alignment: Alignment.topCenter,
                child: LoadingAnimationWidget.horizontalRotatingDots(
                  color: Colors.red,
                  size: 100,
                ),
              ),
            ),
            endLoadingViewBuilder: (context) =>
                LoadingAnimationWidget.threeArchedCircle(
              color: Colors.red,
              size: 50,
            ),
          ),
        ],
      ),
      home: const SampleScreen(),
    );
  }
}

高级自定义

如果需要更高级的自定义，比如集成 easy_refresh 包来提供刷新指示器，可以这样修改屏幕代码：

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

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Advanced UI Customization'),
      ),
      body: PagingHelperView(
        provider: sampleNotifierProvider,
        futureRefreshable: sampleNotifierProvider.future,
        notifierRefreshable: sampleNotifierProvider.notifier,
        contentBuilder: (data, widgetCount, endItemView) {
          return EasyRefresh(
            onRefresh: () async => ref.refresh(sampleNotifierProvider.future),
            child: ListView.builder(
              itemCount: widgetCount,
              itemBuilder: (context, index) {
                if (index == widgetCount - 1) {
                  return endItemView;
                }

                return ListTile(
                  title: Text(data.items[index].name),
                  subtitle: Text(data.items[index].id),
                );
              },
            ),
          );
        },
      ),
    );
  }
}

以上内容提供了完整的示例demo和详细的说明，帮助您快速上手并使用 riverpod_paging_utils 插件实现分页加载功能。