Flutter列表管理插件 flutter_bloc_list_manager 的使用

flutter_bloc_list_manager 是一个基于 flutter_bloc 构建的Flutter包，它简化了对列表项进行过滤和搜索的管理，使你能够专注于构建用户界面。本文将详细介绍如何使用该插件，并提供完整的示例代码。

Widgets

ListManager Widget

ListManager 是访问此包提供的 blocs 的入口点。不需要手动创建其他 blocs，它们都可以在 ListManager 小部件下从 build context 中获取。

参数

• I: 存储列表数据的类（实现 ItemClassWithAccessor）
• T: 包含加载项目的状态（实现 ItemSourceState）
• B: 包含上述状态的 bloc

示例

BlocProvider<SourceBloc>(
  create: (_) => SourceBloc(),
  child: ListManager<ItemClass, SourceLoaded, SourceBloc>(
    filterProperties: const ['property1'],
    searchProperties: const ['property2'],
    child: Column(
      children: [
        BlocBuilder<FilterConditionsBloc, FilterConditionsState>(
          builder: (context, state) {
            return const Text('Render filter conditions UI.');
          },
        ),
        BlocBuilder<SearchQueryCubit, String>(
          builder: (context, state) {
            return const Text('Render Search UI.');
          },
        ),
        BlocBuilder<ItemListBloc, ItemListState>(
          builder: (context, state) {
            return const Text('Render list UI.');
          },
        ),
      ],
    ),
  ),
)

FilterConditionsBloc

用于渲染过滤条件UI的状态。当源bloc更新时，过滤条件会自动更新。

示例

BlocBuilder<FilterConditionsBloc, FilterConditionsState>(
  builder: (_, state) {
    if (state is ConditionsInitialized) {
      return ListView.builder(
        itemCount: state.availableConditions.length,
        itemBuilder: (_, index) {
          final condition = state.availableConditions.entries.elementAt(index);
          return Column(
            children: [
              Text(condition.key),
              ...condition.value.map(
                (value) => Text(value),
              ),
            ],
          );
        },
      );
    }

    return CircularProgressIndicator();
  },
)

SearchQueryCubit

负责设置或清除驱动列表搜索的查询。

示例

context.read<SearchQueryCubit>().setQuery('query');
context.read<SearchQueryCubit>().clearQuery();

ItemListBloc

负责连接所有其他 blocs，执行实际的过滤和搜索，并提供状态以渲染列表UI。

示例

BlocBuilder<ItemListBloc, ItemListState>(
  builder: (_, state) {
    if (state is NoSourceItems) {
      return const Text('No source items');
    }

    if (state is ItemEmptyState) {
      return const Text('No matching results');
    }

    if (state is ItemResults<ItemClass>) {
      return ListView(
        children: state.items
            .map(
              (item) => ListTile(
                key: ValueKey(item.id),
                title: Text(item.name),
              ),
            )
            .toList(),
      );
    }

    return Container();
  },
)

数据类

为了正确管理列表中的数据，需要一些设置步骤。

ItemClassWithAccessor

用于存储列表中单个项目的类必须为任何需要动态访问的数据（无论是通过过滤还是搜索）提供属性访问器。

示例

class ItemClass extends Equatable implements ItemClassWithAccessor {
  final String id;
  final String name;

  const ItemClass({
    required this.id,
    required this.name,
  });

  @override
  List<Object> get props => [id, name];

  dynamic operator [](String prop) {
    switch (prop) {
      case 'id':
        return id;
      case 'name':
        return name;
      default:
        throw ArgumentError('Property `$prop` does not exist on ItemClass.');
    }
  }
}

ItemSourceState

你需要自由管理你的源 bloc，唯一的要求是源 bloc 的一个状态必须实现 ItemSourceState。

示例

class SourceLoaded extends SourceBlocState implements ItemSourceState<ItemClass> {
  final items;

  const SourceLoaded(this.items);

  @override
  List<Object> get props => [items];
}

完整示例 Demo

以下是一个完整的示例，展示了如何使用 flutter_bloc_list_manager 插件来实现一个包含搜索栏、过滤条件管理和列表渲染的基本UI。

import 'package:equatable/equatable.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_bloc_list_manager/flutter_bloc_list_manager.dart';

void main() {
  runApp(
    BlocProvider<JournalEntryBloc>(
      create: (_) => JournalEntryBloc()..add(LoadJournalEntry()),
      child: MaterialApp(
        title: 'Flutter Bloc List Manager',
        home: Scaffold(
          appBar: AppBar(
            title: const Text('Flutter Bloc List Manager'),
          ),
          body: ListManager<JournalEntry, Loaded, JournalEntryBloc>(
            filterProperties: const ['author', 'category', 'isPublished'],
            searchProperties: const ['content', 'description', 'title'],
            child: Column(
              children: [
                Row(
                  mainAxisSize: MainAxisSize.max,
                  mainAxisAlignment: MainAxisAlignment.spaceBetween,
                  children: const [
                    SearchInput(),
                    FilterConditionsLauncher(),
                  ],
                ),
                const SizedBox(height: 10.0),
                const Expanded(
                  child: ItemListRenderer(),
                ),
              ],
            ),
          ),
        ),
      ),
    ),
  );
}

// 其他部分如 JournalEntry 类、JournalEntryBloc 等定义请参考上方的详细代码段。