Flutter分页构建项插件 paginated_items_builder 的使用

PaginatedItemsBuilder 是一个用于处理Flutter应用中分页数据展示的插件，支持内部或外部状态管理，内置了加载动画和错误处理等功能。以下是如何使用这个插件的详细指南。

添加依赖

首先，在你的 pubspec.yaml 文件中添加 paginated_items_builder 作为依赖：

dependencies:
  flutter:
    sdk: flutter

  paginated_items_builder:

使用示例

示例1：带有控制器的状态管理

假设你有一个博客文章列表的数据源，可以按照如下方式实现：

定义控制器和API函数

在控制器中定义一个变量来存储博客文章的响应，并提供一个公共getter以便在UI中访问。

class PostsController with ChangeNotifier {
  PaginatedItemsResponse<Post>? _postsResponse;

  PaginatedItemsResponse<Post>? get postsResponse => _postsResponse;

  Future<PaginatedItemsResponse<Post>?> updatePosts({bool reset = false}) async {
    final res = await apiFunction(
      startKey: reset ? null : _postsResponse?.paginationKey,
    );

    if (reset || _postsResponse == null) {
      _postsResponse = res;
    } else {
      _postsResponse?.update(res);
    }
    notifyListeners();
    return _postsResponse;
  }

  Future<PaginatedItemsResponse<Post>> apiFunction({dynamic startKey}) async {
    final res = await _api.getPosts(startKey: startKey);

    return PaginatedItemsResponse<Post>(
      listItems: res.data?.posts,
      paginationKey: res.data?.paginationKey,
      idGetter: (post) => post.id,
    );
  }
}

在Widget树中使用

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final postsCon = Provider.of<PostsController>(context);

    return SafeArea(
      child: Scaffold(
        body: PaginatedItemsBuilder<Post>(
          response: postsCon.postsResponse,
          showLoaderOnResetGetter: (itemsFetchScope) => [
            ItemsFetchScope.noItemsRefresh,
            ItemsFetchScope.onErrorRefresh,
            ItemsFetchScope.pullDownToRefresh,
          ].contains(itemsFetchScope),
          fetchPageData: (reset) => postsCon.updatePosts(reset: reset),
          itemBuilder: (context, idx, post) => PostCard(post),
          loaderItemsCount: 12,
        ),
      ),
    );
  }
}

示例2：无控制器的状态管理

如果你不想使用控制器，可以直接在 PaginationItemsStateHandler 中处理状态：

Future<PaginatedItemsResponse<Post>> updatePosts(dynamic paginationKey) async {
  return await PostsRepository.getPosts(startKey: paginationKey);
}

@override
Widget build(BuildContext context) {
  return SafeArea(
    child: Scaffold(
      body: PaginationItemsStateHandler<Post>(
        fetchPageData: updatePosts,
        builder: (response, fetchPageData) {
          return PaginatedItemsBuilder<Post>(
            response: response,
            fetchPageData: fetchPageData,
            itemBuilder: (context, _, post) => PostCard(post),
            loaderItemsCount: 12,
          );
        },
      ),
    ),
  );
}

配置与自定义

你可以通过 PaginatedItemsBuilderConfig 来配置一些默认设置，例如模拟数据获取器、加载动画颜色等。

class MockItems {
  static dynamic getByType<T>([String? mockItemKey]) {
    final key = mockItemKey ?? T.toString();
    switch (key) {
      case 'Category':
        return _category;
    }
  }

  static final _category = Category.fromJson({
    'id': 'id',
    'name': '■■■■■■',
  });
}

MaterialApp(
  title: 'PaginatedItemsBuilder Demo',
  builder: (context, child) {
    late final Color shimmerBaseColor;
    late final Color shimmerHighlightColor;

    switch (Theme.of(context).brightness) {
      case Brightness.light:
        shimmerBaseColor = Colors.grey[300]!;
        shimmerHighlightColor = Colors.grey[100]!;
        break;
      case Brightness.dark:
        shimmerBaseColor = const Color(0xFF031956);
        shimmerHighlightColor = const Color(0x80031956);
        break;
    }

    PaginatedItemsBuilder.config = PaginatedItemsBuilderConfig(
      mockItemGetter: MockItems.getByType,
      shimmerConfig: ShimmerConfig(
        baseColor: shimmerBaseColor,
        highlightColor: shimmerHighlightColor,
        duration: const Duration(seconds: 1),
      ),
    );

    return child!;
  },
);