
# Flutter

`spring_boot_starter_flutter` を使うアプリに対して、ジェネレーターはウィジェットをアプリケーションコンテキストに結び付けるコードを書き出します。ウィジェットは Bean ではありません。Flutter が自身のコンストラクターでそれらを生成するので、何もそこに注入できません。生成コードは、ジェネレーターがコードから読んだアノテーションと型をもとに、ビルド時にその隙間を埋めます。

ジェネレーターは Flutter のスターターに依存しません。他のスターターのアノテーションを認識するのと同じく、スターターのアノテーションとクラスをその URL (たとえば `package:spring_boot_starter_flutter/src/annotations.dart#BuildContextAccess`) で認識します。それらを何も使わないモジュールの `.spring.dart` ファイルには、Flutter 固有のものは何も入りません。

## 使う理由

ウィジェットのコードには Bean が必要です。バスケット、セッション、現在の言語です。生成コードがなければ、ウィジェットは実行時に各 Bean を型で検索します (`context.bean<Basket>()`)。それでも動きますが、次の問題があります。

- 足りない Bean は、ウィジェットが最初にビルドされるとき、ひょっとするとアプリの奥深くで初めて見つかります。
- 検索のたびに型を、ときには修飾子も繰り返します。
- 変化する状態の Bean は、変更のたびに自分で `notifyListeners()` を呼ばなければならず、ウィジェットはそれを購読しなければなりません。

ジェネレーターはこの作業をビルドに移します。Bean の型付きゲッターを書き、ウィジェットの Bean レコードに値を入れ、ウィジェットが必要とするすべての Bean が存在することをアプリが起動時にチェックできるようにし、代わりにリスナーに通知するプロキシを書き出します。

## 認識するもの

| コード中のもの | ビルドが書き出すもの | 場所 |
|---|---|---|
| Bean クラスまたは `@Bean` メソッドの `@BuildContextAccess()` | `extension SpringBeans on BuildContext` のゲッター | モジュールの `.spring.dart` |
| `SpringStatelessWidget<R>` を継承するクラス、または `SpringState<W, R>` を継承する `State` | モジュールの `SpringWidgetBindings` Bean の中のバインディング | モジュールの Bean のリスト |
| `@ChangeNotifierComponent()` または `@NotifyListeners()` | リスナーに通知するプロキシクラス (前者では `ChangeNotifier` も mixin する) | モジュールの `.spring.dart` |
| ローダークラスの `@ThemeLoaderKind('name')` | `ThemeLoaderKinds` への登録 | モジュールのゲッター |
| `@ScreenRoute(...)` と `@RouteShell(...)` のウィジェット (`spring_boot_starter_flutter_navigation`) | `ScreenRoutes` Bean と、画面ごとに一つのルートの拡張 | モジュールの `.spring.dart` |
| `spring.flutter.theme.*` と `messages*.properties` | `context.theme` と `context.messages` | `lib/spring_gen/theme.spring.keys.dart`、`lib/spring_gen/messages.spring.keys.dart` |

モジュールとは `@SpringBootApplication` または `@ComponentScan` のライブラリのことで、その `.spring.dart` ファイルは、メインのビルダーが `spring_gen/` の中でその隣に書き出すもの (`lib/spring_gen/main.spring.dart` など) です。ウィジェットは、ゲッターと拡張を使うためにそのファイルをインポートします。

以下のコードの抜粋は、実際の生成ファイルから取ったものです。読みやすくするため、`_i10.` のようなインポートのプレフィックスは外しています。

## `@BuildContextAccess`: Bean ごとのゲッター

Bean に `@BuildContextAccess()` を付けると、`SpringApplicationWidget` の下のすべてのウィジェットが `context.<name>` でそれに到達できます。

```dart
// lib/src/basket/basket.dart
@ChangeNotifierComponent()
@BuildContextAccess()
class Basket {
  Basket(this._shop);
  // ...
}
```

ビルドはモジュールごとに一つの拡張を書き出し、示された Bean ごとにゲッターを持たせます。

