
# SpringApplicationWidget

`SpringApplicationWidget` は、`runApp` に渡すルートのウィジェットです。アプリケーションを起動します。設定ファイルを読み、Bean を作り、アプリケーションのランナーを実行します。その間、スプラッシュ画面を表示します。起動が失敗すると、失敗画面を表示してレポートをログに出します。コンテキストの準備ができると、その下のすべてのウィジェットにそれを渡します。

## 使う理由

Spring のアプリケーションは非同期に起動します。ファイルが読まれ、フォントが読み込まれ、Bean が作られます。Flutter アプリは最初のフレームから何かを描かなければなりません。このウィジェットは二つを結び付けます。`runApp` に一つのウィジェットを置くと、アプリはコンテキストが起動する間スプラッシュを表示し、その後アプリそのものを表示します。また、Flutter アプリには必要でサーバーには不要なことも行います。プラットフォームのプロファイル、アプリのライフサイクル、ホットリロード、デスクトップのウィンドウです。

## 例

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

import 'spring_gen/main.spring.dart';

@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    // 値ではなく関数: ホットリロードの後、ウィジェットはこれを
    // 再び呼んで新しい生成コードを得る。
    application: () => springApplication,
    // 省略可能: ビルダーがなければテーマのスプラッシュが使われる。
    splash: (context) => const ColoredBox(color: Color(0xFFFFFFFF)),
    failure: (context, error) => ErrorScreen(error),
    home: const BookListPage(),
  ),
);
```

## パラメーター

| パラメーター | デフォルト | 意味 |
|---|---|---|
| `application` | 必須 | 実行するアプリケーションを返す: `() => springApplication`。ジェネレーターが `main.spring.dart` に書き出す変数 |
| `home` | なし | 最初のページ。ウィジェットは `spring.flutter.app.*` から、その周りにアプリのウィジェットを組み立てる ([アプリのウィジェット](app-widget.md) を参照) |
| `child` | なし | 代わりに使う独自のアプリのウィジェット (`MaterialApp` など)。`home` か `child` のどちらかを指定し、両方は指定しない |
| `splash` | テーマの `splash`、なければ空のボックス | アプリケーションの起動中に表示されるもの。テーマのスプラッシュより優先される |
| `failure` | エラーを示す簡素な画面 (リリースビルドでは短い注記だけ) | 起動、またはホットリロード後の再起動が失敗したときに表示されるもの。失敗はどちらの場合もログに出る |
| `args` | なし | コマンドライン引数 (`--name=value`)。プロパティとして読まれる。引数付きで起動するデスクトップアプリ用 |
| `rerunRunnersOnReload` | `false` | ホットリロードがコンテキストを再起動した後に、`ApplicationRunner` と `CommandLineRunner` の Bean を再び実行するかどうか |

`home` も `child` もない場合、アプリのウィジェットはアプリケーションのルーター、つまり [spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md) が追加する `RouterConfig<Object>` Bean の上に組み立てられます。ルーターがなければ、起動は何を追加すべきかを示すメッセージとともに失敗します。

## 行うこと

アプリケーションの起動のほかに、ウィジェットは次のことを行います。

- プラットフォームのプロファイル (`android` と `mobile`、`web`、`macos` と `desktop` など) とビルドのプロファイル (`debug`、`profile`、`release`) を追加します。[設定](configuration.md) を参照してください。
- ビルドが `spring.flutter.scan-os-environment=true` を定義しない限り、OS の環境変数を読みません。
- アプリのアセットの中のフォントファイルを読み込みます ([アセットとフォント](assets-and-fonts.md) を参照)。
- 起動の進行に従うアクティブなテーマのスプラッシュを表示し、アプリが表示される前に `SplashTask` Bean を実行します ([スプラッシュと起動](splash.md) を参照)。
- Spring のウィジェットが必要とするすべての Bean が存在するかをチェックします。そのため、存在しないものは後の `build` ではなく起動を失敗させます。
- 最初のフレームの前に、`spring.flutter.desktop.window.*` からデスクトップのウィンドウを設定します ([デスクトップのウィンドウ](desktop-window.md) を参照)。
- SQLite のデータベースをアプリのディレクトリに置きます ([SQLite データベース](sqlite.md) を参照)。
- アプリのライフサイクルを発行し、バックグラウンドではコンテキストを一時停止します ([アプリのライフサイクル](lifecycle.md) を参照)。
- Bean を変更したホットリロードの後に、コンテキストを再起動します ([ホットリロード](hot-reload.md) を参照)。
- ツリーから取り除かれるとコンテキストを閉じます。`@PreDestroy` メソッドが実行され、ライフサイクルの Bean が停止します。

## 起動が失敗したとき

例外を投げる Bean、不正な値のプロパティ、存在しない Bean は起動を止めます。その場合ウィジェットは:

1. Spring Boot アプリと同じく、失敗のレポート (原因、Bean、プロパティ、有効な値) をログに出します。
2. `failure`、またはそのデフォルトの画面を表示します。デバッグビルドとプロファイルビルドではエラーを、リリースビルドでは短い注記を表示します。

問題を修正したホットリロードの後、ウィジェットはアプリケーションを新たに起動します。

```dart
// 開発者向けのエラーを持つ、アプリのスタイルの失敗画面。
SpringApplicationWidget(
  application: () => springApplication,
  failure: (context, error) => Directionality(
    textDirection: TextDirection.ltr,
    child: Center(child: Text(kReleaseMode ? 'Something went wrong.' : '$error')),
  ),
  home: const BookListPage(),
)
```

失敗画面はどのアプリのウィジェットよりも上に表示されるため、`Theme.of` や `Localizations` は使えません。`Directionality` など、必要なものを与えてください。

## 独自のアプリのウィジェット

`child` では、アプリのウィジェットを自分で書き、`spring.flutter.app.*` のキーは使われません。テーマは引き続き動きます。`SpringThemes` と `ThemeSelection` の Bean から読んでください。`MaterialApp` は、Material の `ThemeData` を [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) の `MaterialThemes` Bean から受け取ります。キーボードショートカットはその `builder` に置きます ([キーボードショートカット](shortcuts.md) を参照)。

```dart
// MaterialApp: material_ui と spring_boot_starter_flutter_material。
SpringApplicationWidget(
  application: () => springApplication,
  child: Builder(
    builder: (context) => MaterialApp(
      title: 'NEON Books',
      theme: context.bean<MaterialThemes>().theme('light'),
      builder: (context, child) => KeyboardShortcutsScope(
        shortcuts: context.bean<KeyboardShortcuts>(),
        child: child!,
      ),
      home: const BookListPage(),
    ),
  ),
)
```

## テストでは

起動そのもの (スプラッシュ、失敗した起動、プラットフォームのプロファイル) をテストするには、`runApp` と同じく `SpringApplicationWidget` を pump します。このウィジェットは Bean のオーバーライドを受け取りません。ほとんどのウィジェットテストでは、代わりに `springBootTest` と `SpringScope` を使ってください ([テスト](testing.md) を参照)。

## Spring (Java) との対応

Spring にはウィジェットがありません。最も近いものは Spring Boot アプリの `main` メソッド、`SpringApplication.run(App.class, args)` です。失敗のレポートは、Spring Boot アプリが出力するものと同じです。

## 関連項目

- [アプリのウィジェット](app-widget.md)
- [スプラッシュと起動](splash.md)
- [ホットリロード](hot-reload.md)
- [Flutter アプリでの設定](configuration.md)
