Bloc と Cubit

Spring for Dart で作る Flutter アプリは、パッケージ flutter_bloc の Bloc と Cubit に状態を置けます。フレームワークには Bloc のためのスターターがなく、必要もありません。Bloc はクラスなので、Bean です。依存関係はコンストラクターインジェクションで渡され、寿命はそのスコープで決まり、ウィジェットはコンテキストからそれを受け取って Bloc 自身のウィジェットに渡します。

このページの内容はすべて、フレームワークのリポジトリの例 example/bloc のコードです。下のオブザーバー、イベント、ミックスインはその例のコードで、アプリがコピーして使うものです。フレームワークの一部ではありません。

考え方

Bloc のアプリでは、BlocProvider が Bloc をウィジェットツリーに置いて閉じ、Bloc 自身の依存関係はリポジトリのプロバイダーやサービスロケーターから来ます。Spring のアプリでは、コンテナーがすでに両方の仕事をしています。

セットアップ

flutter_bloc はアプリ自身の依存関係です。例は、画面と route スコープのためにナビゲーションのスターターを使います。それが Flutter のスターターを連れてきます。

# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  flutter_bloc: ^9.1.1
  spring_boot_starter_flutter_navigation: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_boot_starter_test: ^0.9.0
  spring_core_dart_generator: ^0.9.0

アプリ全体のための Cubit

@Component() は Cubit を Bean にします。アプリケーションに一つ (シングルトン) です。それを求めるすべての画面が、同じカウントを受け取ります。

@Component()
class CounterCubit extends Cubit<int> with ClosedWithBean<int> {
  CounterCubit() : super(0);

  void increment() => emit(state + 1);

  void decrement() => emit(state - 1);

  @override
  String toString() => 'CounterCubit';
}

ウィジェットはコンテキストからそれを受け取り、BlocBuilder に渡します。

@override
Widget build(BuildContext context) {
  final counter = context.bean<CounterCubit>();
  return Row(
    mainAxisSize: MainAxisSize.min,
    children: [
      Tap('−', onTap: counter.decrement),
      // Bean を渡した Bloc 自身のウィジェット: 上に BlocProvider はない。
      BlocBuilder<CounterCubit, int>(
        bloc: counter,
        builder: (context, count) =>
            Text('$count', key: const ValueKey('count')),
      ),
      Tap('+', onTap: counter.increment),
    ],
  );
}

Tap は例の小さなウィジェットで、タップする言葉です。このアプリにはデザインライブラリがありません。

イベント、状態、サービスを持つ Bloc

リポジトリは、他と同じ Bean です。

@Service()
class BookRepository {
  final List<Book> _books = [const Book('Dune'), const Book('Neuromancer')];

  Future<List<Book>> all() async {
    await Future<void>.delayed(const Duration(milliseconds: 300));
    return List.unmodifiable(_books);
  }

  Future<void> add(String title) async {
    await Future<void>.delayed(const Duration(milliseconds: 150));
    if (_books.any((book) => book.title == title)) {
      throw StateError('"$title" is on the shelf already');
    }
    _books.add(Book(title));
  }
}

Bloc のイベントと状態は、普通のクラスです。

sealed class BooksEvent {
  const BooksEvent();
}

final class BooksRequested extends BooksEvent {
  const BooksRequested();

  @override
  String toString() => 'BooksRequested';
}

final class BookAdded extends BooksEvent {
  const BookAdded(this.title);

  final String title;

  @override
  String toString() => 'BookAdded($title)';
}

sealed class BooksState {
  const BooksState();
}

final class BooksLoading extends BooksState {
  const BooksLoading();
}

final class BooksLoaded extends BooksState {
  const BooksLoaded(this.books, {this.problem});

  final List<Book> books;
  final String? problem;
}

Bloc は、どの Bean とも同じように、コンストラクターを通じてリポジトリを受け取ります。Bloc やそのリポジトリを手で登録するものはありません。

@Component()
class BooksBloc extends Bloc<BooksEvent, BooksState>
    with ClosedWithBean<BooksState> {
  BooksBloc(this.repository) : super(const BooksLoading()) {
    on<BooksRequested>(_load);
    on<BookAdded>(_add);
  }

  final BookRepository repository;

  Future<void> _load(BooksRequested event, Emitter<BooksState> emit) async {
    emit(const BooksLoading());
    emit(BooksLoaded(await repository.all()));
  }

  Future<void> _add(BookAdded event, Emitter<BooksState> emit) async {
    try {
      await repository.add(event.title);
      emit(BooksLoaded(await repository.all()));
    } on StateError catch (error) {
      emit(BooksLoaded(await repository.all(), problem: error.message));
    }
  }

  @override
  String toString() => 'BooksBloc';
}