```dart
// lib/spring_gen/main.spring.dart (生成)

/// Getters for the `@BuildContextAccess` beans, for widgets below `SpringApplicationWidget`.
extension SpringBeans on BuildContext {
  /// The bean 'session'.
  Session get session =>
      SpringScope.beanOf<Session>(this, qualifier: r'session');

  // ...

  /// The bean 'basket'.
  Basket get basket =>
      SpringScope.beanOf<Basket>(this, qualifier: r'basket');
}
```

```dart
// ウィジェットの中で:
Text('${context.basket.count}');
```

ゲッターの作られ方:

1. **その名前** は Bean の名前 (クラス `Basket` なら `basket`)、または指定した名前です: `@BuildContextAccess(name: 'cart')`。
2. **その型** は Bean が知られている型です。クラスの Bean ではクラス、`@Bean` メソッドでは宣言された戻り値の型 (メソッドの本体から推論される型は private な、またはより狭いクラスかもしれないため)、`FactoryBean` では生成物の型です。
3. **その本体** は `SpringScope.beanOf<T>(this, qualifier: '<bean name>')` で Bean を検索します。Bean 名が修飾子なので、他の Bean が同じ型を共有していても、ゲッターはこの Bean を正確に見つけます。

`@BuildContextAccess` は、クラスにも、Bean を生成する `@Bean` メソッドにも付けられます。

### エラー

ビルドはモジュールのすべての不正なゲッターを集め、まとめて報告します。各エラーは Bean とそのソースを示し、修正方法で終わります。

| 問題 | メッセージの例 |
|---|---|
| 名前が Dart の識別子でない | `@BuildContextAccess(name: 'my-cart') on ...: 'my-cart' is not a valid Dart identifier for a getter. Choose another name.` |
| 名前が private | `...: '_cart' is private, so widgets could not use the getter.` |
| 名前が予約語 | `@BuildContextAccess on bean 'default' (...): 'default' is a reserved word. Give the getter a name: @BuildContextAccess(name: 'myGetter').` |
| 名前が `BuildContext`、`Object`、スターターの `SpringBuildContext` のメンバー | `...: 'size' clashes with BuildContext.size, which a generated getter cannot replace.` |
| 二つの Bean が同じゲッターになる | `...: the getter 'cart' is already generated for bean 'cart' (...). Give one of them another name with @BuildContextAccess(name: '...').` |
| クラスが Bean でない | `@BuildContextAccess on Basket, which is no bean of this application: add @Component() (or another stereotype), or put @BuildContextAccess on the @Bean method that creates it.` |

ゲッターに使えないメンバーは、`BuildContext` のもの (`widget`、`owner`、`mounted`、`size`、`findRenderObject`、`dependOn...`、`find...`、`visit...`、`describe...` のメソッドなど)、`Object` のもの (`hashCode`、`runtimeType`、`toString`、`noSuchMethod`)、`SpringBuildContext` のもの (`springContext`、`bean`、`message`) です。そのような名前の拡張ゲッターは本物のメンバーに隠されてしまうので、ビルドはそれを拒否します。

## Bean を持つウィジェット

ウィジェットは必要な Bean をレコード型で指定し、`build` の中で `beans` からそれらを読みます。

```dart
// lib/src/basket/basket_badge.dart
class BasketBadge extends SpringStatelessWidget<(Basket,)> {
  const BasketBadge({super.key});

  @override
  Widget build(BuildContext context) {
    final (basket,) = beans;
    final count = basket.count; // build の中で読む: バスケットが通知するとバッジが再ビルドされる
    return Badge(
      isLabelVisible: count > 0,
      label: Text('$count'),
      child: const Icon(Icons.shopping_basket_outlined),
    );
  }
}

// Bean が多い場合は、typedef でクラスの行を短く保つ。
typedef SettingsPageBeans = (
  ThemeSelection,
  SpringThemes,
  LanguageSelection,
  AppAssets,
);

class SettingsPage extends SpringStatelessWidget<SettingsPageBeans> { ... }

// ステートフルウィジェット: State が Bean を受け取る。
class _CatalogPageState extends SpringState<CatalogPage, (Catalog,)> { ... }
```

レコードに値を入れるには各フィールドを指定するコードが必要で、Dart には実行時にそれを行うリフレクションがありません。そこでビルドは、レコード型ごとに **バインディング** を書き出します。モジュールのすべてのバインディングは一つの Bean `SpringWidgetBindings` にまとめられます。

