Flutter分页搜索插件paginated_search的使用

Flutter分页搜索插件paginated_search的使用

功能特性

• 显示加载项：在获取下一页数据时显示加载项。
• 自动加载下一页：当用户滚动到列表底部时，自动加载下一页（无限滚动）。
• 可定制化：可以自定义错误、加载和其他视图。
• 初始查询：可以通过设置初始查询，在视图初始化时加载数据。

入门指南

此插件依赖于 Riverpod，请确保你已经熟悉如何使用 Riverpod。

使用方法

1. 创建 SearchProvider

SearchProvider 提供搜索数据给分页控制器。你可以通过 PaginatedState 获取当前查询、当前页码、每页的项目数量等信息。

class MockSearchProvider extends SearchProvider<String, String> {
  [@override](/user/override)
  Future<List<String>> performSearch(Ref ref, PaginatedState<String, String> state) async {
    // 模拟网络请求延迟
    await Future.delayed(const Duration(milliseconds: 400));
    
    // 生成模拟数据
    return List.generate(
      state.pageSize, 
      (index) => '${state.query ?? "No Query"} - ${state.page * state.pageSize + index}'
    );
  }
}

2. 创建分页控制器

创建一个分页控制器，允许分页视图处理不同的流程。你可以指定一个初始查询，以便在视图初始化时加载初始页面的数据。

final paginatedSearchControllerProvider = createPaginatedController(
  searchProvider: MockSearchProvider(),
  initialQuery: "Initial Query"  // 初始查询
);

3. 创建分页搜索视图

现在你可以创建一个分页搜索视图。这个视图包含了搜索框、分页列表和底部加载指示器。

class MyHomePage extends PaginatedSearchView<String, String> {
  const MyHomePage({
    super.key,
    required super.paginatedController,
    super.invalidateOnDispose = false,
  });

  [@override](/user/override)
  ConsumerState<ConsumerStatefulWidget> createState() {
    return _MyHomePageState();
  }
}

class _MyHomePageState extends PaginatedSearchViewState<MyHomePage> with TickerProviderStateMixin {
  late final tabController = TabController(length: 2, vsync: this);

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: AnnotatedRegion<SystemUiOverlayStyle>(
        value: SystemUiOverlayStyle.dark,
        child: SafeArea(
          child: CustomScrollView(
            controller: paginatedScrollController,
            slivers: [
              // 标题
              Text(
                'Paginated Search',
                style: context.textTheme.headlineMedium.bold,
              ).withPadding(s16HorizontalPadding).asSliver,

              // 描述
              const Text('Search through your data easily')
                  .withPadding(s16HorizontalPadding)
                  .asSliver,

              // 搜索框
              TextField(
                onChanged: (value) =>
                    ref.read(paginatedSearchControllerProvider.notifier).search(query: value),
                decoration: const InputDecoration(
                  prefixIcon: Icon(Icons.search_rounded),
                  hintText: 'Search...',
                  filled: true,
                ),
              ).withPadding(s16HorizontalPadding).asSliver,

              // 分页列表
              PaginatedSliverListView(
                paginatedController: paginatedSearchControllerProvider,
                itemBuilder: (item) => Card(
                  elevation: 8,
                  child: Text(
                    item,
                    style: TextStyle(
                      color: context.colorScheme.onSecondaryContainer,
                      fontWeight: FontWeight.bold,
                    ),
                  ).withPadding(s24Padding),
                ).withPadding(s4Vertical8Horizontal),
                loadingBuilder: (_) => const CircularProgressIndicator.adaptive().alignCenter.asSliver,
                errorBuilder: (context, error, st) => const Text("Error happened").asSliver,
              ),

              // 底部加载指示器
              PaginatedBottomWidget(
                paginatedController: paginatedSearchControllerProvider,
                onGoingLoading: (context) => const CircularProgressIndicator.adaptive().alignCenter,
                onGoingErrorBuilder: (context, error, st) => const Text("Something went wrong").alignCenter,
              ).asSliver,
            ],
          ),
        ).withHeaderOverlayGlow(context: context),
      ),
    );
  }
}