画面は、最初に組み立てられるときに一度だけ本を求め、状態を表示します。

@override
void initState() {
  super.initState();
  SpringScope.of(
    context,
    listen: false,
  ).getBean<BooksBloc>().add(const BooksRequested());
}
BlocBuilder<BooksBloc, BooksState>(
  bloc: context.bean<BooksBloc>(),
  builder: (context, state) => switch (state) {
    BooksLoading() => const Text('Loading the shelf…'),
    BooksLoaded(:final books, :final problem) => Column(
      children: [
        for (final book in books) Text(book.title),
        if (problem != null) Text(problem),
      ],
    ),
  },
)

一つの画面の Cubit

@Scope(NavigationScopes.route) を付けた Cubit は、一つの画面のものです。画面が開くときに作られ、画面が閉じるときに閉じられます。次の訪問は、新しい空の Cubit で始まります。

@Component()
@Scope(NavigationScopes.route)
class DraftCubit extends Cubit<String> with ClosedWithBean<String> {
  DraftCubit() : super('');

  void type(String title) => emit(title);

  @override
  String toString() => 'DraftCubit';
}

画面のすべてのウィジェットが、コンテキストから同じオブジェクトを受け取ります。別の Bean (ここではアプリケーションの BooksBloc) も、同じ方法で受け取ります。

@ScreenRoute('/new', title: 'A new book')
class NewBookPage extends StatefulWidget {
  const NewBookPage({super.key});

  @override
  State<NewBookPage> createState() => _NewBookPageState();
}

class _NewBookPageState extends State<NewBookPage> {
  // ... the text controller and the focus node

  @override
  Widget build(BuildContext context) {
    // 画面自身のもの: この画面のすべてのウィジェットにとって同じオブジェクト。
    final draft = context.bean<DraftCubit>();
    return Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        EditableText(
          // ...
          onChanged: draft.type,
        ),
        BlocBuilder<DraftCubit, String>(
          bloc: draft,
          builder: (context, title) => Text(
            title.isEmpty ? 'Type a title' : 'Title: $title',
            key: const ValueKey('draft'),
          ),
        ),
        Tap(
          'Add',
          onTap: () {
            if (draft.state.isNotEmpty) {
              context.bean<BooksBloc>().add(BookAdded(draft.state));
            }
            context.route.pop();
          },
        ),
      ],
    );
  }
}

スコープについては 画面やブランチごとの Bean を参照してください。

Bloc を閉じる

コンテナーは、自分では Bloc を閉じません。コンポーネントが破棄されるとき、Bean の close() は呼ばれません。そのため、例のそれぞれの Bloc は、@PreDestroy メソッドを一つ持つミックスインを使います。これがそのすべてです。

import 'dart:async';

import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:spring_boot_starter_flutter_navigation/spring_boot_starter_flutter_navigation.dart';

mixin ClosedWithBean<S> on BlocBase<S> {
  @PreDestroy()
  void closeWithBean() => unawaited(close());
}

コンテナーは、Bean が破棄されるときにそれを呼びます。アプリの Bloc ならアプリケーションとともに、route スコープの Bloc なら画面とともにです。close() を呼ぶウィジェットはありません。

このメソッドは同期的で、close() を待ちません。画面の Bean (route スコープ) は、画面が閉じるときにただちに破棄されます。そこで Future を返す破棄のコールバックは、待たれなかったものとしてコンテナーが報告します。それで失われるものはありません。Bloc は、close が呼ばれた瞬間から新しいイベントと状態を拒否します。

test('the container closes the blocs with the application', () async {
  final previous = Bloc.observer;
  final context = await springApplication.runAsync(const []);
  final counter = context.getBean<CounterCubit>();
  final books = context.getBean<BooksBloc>();
  expect(counter.isClosed, isFalse);

  await context.closeAsync();

  expect(counter.isClosed, isTrue);
  expect(books.isClosed, isTrue);
  expect(Bloc.observer, same(previous));
});

@PreDestroy を参照してください。

アプリケーションイベントとしての Bloc のイベント

Bloc には、アプリ全体で一つのオブザーバー Bloc.observer があります。例では、オブザーバーは Bean であり、すべての Bloc が行うことをアプリケーションイベントとして発行します。三つのイベントクラスがそれを運びます。

sealed class BlocApplicationEvent extends ApplicationEvent {
  BlocApplicationEvent(BlocBase<Object?> super.bloc);

  BlocBase<Object?> get bloc => source as BlocBase<Object?>;
}

final class BlocEventAdded extends BlocApplicationEvent {
  BlocEventAdded(super.bloc, this.event);

  final Object? event;