```dart
// lib/spring_gen/main.spring.dart (生成)、モジュールの Bean のリストの中
BeanDefinition<SpringWidgetBindings>(
  name: r'flutterSpringWidgetBindings#application',
  source: r'package:spring_boot_starter_flutter/spring_boot_starter_flutter.dart#SpringWidgetBindings',
  autowireCandidate: false,
  create: (r) => SpringWidgetBindings([
    SpringWidgetBinding(
      widget: r'package:neon_books_app/src/settings/settings_page.dart#SettingsPage',
      beans: SettingsPageBeans,
      types: const [ThemeSelection, SpringThemes, LanguageSelection, AppAssets],
      resolve: (f) => (
        SpringWidgetBinding.bean<ThemeSelection>(f),
        SpringWidgetBinding.bean<SpringThemes>(f),
        SpringWidgetBinding.bean<LanguageSelection>(f),
        SpringWidgetBinding.bean<AppAssets>(f),
      ),
      values: (r) {
        final v = (r as (ThemeSelection, SpringThemes, LanguageSelection, AppAssets));
        return [v.$1, v.$2, v.$3, v.$4];
      },
    ),
    // ... レコード型ごとに一つのバインディング
  ]),
),
```

各部分の役割:

| フィールド | 役割 |
|---|---|
| `widget` | レコードを宣言したクラス (`package:<app>/<file>.dart#<Class>`)。エラーメッセージ用。 |
| `beans` | `Type` 値としてのレコード型。ウィジェットはこの型でバインディングを見つけます。`(Basket,)` のようにインラインで書かれたレコードは、レコード型を素の型リテラルとして書けないため、生成された `_$typeOf<(Basket,)>()` ヘルパーを通して書かれます。 |
| `types` | 存在しなければならない Bean の型。非 nullable なフィールドのものです。`SpringApplicationWidget` は起動時にそれらをチェックします。 |
| `resolve` | Bean ファクトリーからレコードに値を入れます。 |
| `values` | 値の入ったレコードの Bean を列挙し、ウィジェットが `Listenable` なものを購読できるようにします。 |

Bean の名前は `flutterSpringWidgetBindings#<module>` で、オートワイヤーの候補ではありません。どの Bean も注入でそれを受け取れません。スターターは `getBeansOfType` でそれを見つけます。

### 各フィールドへの値の入れ方

| レコードのフィールド | 生成される呼び出し | 実行時 |
|---|---|---|
| 位置、非 nullable: `(Basket,)` | `SpringWidgetBinding.bean<Basket>(f)` | その型の Bean。存在しない場合、または複数あってどれもプライマリーでない場合は失敗する。 |
| 名前付き、非 nullable: `({Clock clock})` | `SpringWidgetBinding.bean<Clock>(f, 'clock')` | その型の Bean。複数の Bean がその型を持ち、どれもプライマリーでない場合は、名前がフィールド名と同じもの。 |
| nullable: `(Basket?,)` | `f.findBean<Basket>()` | Bean、または `null`。起動時にはチェックされない。 |

### レコード型ごとに一つのバインディング

ウィジェットはレコード型でバインディングを見つけるので、同じレコードを持つ二つのウィジェットは一つのバインディングを共有します。ビルドはそれを、最初にスキャンしたウィジェットの名前で一度だけ書き出します。`BasketBadge` と、どちらも `(Basket,)` を宣言する別のウィジェットは、同じコードを使います。

### 起動時のチェック

コンテキストが起動した後、`SpringApplicationWidget` はすべてのバインディングを調べ、`types` の各型について Bean が存在することをチェックします。足りない Bean があると、ウィジェットが最初にビルドされるときに後で失敗する代わりに、ウィジェットを示す `NoSuchBeanDefinitionException` で起動が止まります。

ウィジェットのレコードに実行時にバインディングがない場合 (ウィジェットを書いた後にジェネレーターが実行されなかった)、最初のビルドで `FlutterError` が投げられます: `No generated beans for BasketBadge ((Basket,)).`。`dart run build_runner build` を実行するようにとのヒントと、レコード型を変更した後はホットリスタートが必要な場合があることも示されます。

### エラー

