Flutter分页管理插件pagination_manager的使用

📦 Pagination Manager

这是一个强大且灵活的Flutter包，用于处理带有内置状态管理支持的分页数据。可以轻松实现无限滚动列表，同时减少样板代码。

✨ 特性

• 🚀 简单易用的分页管理
• 💪 内置Bloc/Cubit状态管理支持
• 🎯 框架无关 - 适用于任何状态管理解决方案
• 🔄 下拉刷新支持
• ⚡ 带有自动状态管理的懒加载
• 🎨 可定制的加载和错误状态
• 📱 响应式和自适应设计

📋 安装

在你的pubspec.yaml中添加以下依赖：

dependencies:
  pagination_manager: ^1.0.0

然后导入：

import 'package:pagination_manager/pagination_manager.dart';

🚀 快速开始

1. 创建一个Repository

首先，实现PaginatedRepository接口：

class MyDataRepository implements PaginatedRepository<MyData> {
  @override
  Future<PaginationResult<MyData>> fetchPaginatedItems(int page, int limitPerPage) async {
    try {
      final response = await api.fetchData(page: page, limit: limitPerPage);
      return PaginationResult.success(response);
    } catch (e) {
      return PaginationResult.failure(e.toString());
    }
  }
}

2. 初始化PaginationManager

final paginationManager = PaginationManager<MyData>(
  repository: MyDataRepository(),
  limitPerPage: 20,
);

3. 使用PaginatedManagerList（推荐）

最简单的方式是使用PaginatedManagerList来实现带有完整状态管理的分页：

PaginatedManagerList<MyData>(
  paginationManager: paginationManager,
  itemBuilder: (context, index, items) {
    final item = items[index];
    return ListTile(
      title: Text(item.title),
    );
  },
);

这将自动处理：

• 自动无限滚动
• 加载状态
• 错误处理与可自定义的重试按钮
• 下拉刷新
• 重试机制
• 空状态处理

自定义PaginatedManagerList

PaginatedManagerList<MyData>(
  paginationManager: paginationManager,
  itemBuilder: (context, index, items) => MyItemWidget(item: items[index]),
  // Customization options
  scrollThreshold: 0.8,                    // 在80%滚动时触发分页
  showRefreshIndicator: true,              // 启用下拉刷新
  showRetryButton: true,                   // 显示错误时的重试按钮
  emptyItemsText: 'No items found',        // 自定义空状态消息
  retryText: 'Try Again',                  // 自定义重试按钮文本
  scrollDirection: Axis.vertical,          // 滚动方向
  initialLoadingWidget: MyLoadingWidget(), // 自定义初始加载小部件
  loadingPaginationWidget: MyLoadingIndicator(), // 自定义分页加载指示器
  emptyItemsWidget: MyEmptyState(),        // 自定义空状态小部件
  whenErrMessageFromPagination: (message) {
    // 处理分页错误
    showSnackBar(message);
  },
  fetchItemsFailureWidget: (errorMessage) {
    // 自定义错误小部件
    return MyErrorWidget(message: errorMessage);
  },
  // 样式设置
  errorTextStyle: TextStyle(color: Colors.red),
  retryTextStyle: TextStyle(color: Colors.blue),
  retryButtonStyle: ButtonStyle(...),
);

4. 替代方案：手动实现

如果你需要更多控制，可以直接使用PaginatedList小部件：

PaginatedList<MyData>(
  paginationManager: paginationManager,
  loadingFromPaginationState: false,
  fetchNextPage: () => paginationManager.fetchNextPage(),
  itemBuilder: (context, index, items) {
    final item = items[index];
    return ListTile(
      title: Text(item.title),
    );
  },
  retryText: 'Try Again',
  onRefresh: () async {
    paginationManager.reset();
    await paginationManager.fetchNextPage();
  },
);

📖 API参考

PaginatedManagerList

PaginationManager

🤝 贡献

欢迎贡献！请随时提交Pull Request。

📄 许可证

本项目采用MIT许可证 - 详情见LICENSE文件。

示例代码

以下是pagination_manager插件的一个完整示例，展示如何在一个简单的应用中使用它。

// example/lib/main.dart
import 'package:flutter/material.dart';
import 'package:pagination_manager/pagination_manager.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Pagination Manager Example',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
        useMaterial3: true,
      ),
      home: const PostListScreen(),
    );
  }
}

// 示例数据模型
class Post {
  final int id;
  final String title;
  final String body;

  Post({
    required this.id,
    required this.title,
    required this.body,
  });

  factory Post.fromJson(Map<String, dynamic> json) {
    return Post(
      id: json['id'],
      title: json['title'],
      body: json['body'],
    );
  }
}

// 示例仓库实现
class PostsRepository implements PaginatedRepository<Post> {
  @override
  Future<PaginationResult<Post>> fetchPaginatedItems(
      int page, int limitPerPage) async {
    try {
      // 模拟API延迟
      await Future.delayed(const Duration(seconds: 2));
      // 计算分页的起始和结束索引
      final startIndex = (page - 1) * limitPerPage;
      final endIndex = startIndex + limitPerPage;
      // 模拟API响应的虚拟数据
      final List<Post> posts = List.generate(
        100,
        (index) => Post(
          id: index + 1,
          title: 'Post ${index + 1}',
          body: 'This is the body of post ${index + 1}.',
        ),
      );

      // 模拟分页逻辑
      // 截取列表以获取分页项目
      final paginatedPosts = posts.sublist(
        startIndex,
        endIndex > posts.length ? posts.length : endIndex,
      );

      return PaginationResult.success(paginatedPosts);
    } catch (e) {
      //return PaginationResult.failure(e.toString());
      return const PaginationResult.failure('An error while fetching.');
    }
  }
}

class PostListScreen extends StatefulWidget {
  const PostListScreen({super.key});

  @override
  State<PostListScreen> createState() => _PostListScreenState();
}

class _PostListScreenState extends State<PostListScreen> {
  late final PaginationManager<Post> _paginationManager;

  @override
  void initState() {
    super.initState();
    _paginationManager = PaginationManager<Post>(
      repository: PostsRepository(),
      limitPerPage: 10,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Posts'),
      ),
      body: PaginatedManagerList<Post>(
        paginationManager: _paginationManager,
        itemBuilder: (context, index, items) {
          final post = items[index];
          return Card(
            margin: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
            child: ListTile(
              title: Text(
                post.title,
                style: const TextStyle(fontWeight: FontWeight.bold),
              ),
              subtitle: Text(
                post.body,
                maxLines: 2,
                overflow: TextOverflow.ellipsis,
              ),
            ),
          );
        },
        // 自定义分页体验
        scrollThreshold: 0.8,
        showRefreshIndicator: true,
        emptyItemsText: 'No posts available',
        retryText: 'Try Again',
        // 处理分页错误
        whenErrMessageFromPagination: (message) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Error: $message')),
          );
        },
      ),
    );
  }
}

通过上述代码，您可以快速搭建一个具有分页功能的应用，并根据需要进行自定义和扩展。希望这对您有所帮助！