  @override
  String get eventName => 'BlocEventAdded';
}

final class BlocStateChanged extends BlocApplicationEvent {
  BlocStateChanged(super.bloc, {required this.current, required this.next});

  final Object? current;
  final Object? next;

  @override
  String get eventName => 'BlocStateChanged';
}

final class BlocFailed extends BlocApplicationEvent {
  BlocFailed(super.bloc, this.error, this.stackTrace);

  final Object error;
  final StackTrace stackTrace;

  @override
  String get eventName => 'BlocFailed';
}
イベント いつ 持っているもの
BlocEventAdded Bloc にイベントが追加された (Cubit にはイベントがない) bloc、event
BlocStateChanged Bloc または Cubit が、ある状態から別の状態に移った bloc、current、next
BlocFailed Bloc がエラーを報告した (addError、またはハンドラーの中で投げられたもの) bloc、error、stackTrace

オブザーバーは次のとおりです。

@Component()
class SpringBlocObserver extends BlocObserver
    implements BeanFactoryPostProcessor, ApplicationEventPublisherAware {
  late ApplicationEventPublisher events;

  @override
  void setApplicationEventPublisher(ApplicationEventPublisher publisher) =>
      events = publisher;

  BlocObserver? _previous;

  @override
  void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
    _previous = Bloc.observer;
    Bloc.observer = this;
  }

  @PreDestroy()
  void uninstall() {
    if (identical(Bloc.observer, this) && _previous != null) {
      Bloc.observer = _previous!;
    }
    _previous = null;
  }

  @override
  void onEvent(Bloc<dynamic, dynamic> bloc, Object? event) {
    super.onEvent(bloc, event);
    events.publishEvent(BlocEventAdded(bloc, event));
  }

  @override
  void onChange(BlocBase<dynamic> bloc, Change<dynamic> change) {
    super.onChange(bloc, change);
    events.publishEvent(
      BlocStateChanged(
        bloc,
        current: change.currentState,
        next: change.nextState,
      ),
    );
  }

  @override
  void onError(BlocBase<dynamic> bloc, Object error, StackTrace stackTrace) {
    super.onError(bloc, error, stackTrace);
    events.publishEvent(BlocFailed(bloc, error, stackTrace));
  }
}

これが BeanFactoryPostProcessor である理由は一つです。Bloc は、自分が作られたときにあったオブザーバーを保持します。そのため、オブザーバーは最初の Bloc が作られる前に自分の場所に就く必要があり、コンテナーは他のどの Bean を作るよりも前に BeanFactoryPostProcessor を実行します。アプリケーションが閉じるとき、@PreDestroy メソッドがその場所を返します。その後に別のものがその場所を取っていなければです。

パブリッシャーはコンストラクターを通じては来ません。ポストプロセッサーは、通常のインジェクションには早すぎる時点で作られるからです。ApplicationEventPublisherAware は、そのような Bean にパブリッシャーを渡す通常の方法です。コンテナーが setApplicationEventPublisher を呼びます。Bean ファクトリー自体はイベントを発行しません。発行するのはアプリケーションコンテキストです。

そして Bean は、@EventListener で Bloc を聞きます。どの Bloc も購読せず、ストリームのことは何も知りません。condition は、メソッドを一つの Bloc に限ります。

bool ofCounter(BlocStateChanged change) => change.bloc is CounterCubit;

@Service()
class Journal extends ChangeNotifier {
  final List<String> _lines = [];

  int counterChanges = 0;

  List<String> get lines => List.unmodifiable(_lines.reversed.take(8));

  @EventListener()
  void onEvent(BlocEventAdded added) =>
      _write('${added.bloc} ← ${added.event}');

  @EventListener()
  void onChange(BlocStateChanged change) => _write(
    '${change.bloc}: ${change.current} → ${change.next}',
  );

  @EventListener(condition: ofCounter)
  void onCounter(BlocStateChanged change) => counterChanges++;

  @EventListener()
  void onFailure(BlocFailed failed) =>
      _write('${failed.bloc} failed: ${failed.error}');

  void _write(String line) {
    _lines.add(line);
    notifyListeners();
  }
}

@EventListener と BeanFactoryPostProcessor を参照してください。

Bloc のやり方のまま残るもの

Spring のウィジェット (SpringStatelessWidget) は、Bloc の状態によって自分で再構築されることはありません。Bloc はストリームであり、Listenable ではないからです。そのため、Bloc の状態で再構築されるウィジェットは Bloc のもので、いつもどおりに使います。bloc: に Bean を渡した BlocBuilder と BlocSelector です。

上の Journal は ChangeNotifier なので、例は Flutter の ListenableBuilder でそれを表示します。Bloc を使わず、Spring のウィジェットを自分で再構築する Bean に状態を置く方法は、状態の Bean を参照してください。

