Flutter分页搜索栏插件paginated_search_bar的使用

Flutter分页搜索栏插件paginated_search_bar的使用

paginated_search_bar 是一个用于在结果列表中搜索和分页项目的库。默认情况下，它看起来像这样：

它支持广泛的自定义功能，包括自定义样式、头部、占位符、尾部等，并且基于 Endless 无限滚动视图库。

基本用法

首先，我们来看一个基本的用法示例。在这个示例中，你需要提供一个用于获取数据的 onSearch 函数和一个用于显示搜索结果的 itemBuilder。

class ExampleItem {
  final String title;

  ExampleItem({
    required this.title,
  });
}

PaginatedSearchBar<ExampleItem>(
  onSearch: ({
    required pageIndex,
    required pageSize,
    required searchQuery,
  }) async {
    // 调用你的搜索API以返回一个项目列表
    return [
      ExampleItem(title: 'Item 0'),
      ExampleItem(title: 'Item 1'),
    ];
  },
  itemBuilder: (
    context, {
    required item,
    required index,
  }) {
    return Text(item.title);
  },
);

在基本用法中，你只需要提供一个 onSearch 函数来获取数据和一个 itemBuilder 来指定如何在搜索结果列表中显示每个项目。

高级用法

接下来，我们来看一个更高级的用法示例。在这个示例中，我们提供了更多的定制选项，例如 emptyBuilder 和 headerBuilderState。

PaginatedSearchBar<ExampleItem>(
  maxHeight: 300,
  hintText: 'Search',
  headerBuilderState: PaginatedSearchBarBuilderStateProperty.empty((context) {
    return const Text("我是一个仅在结果为空时显示的头部！");
  }),
  emptyBuilder: (context) {
    return const Text("我是一个空状态！");
  },
  paginationDelegate: EndlessPaginationDelegate(
    pageSize: 20,
    maxPages: 3,
  ),
  onSearch: ({
    required pageIndex,
    required pageSize,
    required searchQuery,
  }) async {
    return Future.delayed(const Duration(milliseconds: 1000), () {
      if (searchQuery == "empty") {
        return [];
      }

      return [
        ExampleItem(title: '第 $pageIndex 页项目 1'),
        ExampleItem(title: '第 $pageIndex 页项目 2'),
      ];
    });
  },
  itemBuilder: (
    context, {
    required item,
    required index,
  }) {
    return Text(item.title);
  },
);

在这个更高级的示例中，我们提供了一些更多的定制选项，包括 emptyBuilder 和 headerBuilderState。所有这些构建器函数都提供当前的 BuildContext 并返回要显示的 widget。每个构建器函数还有一个对应的 StateProperty 构建器，如我们在 headerBuilderState 中看到的那样。PaginatedSearchBar 库使用 State property 模式来根据系统的状态自定义 widget 的显示。

PaginatedSearchBar 的完整状态列表如下：

enum PaginatedSearchBarState {
  /// 当搜索栏正在搜索项目时出现。当用户更新他们的搜索查询时触发。
  searching,

  /// 当搜索栏正在获取项目页面时出现。这可能是由于修改了搜索查询或通过滚动到列表视图底部并触发下一页加载。
  loading,

  /// 当搜索栏没有与当前搜索查询匹配的项目时出现。
  empty,

  /// 当搜索栏没有更多项目可以获取时出现。当 `[PaginatedSearchBar.onSearch]` 函数返回少于 `[PaginatedSearchBar.pageLimit]` 个项目或 `[EndlessPaginationDelegate.maxPage]` 已达到且无法获取更多项目时触发。
  done,

  /// 当输入框当前处于焦点状态时出现。
  focused,
}

状态属性构建器让我们可以根据这些状态自定义构建的内容。在上面的例子中，我们使用 headerBuilderState 指定了只有在搜索结果为空时才构建该 widget。

如果我们想要在搜索结果为空或完成时显示该 widget，我们可以使用 resolveWith 构建器：

PaginatedSearchBar<ExampleItem>(
  headerBuilderState: PaginatedSearchBarBuilderStateProperty.resolveWith((context, states) {
    if (states.contains(PaginatedSearchBarState.empty) || states.contains(PaginatedSearchBarState.done)) {
      return const Text("我是一个仅在结果为空或完成时显示的头部！");
    }
  }),
  onSearch: ({
    required pageIndex,
    required pageSize,
    required searchQuery,
  }) async {
    return Future.delayed(const Duration(milliseconds: 1000), () {
      if (searchQuery == "empty") {
        return [];
      }

      return [
        ExampleItem(title: '第 $pageIndex 页项目 1'),
        ExampleItem(title: '第 $pageIndex 页项目 2'),
      ];
    });
  },
  itemBuilder: (
    context, {
    required item,
    required index,
  }) {
    return Text(item.title);
  },
);

状态属性可用于 [PaginatedSearchBar] 的构建器和样式属性。

完整示例

下面是完整的示例代码，展示了如何使用 paginated_search_bar 插件。

import 'package:flutter/material.dart';
import 'package:paginated_search_bar/paginated_search_bar.dart';
import 'package:endless/endless.dart';

class ExampleItem {
  final String title;

  ExampleItem({
    required this.title,
  });
}

class ExampleItemPager {
  int pageIndex = 0;
  final int pageSize;

  ExampleItemPager({
    this.pageSize = 20,
  });

  List<ExampleItem> nextBatch() {
    List<ExampleItem> batch = [];

    for (int i = 0; i < pageSize; i++) {
      batch.add(ExampleItem(title: 'Item ${pageIndex * pageSize + i}'));
    }

    pageIndex += 1;

    return batch;
  }
}

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

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

  // This widget is the root of your application.
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  [@override](/user/override)
  Widget build(BuildContext context) {
    ExampleItemPager pager = ExampleItemPager();

    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Column(
        mainAxisAlignment: MainAxisAlignment.start,
        children: [
          Container(
            padding: const EdgeInsets.only(top: 200),
            alignment: Alignment.topCenter,
            child: SizedBox(
              width: 600,
              child: PaginatedSearchBar<ExampleItem>(
                maxHeight: 300,
                hintText: 'Search',
                emptyBuilder: (context) {
                  return const Text("我是一个空状态！");
                },
                placeholderBuilder: (context) {
                  return const Text("我是一个占位符状态！");
                },
                paginationDelegate: EndlessPaginationDelegate(
                  pageSize: 20,
                  maxPages: 3,
                ),
                onSearch: ({
                  required pageIndex,
                  required pageSize,
                  required searchQuery,
                }) async {
                  return Future.delayed(const Duration(milliseconds: 1300), () {
                    if (searchQuery == "empty") {
                      return [];
                    }

                    if (pageIndex == 0) {
                      pager = ExampleItemPager();
                    }

                    return pager.nextBatch();
                  });
                },
                itemBuilder: (
                  context, {
                  required item,
                  required index,
                }) {
                  return Text(item.title);
                },
              ),
            ),
          ),
        ],
      ),
    );
  }
}