
# spring_boot_starter_flutter_signals

`spring_boot_starter_flutter_signals` は、[spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md) の上に作られた Flutter アプリの Bean に、リアクティブな状態を置きます。コンポーネントに付ける三つのアノテーションと、普通のフィールドです。

- **フィールドの `@Signal()`**: 代入されると、それを読んだものに伝えられます。
- **ゲッターの `@Computed()`**: 読んだものが変わるまで保持される値。`Future` や `Stream` からも、その状態とともに。
- **メソッドの `@Effect()`**: 読んだものが変わると、再び実行されます。

## 使う理由

互いに別々に変わる複数のフィールドを持つ Bean には、よくある答えが二つあります。Bean 全体のための一つの通知 (聞いているすべてのウィジェットが再構築される) か、すべてのフィールドを包むラッパー型と、読むたびの `.value` です。ここでは、フィールドは普通のフィールドのままです。Bean の生成されたプロキシが、読み取りと代入を追跡します。そのため、次のようになります。

- ラッパー型も `.value` もありません。
- ウィジェットは、`build` が読んだフィールドのためにだけ再構築されます。
- 他の値から作られる値は、一度計算されて保持されます。
- リクエストは、それが依存するものが変わると、もう一度行われます。

スターターは、サードパーティのパッケージ `signals_core` の上に作られています。そこから再エクスポートするのは `batch` と `untracked` だけです。`ChangeNotifier` の代わりではなく、その横に並びます。`@ChangeNotifierComponent` と `@NotifyListeners` はそのままです ([ChangeNotifier の横で](beside-change-notifier.md) を参照)。

## セットアップ

```yaml
# pubspec.yaml
environment:
  sdk: ^3.14.0
  flutter: '>=3.50.0'

dependencies:
  flutter:
    sdk: flutter
  spring_boot_starter_flutter_signals: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
```

スターターは `spring_boot_starter_flutter` を連れてきて再エクスポートします。アプリは代わりにこのパッケージを列挙します。インポートは一つで足ります。

```dart
import 'package:spring_boot_starter_flutter_signals/spring_boot_starter_flutter_signals.dart';
```

Flutter 3.50 以降 (Dart 3.14) が必要です。プロキシはジェネレーターが書き出します。アノテーションを追加または削除した後は `dart run build_runner build` を実行します。

## 例

合計がアイテムとクーポンに従い、エフェクトが保存するバスケットです。

```dart
// lib/main.dart
import 'package:flutter/widgets.dart';
import 'package:spring_boot_starter_flutter_signals/spring_boot_starter_flutter_signals.dart';

import 'spring_gen/main.spring.dart';

class Book {
  const Book(this.title, this.price);

  final String title;
  final double price;
}

@Service()
class BasketStorage {
  final List<int> saved = [];

  void write(int count) => saved.add(count);
}

@Component()
class Basket {
  Basket(this.storage);              // 通常のインジェクション

  final BasketStorage storage;

  @Signal()
  List<Book> items = [];

  @Signal()
  String? coupon;

  @Computed()                        // items か coupon が変わるまで保持される
  double get total =>
      items.fold(0.0, (sum, book) => sum + book.price) *
      (coupon == null ? 1 : 0.9);

  @Effect()                          // items が変わるたびに再び実行される
  void save() => storage.write(items.length);

  void add(Book book) => items.add(book);
  void apply(String code) => coupon = code;
}

// Spring のウィジェットは自分の build を追跡する: クーポンが変わると
// 再構築され、バスケットの他のものでは再構築されない。
class CouponLabel extends SpringStatelessWidget<(Basket,)> {
  const CouponLabel({super.key});

  @override
  Widget build(BuildContext context) {
    final (basket,) = beans;
    return Text('Coupon: ${basket.coupon ?? 'none'}');
  }
}

class Shop extends StatelessWidget {
  const Shop({super.key});

  @override
  Widget build(BuildContext context) {
    final basket = context.bean<Basket>();
    return Column(
      children: [
        GestureDetector(
          onTap: () => basket.add(const Book('Dune', 10)),
          child: const Text('Add Dune'),
        ),
        // 合計が変わると再構築され、他のものでは再構築されない。
        Watch((context) => Text('Total: ${basket.total}')),
        const CouponLabel(),
      ],
    );
  }
}

@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    home: const Shop(),
  ),
);
```