テスト

springBootTest はアプリケーションの Bean を起動し、BeanOverride はアプリのリポジトリの代わりにテストのリポジトリを置きます。

class _Shelf extends BookRepository {
  final List<Book> books = [const Book('Solaris')];

  @override
  Future<List<Book>> all() async => List.of(books);

  @override
  Future<void> add(String title) async => books.add(Book(title));
}

void main() {
  group('the beans', () {
    final app = springBootTest(
      springApplication,
      overrides: [BeanOverride<BookRepository>(_Shelf())],
    );

    test('a cubit is one bean for the app', () {
      final counter = app.getBean<CounterCubit>();
      expect(app.getBean<CounterCubit>(), same(counter));
      counter.increment();
      expect(counter.state, 1);
    });

    test('a bloc gets its repository by injection', () async {
      final books = app.getBean<BooksBloc>();
      expect(books.repository, isA<_Shelf>());

      books.add(const BooksRequested());
      final loaded = await books.stream.firstWhere(
        (state) => state is BooksLoaded,
      ) as BooksLoaded;
      expect(loaded.books.single.title, 'Solaris');
    });

    test('what a bloc does is heard as application events', () async {
      final journal = app.getBean<Journal>();
      final before = journal.counterChanges;

      app.getBean<CounterCubit>().increment();
      final books = app.getBean<BooksBloc>()..add(const BookAdded('Ubik'));
      await books.stream.firstWhere(
        (state) => state is BooksLoaded && state.books.length == 2,
      );

      expect(journal.counterChanges, before + 1);
      expect(journal.lines, contains('BooksBloc ← BookAdded(Ubik)'));
      expect(Bloc.observer, same(app.getBean<SpringBlocObserver>()));
    });
  });
}

ウィジェットテストは、アプリ全体を起動して画面を見ます。画面の Cubit が画面とともに閉じられること、次の訪問では新しい Cubit になることを示します。

testWidgets('a screen has a cubit of its own', (tester) async {
  await tester.pumpWidget(
    SpringApplicationWidget(application: () => springApplication),
  );
  await tester.pumpAndSettle(const Duration(milliseconds: 400));
  expect(find.text('Dune'), findsOneWidget);

  await tester.tap(find.text('+'));
  await tester.pump();
  expect(
    tester.widget<Text>(find.byKey(const ValueKey('count'))).data,
    '1',
  );

  await tester.tap(find.text('Add a book'));
  await tester.pumpAndSettle();
  final first = SpringScope.beanOf<DraftCubit>(
    tester.element(find.byType(NewBookPage)),
  );
  await tester.enterText(find.byType(EditableText), 'Hyperion');
  await tester.pump();
  expect(first.state, 'Hyperion');

  await tester.tap(find.text('Add'));
  await tester.pumpAndSettle(const Duration(milliseconds: 600));
  expect(find.text('Hyperion'), findsOneWidget);
  // 画面を去ると、その Cubit は閉じられた。
  expect(first.isClosed, isTrue);

  // 次の訪問は、新しい空の Cubit で始まる。
  await tester.tap(find.text('Add a book'));
  await tester.pumpAndSettle();
  final second = SpringScope.beanOf<DraftCubit>(
    tester.element(find.byType(NewBookPage)),
  );
  expect(second, isNot(same(first)));
  expect(second.state, '');
});

spring_boot_starter_flutter のテスト と BeanOverride と @TestBean を参照してください。

リリースビルドでの名前

リリースビルドはクラス名を短くします。runtimeType は minified:Class… と出力します。ジャーナルは Bloc を行に書き込むので、例の Bloc とイベントは toString をオーバーライドします。

@override
String toString() => 'CounterCubit';

ここでフレームワークが与えるもの

Bloc のために フレームワークから
依存関係 コンストラクターインジェクション: Bloc の @Component()、リポジトリの @Service()
ウィジェットの中での場所 BlocProvider の代わりの context.bean<T>()
アプリに一つ、または画面ごとに一つ スコープ: シングルトン、または @Scope(NavigationScopes.route)
close() Bean が破棄されるときに呼ばれる @PreDestroy
どの Bloc よりも前の、オブザーバーの場所 BeanFactoryPostProcessor と、パブリッシャーのための ApplicationEventPublisherAware
他の Bean が聞くイベント ApplicationEventPublisher と、condition を持つ @EventListener
テストでのフェイクのリポジトリ springBootTest と BeanOverride

Bloc 自体、そのウィジェット、そのオブザーバーは flutter_bloc のものです。テストを含むアプリ全体は example/bloc にあります。

関連項目