4. 运行应用

最后，创建 MyApp 并运行应用。

void main() {
  runApp(const ProviderScope(child: MyApp()));
}

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      themeMode: ThemeMode.dark,
      darkTheme: ThemeData(
        brightness: Brightness.dark,
        useMaterial3: true,
        colorSchemeSeed: Colors.blue.shade900,
      ),
      debugShowCheckedModeBanner: false,
      home: MyHomePage(paginatedController: paginatedSearchControllerProvider),
    );
  }
}

完整示例代码

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:paginated_search/paginated_helpers.dart';
import 'package:paginated_search/paginated_search.dart';

void main() {
  runApp(const ProviderScope(child: MyApp()));
}

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      themeMode: ThemeMode.dark,
      darkTheme: ThemeData(
        brightness: Brightness.dark,
        useMaterial3: true,
        colorSchemeSeed: Colors.blue.shade900,
      ),
      debugShowCheckedModeBanner: false,
      home: MyHomePage(paginatedController: paginatedSearchControllerProvider),
    );
  }
}

final paginatedSearchControllerProvider =
    createPaginatedController(searchProvider: MockSearchProvider(), initialQuery: "Initial Query");

class MockSearchProvider extends SearchProvider<String, String> {
  [@override](/user/override)
  Future<List<String>> performSearch(Ref ref, PaginatedState<String, String> state) async {
    // 模拟网络请求延迟
    await Future.delayed(const Duration(milliseconds: 400));
    
    // 生成模拟数据
    return List.generate(
      state.pageSize, 
      (index) => '${state.query ?? "No Query"} - ${state.page * state.pageSize + index}'
    );
  }
}

class MyHomePage extends PaginatedSearchView<String, String> {
  const MyHomePage({
    super.key,
    required super.paginatedController,
    super.invalidateOnDispose = false,
  });

  [@override](/user/override)
  ConsumerState<ConsumerStatefulWidget> createState() {
    return _MyHomePageState();
  }
}

class _MyHomePageState extends PaginatedSearchViewState<MyHomePage> with TickerProviderStateMixin {
  late final tabController = TabController(length: 2, vsync: this);

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: AnnotatedRegion<SystemUiOverlayStyle>(
        value: SystemUiOverlayStyle.dark,
        child: SafeArea(
          child: CustomScrollView(
            controller: paginatedScrollController,
            slivers: [
              // 标题
              Text(
                'Paginated Search',
                style: context.textTheme.headlineMedium.bold,
              ).withPadding(s16HorizontalPadding).asSliver,

              // 描述
              const Text('Search through your data easily')
                  .withPadding(s16HorizontalPadding)
                  .asSliver,

              // 搜索框
              TextField(
                onChanged: (value) =>
                    ref.read(paginatedSearchControllerProvider.notifier).search(query: value),
                decoration: const InputDecoration(
                  prefixIcon: Icon(Icons.search_rounded),
                  hintText: 'Search...',
                  filled: true,
                ),
              ).withPadding(s16HorizontalPadding).asSliver,

              // 分页列表
              PaginatedSliverListView(
                paginatedController: paginatedSearchControllerProvider,
                itemBuilder: (item) => Card(
                  elevation: 8,
                  child: Text(
                    item,
                    style: TextStyle(
                      color: context.colorScheme.onSecondaryContainer,
                      fontWeight: FontWeight.bold,
                    ),
                  ).withPadding(s24Padding),
                ).withPadding(s4Vertical8Horizontal),
                loadingBuilder: (_) => const CircularProgressIndicator.adaptive().alignCenter.asSliver,
                errorBuilder: (context, error, st) => const Text("Error happened").asSliver,
              ),

              // 底部加载指示器
              PaginatedBottomWidget(
                paginatedController: paginatedSearchControllerProvider,
                onGoingLoading: (context) => const CircularProgressIndicator.adaptive().alignCenter,
                onGoingErrorBuilder: (context, error, st) => const Text("Something went wrong").alignCenter,
              ).asSliver,
            ],
          ),
        ).withHeaderOverlayGlow(context: context),
      ),
    );
  }
}