| 問題 | メッセージ |
|---|---|
| 型引数がレコードでない、または nullable なレコード | `SpringStatelessWidget BasketBadge: its beans must be a record of bean types, like SpringStatelessWidget<(Basket, AppNavigator)>, not Basket.` |
| フィールドがクラス型やインターフェース型でない (`dynamic`、`Object`、`Function`、`Null`、レコード、関数型) | `SpringStatelessWidget BasketBadge: Object (positional field of (Object,)) is not a bean type; every field of the record must be a class or interface type (nullable for an optional bean).` |

レコードがまだ型パラメーターである抽象クラス (`abstract class MyBase<R extends Record> extends SpringStatelessWidget<R>` のような基底クラス) はスキップされ、その具象サブクラスがバインディングを受け取ります。レコードが型パラメーターである具象クラスは、最初のエラーで失敗します。

## `@ChangeNotifierComponent` と `@NotifyListeners`

状態の Bean は、変化したときにウィジェットに伝えなければなりません。スターターの二つのアノテーションは、生成されたプロキシにそれを任せます。

- **`@ChangeNotifierComponent()`** を普通のクラス (`extends ChangeNotifier` なし) に付けると、クラスは Bean になり、そのプロキシは `ChangeNotifier` を mixin し、`exclude` で指定されたもの以外のすべての public なメソッドとセッターの後に `notifyListeners()` を呼びます。
- **`@NotifyListeners()`** をすでに `ChangeNotifier` を継承しているクラスに付けると、クラスに付けた場合は `exclude` のもの以外のすべての public なメソッドとセッターで同じことを行い、メソッドやセッターに付けた場合はそれの後だけで行います。

ゲッターは決して通知しません。`Future` を返すメソッドでは、Future が完了したときにリスナーに通知されます。メソッドが例外を投げた場合も通知されます。

上の `Basket` のプロキシです (private なメンバーを持つクラスなので、プロキシはサブクラスです)。

```dart
// lib/spring_gen/main.spring.dart (生成)
/// Basket: `@ChangeNotifierComponent()`
class _$BasketProxy extends Basket with ChangeNotifier, AdvisedSubclass {
  _$BasketProxy(super.p0);

  /// add: `@ChangeNotifierComponent()`
  @override
  Future<void> add(Book book) {
    final _$invoker = this.aopInvoker;
    return _$invoker == null
        ? super.add(book)
        : _$invoker.invokeAsync<void>(
            proxy: this,
            target: this,
            methodIndex: 0,
            arguments: [book],
            original: (args) => super.add((args[0] as Book)),
          );
  }
  // ... その他のすべてのメンバー
}
```

通知そのものは、`@Transactional` と同じくアドバイスです。スターターは、ポイントカットが二つのアノテーションに一致する二つのアドバイザーを登録し、プロキシは各呼び出しをそれらに通します。

- 一つは、上で説明したメソッドとセッターの後に `notifyListeners()` を呼びます。
- もう一つはゲッターとフィールドの読み取りを監視し、`SpringStatelessWidget` や `SpringState` が、その `build` が状態を読んだときにだけ Bean を購読するようにします。メソッドを呼ぶだけのウィジェット (`onPressed: counter.increment`) は再ビルドされません。

そのため、プロキシはゲッターもオーバーライドします。コンテナが渡す Bean は、コンパイラーから見てクラス `Basket` が `Listenable` でなくても、`Listenable` です。Spring のウィジェットは自分でそれを購読します。それ以外の場所では、`listenableOf(bean)` がそれに `Listenable` の型を与えます。

これらのプロキシは常に生成されます。ビルドが [AOP プロキシを刈り込む](../optimizations/aop-proxies.md) とき、`@ChangeNotifierComponent` クラスのプロキシを取り除いたり遅延したりすることはありません。それがなければ、Bean はそもそも `ChangeNotifier` にならないからです。`@NotifyListeners` を持つ Bean は、スターターのポイントカットが一致するアノテーションを宣言している (`static const annotationTypes`) ので、ビルドはそれらが適用されることを知り、プロキシを保ちます。

### エラー

