Flutter状态管理架构插件 bloc_toolkit 的使用

bloc_toolkit 是一个用于在Flutter应用中高效灵活地进行状态管理的插件，基于Bloc模式。它旨在简化应用程序开发，提供高级功能如加载、重新加载、更新和初始化数据。

DataBloc

DataBloc 类是该包的核心。这是一个通用类，提供了管理数据源状态的一整套工具，并设计为实现业务逻辑的基础类。

创建你的DataBloc

class AnimalBloc extends DataBloc<String, String> {
  AnimalBloc({required AnimalRepository animalRepository})
      : _animalRepository = animalRepository;
  final AnimalRepository _animalRepository;

  [@override](/user/override)
  FutureOr<String> loadData(DataS<String> oldState, LoadDataE<String> event) {
    return _animalRepository.getAnimal(event.params!);
  }
}

构建你的Widgets

BlocProvider(
  create: (_) => AnimalBloc(animalRepository: AnimalRepository()),
  child: BlocConsumer<AnimalBloc, DataS<String>>(
    listener: (context, state) {
      if (state is ErrorS<String>) {
        _showSnackBar(context, 'Loading animal error: ${state.error}');
      } 
    },
    builder: (context, state) {
      if (state is UnloadedDataS<String>) {
        return Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            const Text('Animal not loaded'),
            ElevatedButton(
              onPressed: () {
                context.read<AnimalBloc>().add(const LoadDataE(params: 'some args'));
              },
              child: const Text('Load Animal'),
            ),
          ],
        );
      }
      if (state is LoadingDataS<String>) {
        return const Text('Loading animal...');
      }
      if (state is LoadedDataS<String, String>) {
        return Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Text(state.data),
            ElevatedButton(
              onPressed: () {
                context.read<AnimalBloc>().add(const ReloadDataE(params: 'some args'));
              },
              child: const Text('Reload Animal'),
            ),
          ],
        );
      }
      if (state is ReloadingDataS<String, String>) {
        return const Text('Reloading animal...');
      }
      return const SizedBox();
    },
  ),
)

添加事件

final animalBloc = context.read<AnimalBloc>();

// 加载数据
animalBloc.add(const LoadDataE(params: 'some args'));       
// 或者 初始化数据
animalBloc.add(InitializeDataE('dog')) 

// 然后你可以
animalBloc.add(const ReloadDataE(params: 'some args')) 
// 或者 更新数据
animalBloc.add(UpdateDataE((currentData) => 'cat'));

状态

DataBloc 支持以下几种状态：

• 基础状态（Base States）

  • abstract DataS: 所有状态的基础。
  • abstract IdleS: 当没有事情发生时的状态。
  • abstract LoadingS: 数据正在加载或重新加载时的状态。
  • abstract ErrorS: 发生错误时的状态。

• 数据未加载状态（Data unloaded states）

  • UnloadedDataS: 初始状态，没有任何数据被加载。
  • LoadingDataS: 数据正在加载时的状态。
  • LoadingDataErrorS: 数据加载时发生错误的状态。

• 数据已加载状态（Data loaded states）

  • LoadedDataS: 数据成功加载或初始化成功的状态。
  • ReloadingDataS: 数据正在重新加载时的状态。
  • ReloadingDataErrorS: 数据重新加载时发生错误的状态。

错误处理

默认情况下，所有在数据加载期间抛出的错误都会转换为 DataException，可以在 LoadingDataErrorS 或 ReloadingDataErrorS 状态中接收。

如果你想在 BlocObserver.onError 中处理这些错误，可以通过覆盖 overridedOnLoadingError 和 overridedOnReloadingError 方法来改变这种行为。

void _$onLoadingError(
  DataException error,
  UnloadedDataS<String> state,
  Emitter<DataS<String>> emit, {
  String? params,
}) {
  if (error is UnhandledDataException) {
    throw error;
  }
  emit(LoadingDataErrorS(error, params: params));
  emit(const UnloadedDataS());
}

void _$onReloadingError(
  DataException error,
  LoadedS<String, String> state,
  Emitter<DataS<String>> emit, {
  String? params,
}) {
  if (error is UnhandledDataException) {
    throw error;
  }
  emit(ReloadingDataErrorS(state, error, params: params));
  emit(LoadedDataS(state.data, params: state.params));
}

