
# 状態の Bean

Flutter では、共有の状態は通常、メソッドが `notifyListeners()` で終わる `ChangeNotifier` です。呼び出しを忘れると画面が古いままになります。ここでは、Bean の生成されたプロキシ (Bean を包み、そのメソッドの前後でコードを実行するオブジェクト) がその呼び出しを行います。二つのアノテーションがこれを行います。

- 普通のクラスには `@ChangeNotifierComponent()`。`extends ChangeNotifier` も `notifyListeners()` も不要です。
- すでに `ChangeNotifier` を継承しているクラスには `@NotifyListeners()`。

## 使う理由

Bean の中の状態は、すべての画面とすべてのサービスで共有できます。本の画面が満たすバスケットは、バッジが数え、チェックアウトが読むものと同じです。通知が生成されるため、メソッドがそれを忘れることはなく、ウィジェットは状態を表示する場合にだけ再構築され、単にメソッドを呼ぶだけでは再構築されません。

## @ChangeNotifierComponent

普通のクラスから状態の Bean を宣言します。これは `@Component` なので、クラスは Bean になります。そのプロキシは `ChangeNotifier` で、`exclude` で指定したものを除くすべての公開メソッドとセッターの後に通知します。ゲッターは決して通知しません。

```dart
// 本の画面、バッジ、バスケットの画面が共有するバスケット。
@ChangeNotifierComponent(exclude: ['peek'])
class Basket {
  Basket(this._api);

  final ShopApi _api;
  final _items = <String>[];

  int get count => _items.length;      // ゲッター: 決して通知しない

  void add(String isbn) => _items.add(isbn);
  void clear() => _items.clear();
  String? peek() => _items.lastOrNull; // 除外: 読むだけ

  Future<void> load() async {          // Future が完了したときに通知する
    _items.addAll(await _api.basket());
  }
}
```

生成コードはクラスにスーパークラスを与えられないため、クラス自体は `Listenable` ではありません。コンテナが渡す Bean が `Listenable` です。そのため:

- `SpringStatelessWidget` と `SpringState` は自分でそれを購読します。
- それ以外の場所では、`listenableOf(bean)` が `Listenable` を返します: `ListenableBuilder(listenable: listenableOf(context.basket), builder: ...)`。手で作ったインスタンスなど、`Listenable` でないオブジェクトには `ArgumentError` を投げます。

`exclude` の名前がクラスのメソッド、セッター、フィールドでない場合や、クラスが `ChangeNotifier` 自身のメンバー (`addListener`、`dispose` など) の一つを宣言している場合、ビルドは失敗します。

## @NotifyListeners

すでに `ChangeNotifier` を継承しているクラス、例えばストリームのコールバックからも通知するクラスに対して、同じことを行います。クラスに付けると、すべての公開メソッドとセッター (`exclude` を除く) の後に通知します。メソッドやセッターに付けると、そのものの後にだけ通知します。

```dart
// `select`、`clear`、そして `selected` へのすべての書き込みの後に通知する。
@Component()
@NotifyListeners()
class Search extends ChangeNotifier {
  Book? selected;

  void select(Book book) => selected = book;
  void clear() => selected = null;
}

// `restock` だけが通知する。
@Component()
class Stock extends ChangeNotifier {
  final _available = <String, int>{};

  @NotifyListeners()
  void restock(String isbn, int count) => _available[isbn] = count;
}
```

## リスナーに通知される時

- メソッドが戻った後。例外を投げた場合も (エラーの前に状態が変わっている可能性があるため)。
- 返された `Future` が完了した後。
- コンテナが渡す Bean で。手で作ったインスタンスではありません。
- Bean が自分自身に対して行う呼び出し (`this.add(...)`) が通知するのは、そのプロキシがサブクラスのプロキシ (プライベートなメンバーを持つクラス) である場合だけです。それ以外では、外部からの呼び出しだけが通知します。

## 読むのは無料

Spring のウィジェットが `@ChangeNotifierComponent` の Bean や `@NotifyListeners` を付けたクラスをリッスンするのは、その `build` が Bean の状態 (ゲッターまたはフィールド) を読んだ場合だけです。メソッドを呼ぶこと (`onPressed: counter.increment`) は再構築を招きません。そのため、ページはボタンのためにカウンターを保持しつつ、カウントを表示する `Text` だけを再構築できます。

```dart
class CounterPage extends SpringStatelessWidget<(Counter,)> {
  const CounterPage({super.key});

  @override
  Widget build(BuildContext context) {
    final (counter,) = beans;
    return Scaffold(
      body: const CounterText(),                  // タップ後に再構築される
      floatingActionButton: FloatingActionButton( // ページは再構築されない
        onPressed: counter.increment,
        child: const Icon(Icons.add),
      ),
    );
  }
}
```

プロキシは読み取りを見ているため、ルールはウィジェットが実際に表示するものに従います。Bean を読まなくなった `build` はリッスンをやめ、次に読んだ `build` は再びリッスンします。Bean 自身のメソッドの中での自分自身の読み取りは数に入りません。

知っておくべきケースが一つあります。ウィジェット自身の `build` の外での読み取り (`ListView.builder` のアイテムビルダー、その下の `Builder`、コールバック、`initState`、別の Bean) は、画面のための読み取りと区別できません。そうした読み取りの後は、Bean を保持するすべてのウィジェットがリッスンし続けるため、画面が古くなることはありませんが、必要以上に再構築されることがあります。それが問題になる場合は、`build` の外では状態を読むよりメソッドを呼んでください。

それ以外の `Listenable` の Bean (普通の `ChangeNotifier`、またはメソッドにだけ `@NotifyListeners` を持つもの) は常にリッスンされます。

## Spring (Java) との対応

Spring には対応するものがありません。これは `@Transactional` のような、Bean のメソッドの周りのアドバイスです。プロキシが各呼び出しの後にコードを実行します。

## 関連項目

- [ウィジェットの中の Bean](beans-in-widgets.md)
- [ChangeNotifier の横のシグナル](../spring-boot-starter-flutter-signals/beside-change-notifier.md): フィールド単位で追跡される状態。`@Signal`、`@Computed`、`@Effect`
- [Bloc と Cubit](../../docs/bloc.md): Bean である Bloc に置く状態
- [spring_core_dart の AOP](../spring-core-dart/aop/index.md)
- [Flutter のためのジェネレーター](../spring-core-dart-generator/flutter/index.md)