| 問題 | メッセージ |
|---|---|
| `exclude` の名前が、クラスの (自身の、または継承した) public なメソッド、セッター、フィールドでない | `@ChangeNotifierComponent on Counter: exclude names rest, which is no public method, setter or field of Counter.` |
| `ChangeNotifier` でない `@ChangeNotifierComponent` クラスが、`addListener`、`removeListener`、`dispose`、`notifyListeners`、`hasListeners` を宣言している | `@ChangeNotifierComponent on Counter: dispose would clash with the ChangeNotifier its proxy mixes in; rename it, or let Counter extend ChangeNotifier.` |

最初のチェックがなければ、`exclude` のタイプミスは黙って何も除外しないことになります。

## アプリ独自のローダーの種類

テーマはローダーを種類で指定します。`spinner`、`dots`、`pulse`、`bar`、`skeleton` は組み込みです。`@ThemeLoaderKind('doors')` で示され、`ThemeLoaderPainter<P>` または `ThemeLoaderWidget<P>` を継承するクラスは、種類を追加します。モジュールは、モジュールが組み立てられる前にそのゲッターの中でそれを登録するので、テーマが読まれるときにはその種類が見つかります。

```dart
// lib/spring_gen/main.spring.dart (生成)
BeanModule get $application {
  ThemeLoaderKinds.register<SpringLeafLoaderProps>(
    r'spring-leaf',
    widget: SpringLeafLoader(),
    props: SpringLeafLoaderProps._,
    keys: SpringLeafLoaderProps.keys,
  );
  return BeanModule(r'application', [/* Bean */]);
}
```

