Bloc と Cubit
Spring for Dart で作る Flutter アプリは、パッケージ flutter_bloc の Bloc と Cubit に状態を置けます。フレームワークには Bloc のためのスターターがなく、必要もありません。Bloc はクラスなので、Bean です。依存関係はコンストラクターインジェクションで渡され、寿命はそのスコープで決まり、ウィジェットはコンテキストからそれを受け取って Bloc 自身のウィジェットに渡します。
このページの内容はすべて、フレームワークのリポジトリの例 example/bloc のコードです。下のオブザーバー、イベント、ミックスインはその例のコードで、アプリがコピーして使うものです。フレームワークの一部ではありません。
考え方
Bloc のアプリでは、BlocProvider が Bloc をウィジェットツリーに置いて閉じ、Bloc 自身の依存関係はリポジトリのプロバイダーやサービスロケーターから来ます。Spring のアプリでは、コンテナーがすでに両方の仕事をしています。
BlocProviderもサービスロケーターもありません。 Bloc に付けた@Component()が、それを Bean にします。コンストラクターが求めるものはインジェクションされます。- ウィジェットはコンテキストから Bloc を受け取ります:
context.bean<CounterCubit>()。 - Bloc 自身のウィジェットがそれを表示します: Bean を渡した
BlocBuilder(bloc: ..., builder: ...)。 - 寿命はそのスコープです: シングルトンならアプリケーションの寿命、
routeスコープなら画面の寿命。
セットアップ
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 にあります。