
# ウィジェットの中の Bean

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

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

## 使う理由

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

## SpringStatelessWidget

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

```dart
// 本の数を示すバスケットのアイコン。
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 は型付きで、一か所に列挙されます。
- ジェネレーターはそうしたウィジェットをすべて見るため、存在しない Bean は起動を失敗させます。
- ウィジェットは、表示する状態の Bean が変わると再構築されます ([状態の Bean](state-beans.md) を参照)。

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

```dart
/// [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),
    );
  }
}
```

ルール:

- `beans` は `build` と、そこで作られるコールバック (`onPressed`) の中で読んでください。ウィジェットはイミュータブルで、一つの `const` インスタンスが複数の場所で組み立てられることがあるため、`build` の後には最新の `build` の Bean を保持しています。二つのアプリケーションコンテキストの下で同時に組み立てられるウィジェット (まれ: 二つの `SpringScope`) は、上のように `build` の中でそれらをローカル変数に取ります。
- 名前付きフィールドを持つレコード (`({Clock utc})`、`beans.utc` として読む) も使えます。複数の Bean がフィールドの型を持つ場合、Spring のコンストラクターのパラメーター名のように、フィールドの名前が一つを選びます。
- nullable のフィールド (`Clock?`) は省略可能です。そうした Bean がなければ `null` です。

## SpringStatefulWidget と SpringState

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

```dart
/// [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 が変わってもウィジェットを再構築しません。

```dart
// タップされると注文を送る。
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')` は別の名前を選びます。

```dart
@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` がその状態を読んだ場合だけです ([読むのは無料](state-beans.md#読むのは無料) を参照)。Bean を取得するすべてのウィジェットは、ホットリロードの後にコンテキストが置き換えられたときにも新たに組み立てられます。

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

## フェイクで組み立てる

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

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

## 検索のスコープ

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

## 既知の制限

- 同じ Bean のレコードを持つウィジェットは、一つのバインディングを共有します。ジェネレーターはレコードの型ごとに一つのバインディングを書き出します。Bean が存在しない場合、起動はそのレコードを使うウィジェットのそれぞれではなく、そのうちの一つを示して失敗します。

## Spring (Java) との対応

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

## 関連項目

- [状態の Bean](state-beans.md)
- [テスト](testing.md)
- [spring_core_dart の Bean](../spring-core-dart/beans/index.md)