`SpringLeafLoader` は `ThemeLoaderWidget` なので `widget:` として渡されます。`ThemeLoaderPainter` は `painter:` として渡されます。props クラス `SpringLeafLoaderProps` は、テーマがその種類のローダーに与えるキーから、型付きキーのビルダーが書き出します。[型付きキー](typed-keys.md#ローダーとスプラッシュ) を参照してください。クラスが生成された props クラスの代わりに `LoaderValues` を受け取る場合、登録には `props:` と `keys:` がありません。

次の場合、ビルドは失敗します。

- 種類に名前がない、または組み込みの種類の名前である (大文字小文字、`-`、`_` を区別せずに比較)。
- クラスが抽象である、`ThemeLoaderPainter` も `ThemeLoaderWidget` も継承していない、または必須の引数のない無名コンストラクターを持たない (登録がそれを生成するため)。
- その props の型が、生成されたクラス (`doors` なら `DoorsLoaderProps`) でも `LoaderValues` でもない。
- 二つのクラスが同じ種類を宣言している。

## 画面とルート

`spring_boot_starter_flutter_navigation` では、`@ScreenRoute('/path')` で示されたウィジェットは画面になり、`@RouteShell(branches: [...])` で示されたものはブランチごとのスタックを持つシェルになります。ビルドはそれらを、アプリが手で使うのと同じビルダーで書かれた、モジュールごとに一つの `ScreenRoutes` Bean にまとめます。

```dart
// 入力
@ScreenRoute('/components/{*path}', title: '#{docs.title}', content: 'resources:content/components/')
class DocsPage extends StatelessWidget {
  const DocsPage({super.key});
  // ...
}
```

```dart
// lib/spring_gen/main.spring.dart (生成)、モジュールの Bean のリストの中
BeanDefinition<ScreenRoutes>(
  name: r'screenRoutes#application',
  source: r'package:spring_boot_starter_flutter_navigation/spring_boot_starter_flutter_navigation.dart#ScreenRoutes',
  create: (r) => ScreenRoutes.route(source: r'application')
      .screen(
        r'/components/{*path}',
        (r) => const DocsPage(),
        name: r'docs-page',
        title: r'#{docs.title}',
        content: r'resources:content/components/',
        source: r'package:neon_farum_azula/src/pages/docs/docs_page.dart#DocsPage',
      )
      // ... その他の画面
      .notFound((r) => const NotFoundPage())
      .build(),
),
```

見つからない場合の画面を除く各画面は、その定数と型付きの `to(...)` を持つ拡張も受け取ります。

```dart
// lib/spring_gen/main.spring.dart (生成)

/// The route of [DocsPage]: its path, name, values and `to`.
extension DocsPageRoute on DocsPage {
  /// The path pattern.
  static const pattern = r'/components/{*path}';

  /// The route's name.
  static const routeName = r'docs-page';

  /// The path variable `path`.
  static const path = RouteVar<String>(r'path');

  /// The location of this screen with these values.
  static RouteLocation to({required String path}) =>
      RouteLocation.expand(pattern, pathVariables: {r'path': path});
}
```

拡張には、パス変数ごとの `RouteVar<String>`、`params: {'page': int}` で宣言されたクエリパラメーターごとの `RouteParam<T>`、`extra:` のための `RouteExtra<T>`、そしてパス変数ごとに必須の `String`、パラメーターごとに省略可能な値を取る `to(...)` があります。名前を変えたパス、変数、パラメーターは、それを使うコードをコンパイル時に壊します。

ビルドが適用するルール:

- **ルート名** は `name:`、なければクラス名をケバブケースにしたものです。`BookPage` は `book-page` です。
- **値の名前** は Dart の名前にされます。`page-size` は `pageSize` です。`pattern`、`routeName`、`to`、`extra` と衝突する名前、識別子にならない名前、同じ名前の二つの値はビルドを失敗させます。
- **ウィジェット** は、無名コンストラクターが const であれば `const` で生成されます。
- 画面に付けた `spring_security_core` の **`@PreAuthorize('...')`** は、ルート属性 `RouteAttributes.preAuthorize` になります。
- **`@RouteInfo`** (description、image、index、link、paths) はメタデータに入り、[検索エンジン向けのページ](seo.md) がそれを読みます。`link: false` はルートにも渡されます。

次の場合、ビルドは失敗します。`@ScreenRoute` や `@RouteShell` を持つクラスがウィジェットでない、または両方を持つ。画面が必須パラメーターのない無名コンストラクターを持たない (ルーターがそれを生成し、画面は値を `context.route` から読むため)。シェルの無名コンストラクターがその `ShellState` を唯一の必須パラメーターとして取らない、ブランチを宣言していない、またはブランチが変数なしの `/` で始まるパスでない。パスが `/` で始まらない、波括弧の対応が取れていない、末尾以外に `{*rest}` がある、または同じ変数が二度ある。クエリパラメーターがパス変数と同じ名前を持つ。モジュールの二つの画面が同じパスを宣言している、または二つが見つからない場合の画面である。

画面とシェルは `spring_metadata.json` (`routes`、`shells`) にも列挙されます。[エディター向けのメタデータ](../metadata.md) を参照してください。

## Flutter のビルダー

メインのビルダーの他に、五つのビルダーが Flutter アプリに役立ちます。それぞれ、読むものを使わないパッケージには何も書き出さず、それぞれ独自のページがあります。

| ビルダー | 書き出すもの | ページ |
|---|---|---|
| `spring_flutter_keys` | `lib/spring_gen/theme.spring.keys.dart`、`lib/spring_gen/messages.spring.keys.dart` | [型付きキー](typed-keys.md) |
| `spring_flutter_web` | `web_dev_config.yaml` | [Web 開発サーバー](web-dev-server.md) |
| `spring_flutter_page_loader` | `web/index.html` のブロック | [ページローダー](page-loader.md) |
| `spring_flutter_seo` | `web/` の中のルートと Markdown ファイルごとのページ、`sitemap.xml`、`robots.txt`、`llms.txt` | [検索エンジン向けのページ](seo.md) |
| `spring_flutter_deep_links` | `Info.plist`、`Runner.entitlements`、`AndroidManifest.xml` のブロック。`apple-app-site-association`、`assetlinks.json` | [ディープリンク](deep-links.md) |

これらのビルダーがビルド時に読むプロパティは、[ビルドが読むプロパティ](../build-properties.md) に列挙されています。

## Spring (Java) との対応

Spring には対応するものがありません。コンテナの外でオブジェクトが生成される UI ツールキットを持たないからです。`@ChangeNotifierComponent` と `@NotifyListeners` は、`@Transactional` と同じく、Bean のメソッドの周りのアドバイスという Spring のモデルに従っています。

## 関連項目

- [型付きキー: context.theme と context.messages](typed-keys.md)
- [ビルダー](../builders.md)
- [AOP プロキシ: 刈り込みと遅延](../optimizations/aop-proxies.md)
- [エディター向けのメタデータ](../metadata.md)
- [プロキシ](../../spring-core-dart/aop/proxies.md)
