Flutter列表工具插件listview_utils_plus的使用

简介

listview_utils_plus 是一个用于增强 Flutter 中 ListView 功能的插件。它通过自定义适配器（adapters）来实现无限滚动等功能，特别适用于需要从网络或数据库中分页加载大量数据的场景。

特性

• 无限滚动：自动处理分页逻辑，当用户滚动到底部时自动加载更多数据。
• 多种适配器支持：内置了网络适配器（NetworkListAdapter），也可以自定义适配器。
• 丰富的配置选项：支持头部、尾部、空状态、错误处理等自定义组件。
• 控制器支持：支持 Flutter 的 ScrollController 和自定义的 CustomListViewController。

安装

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

dependencies:
  listview_utils_plus: ">=0.0.1 <1.0.0"

然后运行 flutter pub get 来安装依赖。

使用示例

基本用法

以下是一个基本的示例，展示了如何使用 listview_utils_plus 创建一个带有网络适配器的 CustomListView。

import 'package:flutter/material.dart';
import 'package:listview_utils_plus/listview_utils_plus.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(
    const MaterialApp(
      title: 'Example',
      home: HomeScreen(),
    ),
  );
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('🔌 ListView Utils+')),
      body: SafeArea(
        child: CustomListView(
          paginationMode: PaginationMode.page,
          initialOffset: 0,
          loadingBuilder: CustomListLoading.defaultBuilder,
          header: const SizedBox(
            height: 50,
            child: Center(
              child: Text('😄 Header'),
            ),
          ),
          footer: const SizedBox(
            height: 50,
            child: Center(
              child: Text('🦶 Footer'),
            ),
          ),
          adapter: const NetworkListAdapter(
            url: 'https://jsonplaceholder.typicode.com/posts',
            limitParam: '_limit',
            offsetParam: '_start',
          ),
          itemBuilder: (context, _, item) {
            return ListTile(
              title: Text(item['title']),
              leading: const Icon(Icons.assignment),
            );
          },
          errorBuilder: (context, error, state) {
            return Column(
              children: <Widget>[
                Text(error.toString()),
                TextButton(
                  onPressed: () => state.loadMore(),
                  child: const Text('Retry'),
                ),
              ],
            );
          },
          separatorBuilder: (context, _) {
            return const Divider(height: 1);
          },
          empty: const Center(
            child: Text('Empty'),
          ),
        ),
      ),
    );
  }
}

配置选项

常见属性

• pageSize：每次请求获取的项目数量，默认为 30。
• header：列表头部的组件，默认为 null。
• footer：列表尾部的组件，默认为 null。
• empty：列表为空时显示的组件，默认为 null。
• adapter：数据适配器，用于从网络或数据库中获取数据。
• paginationMode：分页模式，可选值为 PaginationMode.offset 或 PaginationMode.page，默认为 PaginationMode.offset。
• initialOffset：初始偏移量，默认为 0。
• itemBuilder：构建列表项的回调函数，必须提供。
• errorBuilder：发生错误时的构建回调函数，默认为 null。
• itemCount：列表项总数，默认为 null。
• onRefresh：下拉刷新时的回调函数，默认为 null。
• disableRefresh：是否禁用下拉刷新，默认为 false。

适配器

目前 listview_utils_plus 只支持网络适配器 NetworkListAdapter，但你也可以通过实现 BaseListAdapter 混合类或使用 ListAdapter 类来自定义适配器。

NetworkListAdapter(
  url: 'https://jsonplaceholder.typicode.com/posts',
  limitParam: '_limit',
  offsetParam: '_start',
),

控制器

滚动控制器

listview_utils_plus 支持 Flutter 的 ScrollController，可以用来控制滚动位置。

class _SomeWidgetState extends State<SomeWidget> {
  ScrollController scrollController = ScrollController();

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        FlatButton(
          onPressed: () {
            scrollController.animateTo(100);
          },
          child: const Text('Scroll down'),
        ),
        Expanded(
          child: CustomListView(
            adapter: ...,
            scrollController: scrollController,
            itemBuilder: (context, index, dynamic item) {
              return ListTile(
                title: Text(item['title']),
              );
            },
          ),
        ),
      ],
    );
  }

  @override
  void dispose() {
    scrollController.dispose();
    super.dispose();
  }
}

列表控制器

listview_utils_plus 还支持自定义的 CustomListViewController，可以用来控制列表项，例如程序化刷新列表。

class _SomeWidgetState extends State<SomeWidget> {
  CustomListViewController listViewController = CustomListViewController();

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        FlatButton(
          onPressed: () {
            listViewController.refresh();
          },
          child: const Text('Refresh'),
        ),
        Expanded(
          child: CustomListView(
            adapter: ...,
            loadingBuilder: (context) => const Center(
              child: CircularProgressIndicator(),
            ),
            scrollController: scrollController,
            itemBuilder: (context, index, dynamic item) {
              return ListTile(
                title: Text(item['title']),
              );
            },
          ),
        ),
      ],
    );
  }

  @override
  void dispose() {
    listViewController.dispose();
    super.dispose();
  }
}

总结

listview_utils_plus 是一个非常强大的插件，可以帮助你在 Flutter 应用中轻松实现无限滚动和其他高级功能。通过自定义适配器和控制器，你可以灵活地处理各种数据源和用户交互。希望本文档能帮助你更好地理解和使用这个插件。