コンポーネントは、別の指定がなければシングルトンです。そのため、これはアプリの状態であり、インジェクションによって、またはウィジェットのコンテキストから、どこからでも届きます。

## 実行する

```bash
dart run build_runner build   # Basket のプロキシを書き出す
flutter run
```

- "Add Dune" をタップすると、リストがその場で変わります。合計がもう一度計算され、`Watch` が再構築され、`save` がもう一度実行されます。
- `CouponLabel` は、そのためには再構築されません。その `build` が読んだのはクーポンだけです。
- デバッグビルドでは、デバッグパネルに "State" タブがあり、`Basket` とそのメンバーを名前で示します。

## 内容

- [フィールドと計算された値](fields-and-computed.md): `@Signal` と `@Computed`、付ける場所、何が変化と数えられるか。
- [コレクション](collections.md): `List`、`Set`、`Map`、`Queue` のフィールドは、その場での変化を伝えます。
- [非同期の状態](async-state.md): `@Computed` の `Future` や `Stream`、`state`、`refresh()`、`reload()`。
- [エフェクト](effects.md): `@Effect`、`untracked`、メソッドは一つの変化、`batch`。
- [ウィジェットの中で](widgets.md): Spring のウィジェット、`Watch`、`AsyncView`。
- [状態の寿命](lifetime.md): 状態は Bean とともに終わります。
- [ChangeNotifier の横で](beside-change-notifier.md): どちらをいつ使うか。三つ目の方法としての Bloc。
- [ビルドがチェックするもの](build-checks.md): ビルドを失敗させるものと、させないもの。
- [デバッグタブとログ](debug-tab.md): State タブ、`@Signal(hidden: true)`、ロガー。
- [テスト](testing.md): テストでの状態。

## 知っておくこと

- **Bean 自身の呼び出しは追跡されます。追跡されるだけです。** このようなメンバーを持つ Bean は、Bean が自分自身に対して行う呼び出しを見るサブクラスによってプロキシされるため、メソッドの中で読み書きするフィールドも追跡されます。Bean に付いたほかのアドバイス (`@Transactional`、`@PreAuthorize`、`@Cacheable`) は、ほかの Bean や Spring と同じく、その呼び出しを飛ばします。外からの呼び出しに対して実行されます。
- **誰も読んでいないフィールドは、まだ追跡されていません。** 最初に読まれたときに、フィールド自体から写し取られます。
- **等しければ変化ではありません。** そこにある値と等しい値を代入しても、誰にも伝えられません。
- **エフェクトは、読んだものが代入されるとただちに実行されます** (代入したメソッドの終わりに)。後のフレームではありません。
- **スターターが作らないもの**: 実行をまたいで保持される状態、アンドゥのある履歴、実行中のアクションの状態 ("saving...")、無効化のあるキャッシュとしてのサーバーのデータ。

## Spring (Java) との対応

Spring には対応するものがありません。形は Spring のものです。コンポーネントのメンバーに付けるアノテーションと、Bean のプロキシがその周りで実行するアドバイスで、`@Transactional` や `@Cacheable` と同じです。Spring と違う点が一つあります。このようなメンバーを持つ Bean は、自分自身に対して行う呼び出しにもアドバイスが適用されます。

## 関連項目

- [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md)
- [状態の Bean](../spring-boot-starter-flutter/state-beans.md)
- [ウィジェットの中の Bean](../spring-boot-starter-flutter/beans-in-widgets.md)
- [spring_core_dart の AOP](../spring-core-dart/aop/index.md)
- [ビルドに含まれるもの](optimizations.md)
