ウィジェットの中の Bean

サービスはコンストラクターを通じて Bean を受け取ります。ウィジェットはそうできません。Flutter とあなた自身のコードがウィジェットを作るため、何も注入されません。ウィジェットは次の四つの方法のいずれかで Bean を取得します。

方法 型付き 起動時にチェック 変更時に再構築 用途
SpringStatelessWidget<(...)> はい はい はい Bean を表示したり使ったりするほとんどのウィジェット
SpringState を使う SpringStatefulWidget<(...)> はい はい はい 同じもので、State (コントローラー、initState) を持つもの
context.bean<T>() はい いいえ いいえ 一回限りの使用: サービスを呼ぶボタン
context.basket (@BuildContextAccess) はい はい いいえ ツリーの深くで多くのウィジェットが必要とする少数の Bean

使う理由

ルートから葉までコンストラクターでサービスを渡すのは面倒で、Provider のツリーはサービスと手で同期を保たなければなりません。ここではウィジェットが必要なものをその型で示し、ジェネレーターがそれを見て、存在しない Bean はユーザーの前の後の build ではなく起動を失敗させます。

SpringStatelessWidget

ウィジェットは Bean をその型にレコードとして列挙し、build で beans から読みます。

// 本の数を示すバスケットのアイコン。
class BasketBadge extends SpringStatelessWidget<(Basket,)> {
  const BasketBadge({super.key});

  @override
  Widget build(BuildContext context) {
    final (basket,) = beans;
    return Badge(
      label: Text('${basket.count}'),
      child: const Icon(Icons.shopping_basket_outlined),
    );
  }
}

context.bean と比べると:

複数の Bean には、ウィジェットにちなんだ名前の typedef でレコードに名前を付け、末尾のカンマ付きで一行に一つの Bean を書きます。

/// [BasketBadge] の Bean。
typedef BasketBadgeBeans = (
  Basket,
  Clock,
);

class BasketBadge extends SpringStatelessWidget<BasketBadgeBeans> {
  const BasketBadge({super.key});

  @override
  Widget build(BuildContext context) {
    final (
      basket,
      clock,
    ) = beans;
    return Badge(
      label: Text('${basket.count}'),
      isLabelVisible: clock.now().hour < 22, // 夜はバッジなし
      child: const Icon(Icons.shopping_basket_outlined),
    );
  }
}

ルール:

SpringStatefulWidget と SpringState

State も必要なウィジェットのための同じものです。テキストのコントローラー、アニメーション、initState で始める処理などです。State は Bean を beans として持ち、initState 以降で使えます。Dart はウィジェットからレコードを取れないため、両方に書きます。コンパイラーがそれらの一致をチェックし、typedef が一か所にまとめます。

/// [BasketPage] の Bean。
typedef BasketPageBeans = (
  Basket,
  Clock,
);

class BasketPage extends SpringStatefulWidget<BasketPageBeans> {
  const BasketPage({super.key});

  @override
  State<BasketPage> createState() => _BasketPageState();
}

class _BasketPageState extends SpringState<BasketPage, BasketPageBeans> {
  @override
  void initState() {
    super.initState();
    // ページが開いたときに一度、サーバーからバスケットを取得する。
    final (
      basket,
      _,
    ) = beans;
    basket.load();
  }

  @override
  Widget build(BuildContext context) {
    final (
      basket,
      clock,
    ) = beans;
    return Text('${basket.count} books at ${clock.now()}');
  }
}

dispose や didChangeDependencies をオーバーライドする SpringState は、super を呼ばなければなりません。

context.bean

context.bean<T>() は、任意の Bean を型で、または qualifier: で名前で返します。すべてのウィジェットとコールバックで動くため、一回限りの使用に適しています。Bean が変わってもウィジェットを再構築しません。

// タップされると注文を送る。
FilledButton(
  onPressed: () => context.bean<OrderService>().placeOrder(),
  child: const Text('Order'),
);

// 名前による Bean。
final mail = context.bean<MailSender>(qualifier: 'transactional');

生成されるゲッター: @BuildContextAccess

Bean に @BuildContextAccess() を付けると、ジェネレーターは Bean にちなんだ名前の型付きのゲッターを BuildContext に書き出します: context.basket。ツリーの深くで多くのウィジェットが必要とする少数の Bean に使ってください。バスケット、セッション、現在のユーザーなどです。印を付けた Bean だけが得るため、リストは短いままです。@BuildContextAccess(name: 'cart') は別の名前を選びます。

@ChangeNotifierComponent()
@BuildContextAccess()
class Basket { ... }

// 本のタイルの中: タップで本をバスケットに入れる。
IconButton(
  onPressed: () => context.basket.add(book),
  icon: const Icon(Icons.add_shopping_cart),
);

ゲッターは spring_gen/main.spring.dart に生成されます。使う場所でそれをインポートしてください。context.bean と同じく、ゲッターは Bean が変わってもウィジェットを再構築しません。

Spring のウィジェットが再構築される時

SpringStatelessWidget や SpringState は、Listenable であるその Bean の一つが通知すると再構築されます。@ChangeNotifierComponent や @NotifyListeners の Bean では、ウィジェットの build がその状態を読んだ場合だけです (読むのは無料 を参照)。Bean を取得するすべてのウィジェットは、ホットリロードの後にコンテキストが置き換えられたときにも新たに組み立てられます。

context.bean とゲッターでは、Flutter で通常行うように、自分でリッスンしてください。Listenable には ListenableBuilder (状態の Bean には listenableOf(bean) がそれを返します)、ストリームには StreamBuilder です。

フェイクで組み立てる

SpringStatelessWidget は、buildWith を通じて、アプリケーションなしにフェイクで組み立てられます。

final widget = const BasketBadge().buildWith(context, (FakeBasket(), FakeClock()));

検索のスコープ

BeanLookupScope は、その下のウィジェットの Bean の検索 (context.bean<T>()、生成されたゲッター、Spring のウィジェットのレコード) をそのゾーンの中で実行します。そのため、独自の Bean のスコープは、アプリのどの部分が求めているかを知ることができます。ナビゲーションのスターターは、その route と branch のスコープのために、すべての画面の周りに一つ置きます。

既知の制限

Spring (Java) との対応

Spring には対応するものがありません。Java の Bean はコントローラーやビューに注入され、UI のツリーから検索されることはありません。Bean のレコードは、コンストラクターのパラメーターの役割を果たします。

関連項目