class AnimalBloc extends DataBloc<String, String> {
  AnimalBloc({
    required AnimalRepository animalRepository,
    super.overridedOnLoadingError = _$onLoadingError,
    super.overridedOnReloadingError = _$onReloadingError,
  })
}

然后你可以在 BlocObserver.onError 中处理它们：

[@override](/user/override)
void onError(BlocBase bloc, Object error, StackTrace stackTrace) {
  super.onError(bloc, error, stackTrace);
  if (error is UnhandledDataException) {
    final originError = error.error;
    final originStackTrace = error.stackTrace;
    // send to sentry...
  }
}

ListBloc 和 SelectBloc

ListBloc 提供了对列表进行排序和过滤的功能。而 SelectBloc 实现了从列表中选择项目的便捷操作。

示例代码

下面是一个完整的示例，展示了如何使用 bloc_toolkit 插件：

import 'dart:async';
import 'package:bloc_toolkit/bloc_toolkit.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:logger/logger.dart';

void main() {
  final logger = Logger();
  Bloc.observer = SimpleBlocObserver(logger);
  runApp(const MyApp());
}

class AnimalBloc extends DataBloc<String, String> {
  AnimalBloc({required AnimalRepository animalRepository})
      : _animalRepository = animalRepository;
  final AnimalRepository _animalRepository;

  [@override](/user/override)
  FutureOr<String> loadData(DataS<String> oldState, LoadDataE<String> event) {
    return _animalRepository.getAnimal(event.params!);
  }
}

class SimpleBlocObserver extends BlocObserver {
  SimpleBlocObserver(this._logger);

  final Logger _logger;

  [@override](/user/override)
  void onChange(BlocBase bloc, Change change) {
    super.onChange(bloc, change);
    final nextState = change.nextState;
    if (nextState is ErrorS) {
      final error = nextState.error;
      if (error is UnhandledDataException) {
        _logger.f('UnhandledDataException',
            error: error.error, stackTrace: error.stackTrace);
        //TODO: send to analytics
      }
    }
  }
}

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

  [@override](/user/override)
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: HomeScreen(),
    );
  }
}

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

  void _showSnackBar(BuildContext context, String text) {
    ScaffoldMessenger.of(context).showSnackBar(SnackBar(
      backgroundColor: Colors.red,
      content: Text(text),
      duration: const Duration(milliseconds: 1000),
    ));
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: BlocProvider(
          create: (_) => AnimalBloc(animalRepository: AnimalRepository()),
          child: BlocConsumer<AnimalBloc, DataS<String>>(
            listener: (context, state) {
              if (state is ReloadingDataErrorS<String, String>) {
                _showSnackBar(
                    context, 'Reloading animal error: ${state.data}');
              } else if (state is LoadingDataErrorS<String, String>) {
                _showSnackBar(
                    context, 'Loading animal error: ${state.error}');
              }
            },
            builder: (context, state) {
              if (state is LoadingDataS<String>) {
                return const Text('Loading animal...');
              }
              if (state is UnloadedS<String>) {
                return Column(
                  mainAxisSize: MainAxisSize.min,
                  children: [
                    const Text('Animal not loaded'),
                    ElevatedButton(
                      onPressed: () {
                        context
                            .read<AnimalBloc>()
                            .add(const LoadDataE(params: 'some args'));
                      },
                      child: const Text('Load Animal'),
                    ),
                  ],
                );
              }
              if (state is LoadedDataS<String, String>) {
                return Column(
                  mainAxisSize: MainAxisSize.min,
                  children: [
                    Text(state.data),
                    ElevatedButton(
                      onPressed: () {
                        context
                            .read<AnimalBloc>()
                            .add(const ReloadDataE(params: 'some args'));
                      },
                      child: const Text('Reload Animal'),
                    ),
                  ],
                );
              }
              if (state is ReloadingDataS<String, String>) {
                return const Text('Reloading animal...');
              }
              return const SizedBox();
            },
          ),
        ),
      ),
    );
  }
}