Flutter偏移迭代器插件offset_iterator的使用

OffsetIterator 是一个基于偏移量的异步可迭代对象，用于实现真正的拉取式数据流。灵感来源于 Apache Kafka。

适用场景

• 基于 IO 的数据流
• 分页 API 调用

示例

以下是一个从测试用例中提取的示例，该示例从一个虚拟 API 中获取最多 5 页的数据。你可以在这里查看测试用例。

注意，它只会调用一次 fetchPage，因为我们只请求了一页。

Future<String> fetchPage(int page) async {
  print('Fetching page $page!');
  await Future.delayed(const Duration(milliseconds: 50));
  return 'page content $page';
}

final i = OffsetIterator(
  init: () => 1, // 从第 1 页开始
  process: (nextPage) async {
    final pageContent = await fetchPage(nextPage);
    return OffsetIteratorState(
      acc: nextPage + 1, // 设置下一个累加器/游标
      chunk: [pageContent], // 添加页面内容
      hasMore: nextPage < 5, // 我们只需要 5 页
    );
  },
);

final firstPage = await i.pull();
print(firstPage.toNullable());

// 在日志中：
// "Fetching page 1!"
// "page content 1"

在 Flutter 中使用

有一个名为 offset_iterator_builder 的包可用。你可以在这里查看该包。

此包可用于从 OffsetIterator 的值构建小部件。builder 函数会接收当前的 BuildContext、迭代器的最新值以及一个用于请求更多数据的 pull 函数。

builder 提供了一个 withValue 辅助函数，使使用状态更加方便！

class MyList extends StatelessWidget {
  MyList({Key? key, required this.iterator}) : super(key: key);

  final OffsetIterator<List<int>> iterator;

  @override
  Widget build(BuildContext context) => OffsetIteratorBuilder(
    iterator: iterator,
    builder: (context, value, pull) => withValue(value)(
      data: (listOfNumbers, hasMore) => Text('I have ${listOfNumbers.length} numbers!'),
      loading: () => Text('Loading...'),
      error: (err) => Text('Error: $err'),
    ),
  );
}

完整示例

以下是一个完整的示例，展示了如何在 Flutter 应用中使用 OffsetIterator 和 OffsetIteratorBuilder。

main.dart

import 'package:flutter/material.dart';
import 'package:offset_iterator/offset_iterator.dart';
import 'package:offset_iterator_builder/offset_iterator_builder.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Offset Iterator Example')),
        body: MyList(),
      ),
    );
  }
}

class MyList extends StatefulWidget {
  @override
  _MyListState createState() => _MyListState();
}

class _MyListState extends State<MyList> {
  late final OffsetIterator<String> _iterator;

  @override
  void initState() {
    super.initState();
    _iterator = paginatedIterator();
  }

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

  @override
  Widget build(BuildContext context) {
    return OffsetIteratorBuilder(
      iterator: _iterator,
      builder: (context, value, pull) => withValue(value)(
        data: (pages, hasMore) => ListView.builder(
          itemCount: pages.length,
          itemBuilder: (context, index) {
            return ListTile(title: Text(pages[index]));
          },
        ),
        loading: () => Center(child: CircularProgressIndicator()),
        error: (err) => Center(child: Text('Error: $err')),
      ),
    );
  }
}

/// 模拟 API 请求
Future<String?> fetchPage(int page) async {
  await Future.delayed(const Duration(milliseconds: 50));
  if (page > 5) return null;
  return 'page $page content';
}

/// 创建分页迭代器
OffsetIterator<String> paginatedIterator() => OffsetIterator(
      // 从第 1 页开始
      init: () => 1,
      process: (page) async {
        // 获取下一页的内容
        final content = await fetchPage(page);

        // 返回 OffsetIteratorState
        return OffsetIteratorState(
          // 增加页码
          acc: page + 1,
          // 返回页面内容
          chunk: content != null ? [content] : [],
          // 如果内容为空，则没有更多内容
          hasMore: content != null,
        );
      },
    );

依赖项

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

dependencies:
  flutter:
    sdk: flutter
  offset_iterator: ^0.0.1
  offset_iterator_builder: ^0.0.1

运行应用

运行上述代码后，你将看到一个列表，显示从虚拟 API 获取的页面内容。每当你滚动到底部时，OffsetIterator 会自动请求下一页的内容，并将其添加到列表中。

希望这个示例能帮助你更好地理解和使用 OffsetIterator 插件！