
# アプリのウィジェット

`home:` を指定すると、`SpringApplicationWidget` はルートに `SpringApp` を置きます。コードではなくプロパティで設定される `WidgetsApp`、またはデザインのスターターがあれば `MaterialApp` や `CupertinoApp` です。その種類、タイトル、デバッグバナー、ロケールは `spring.flutter.app.*` から、テーマは `spring.flutter.theme.*` から来ます。プロパティはプロファイルごとに変えられるため、iPhone では `CupertinoApp`、他のプラットフォームでは `MaterialApp` にできます。

## 使う理由

アプリのウィジェットのほとんどは設定です。タイトル、ロケール、テーマとダークテーマ、オブザーバーです。Dart で書くと、メッセージファイルやテーマと手で同期を保たなければなりません。プロパティからなら、ロケールはメッセージファイルに、テーマはテーマのファイルに従い、プラットフォームやビルドはファイル名でそれらを変えます。

## 例

ほとんどのプラットフォームでは Material、iPhone では Cupertino: アプリは二つのデザインのスターターとそのライブラリを列挙します。デザインのスターターが二つあるので、すべてのプラットフォーム向けに種類を選び、iOS のプロファイルでもう一度選びます ([種類を設定しないとき](#種類を設定しないとき) を参照)。デザインのスターターが一つのアプリは `type` を省きます。

```yaml
# pubspec.yaml
dependencies:
  material_ui: ^1.11.0
  cupertino_ui: ^1.1.6
  spring_boot_starter_flutter_material: ^0.9.0
  spring_boot_starter_flutter_cupertino: ^0.9.0
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    app:
      type: material
      title: NEON Books
      description: The bookshop of the NEON district.
      debug-banner: false
      locales: en, ja, pt_BR
```

```yaml
# lib/resources/application-ios.yml: iPhone では iOS の見た目
spring:
  flutter:
    app:
      type: cupertino
```

```dart
@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    home: const BookListPage(), // MaterialApp、iOS では CupertinoApp
  ),
);
```

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.app.type` | テキスト: `widgets`、`material`、`cupertino`、または独自のアプリファクトリーの種類 | 未設定: 唯一のデザインのスターターの種類 (`material`、`cupertino`)、なければ `widgets`。複数あるときは必須 | アプリのウィジェット: `WidgetsApp` (このスターター自身のもの、デザインライブラリなし)、`MaterialApp` (`spring_boot_starter_flutter_material` が必要。`Scaffold`、`AppBar` などの Material のウィジェットに必要)、`CupertinoApp` (`spring_boot_starter_flutter_cupertino` が必要)。[アプリファクトリー](#アプリファクトリー) を参照 |
| `spring.flutter.app.title` | テキスト | 空 | OS に対するアプリの名前: タスクスイッチャー、ブラウザーのタブ。Web のビルドは `web/index.html` (`<title>`) と `web/manifest.json` (`name`、`short_name`) にも書き込む |
| `spring.flutter.app.description` | テキスト | なし | アプリが何であるかを一文で。実行時には使われない。Web のビルドが `web/index.html` (`<meta name="description">`) と `web/manifest.json` に書き込む |
| `spring.flutter.app.debug-banner` | `true`、`false` | `true` | デバッグビルドでの Flutter の DEBUG バナー |
| `spring.flutter.app.locales` | カンマ区切りの言語タグ (`en`、`pt_BR`、`zh_Hant_TW`) | メッセージファイルの言語 | アプリがサポートするロケール |

`locales` は、YAML でも一つのカンマ区切りの値として書いてください (`locales: en, ja`)。アプリのウィジェットはこれを一つの値として読むため、YAML のリスト (`[en, ja]`) は見えず、その場合ロケールはメッセージファイルから来ます。

## 種類を設定しないとき

`spring.flutter.app.type` は設定しなくてもかまいません。Spring Boot がクラスパスから `spring.main.web-application-type` を推定するのと同じように、アプリケーションのスターターが決めます。

| アプリケーションにあるもの | アプリの種類 |
|---|---|
| デザインのスターターなし | `widgets`、`WidgetsApp` |
| デザインのスターターが一つ: `spring_boot_starter_flutter_material` または `spring_boot_starter_flutter_cupertino` | `material` または `cupertino` |
| 独自の種類の `SpringAppFactory` Bean が一つ (`ocean`、[アプリファクトリー](#アプリファクトリー) を参照) | その種類 |
| 複数の種類のアプリファクトリー (たとえば二つのデザインのスターター) | なし: 起動は失敗し、プロパティの設定を求める |

複数あるとき、失敗のレポートはプロパティと種類を示します。

```text
Invalid argument(s) (spring.flutter.app.type): not set, and the application has app widgets of several types: cupertino, material. Choose one, for every platform or in a profile of each (spring.flutter.app.type=cupertino in application-ios.properties)
```

設定されていれば、プロパティが常に優先されます。デザインのスターターが別のパッケージ経由で入ってきても、`widgets` なら `WidgetsApp` のままです。種類を設定しているアプリは、スターターを追加しても変わりません。

## ロケール

デフォルトでは、アプリはテキストを持つ言語をサポートします。`messages.properties` は英語とみなされ、各 `messages_<locale>.properties` がそのロケールを追加します (`messages_ja` は `ja` を、`messages_pt_BR` は `pt_BR` を追加します)。そのため、アプリのロケールと `context.message` が一致します。`messages*.properties` 以外のファイルを使う場合は、`spring.messages.basename` を `/` を区切りとする一つのカンマ区切りの値 (`i18n/messages,i18n/errors`) として設定すると、スターターはそれらのファイルのロケールを探します。

アプリの種類に応じた Flutter 自身の翻訳 (すべての言語でのそのウィジェットのテキスト) は、その種類のアプリファクトリーが追加します (`SpringAppFactory.localizationsDelegates`)。`widgets` には `GlobalWidgetsLocalizations`、Material のスターターのファクトリーは Material のもの (`GlobalMaterialLocalizations`) を、Cupertino のスターターのファクトリーは Cupertino のもの (`GlobalCupertinoLocalizations`) を追加します。`flutter_localizations` はスターターに含まれています。[メッセージと言語](messages.md) を参照してください。

## テーマ

表示されるテーマは、`ThemeSelection` Bean が選ぶものです。`widgets` はテーマのテキストスタイルと色を受け取ります。Material のスターターがあれば、`material` は表示されるテーマの Material の `ThemeData` (そして `system` ではそのダークの対応物) を、Cupertino のスターターがあれば、`cupertino` は `CupertinoThemeData` を受け取ります。実行時に選ばれたテーマや、サーバーから読み込まれたテーマは即座に表示されます。アプリの上の `SpringTheme` が、アプリ自身のウィジェットにテーマを渡します。[テーマ](themes/index.md) を参照してください。

## ナビゲーターのオブザーバー

すべての `NavigatorObserver` Bean は、`@Order` の順でアプリのナビゲーターのオブザーバーになります。

```dart
// ユーザーが開くすべての画面をログに出す。
@Component()
@Log()
class ScreenLog extends NavigatorObserver {
  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) =>
      log.info('Opened ${route.settings.name}');
}
```

## FlutterAppCustomizer

どのプロパティも扱わないものは、`FlutterAppCustomizer` Bean で変更します。`builder`、キーボードの `shortcuts`、`scrollBehavior`、アプリ独自のローカリゼーションのデリゲートです。それぞれが、アプリのウィジェットが最初に組み立てられる前に一度、`@Order` の順で `FlutterAppSettings` を受け取ります。

```dart
// アプリ独自の翻訳と、130 % を超えて大きくならないテキスト。
@Component()
class AppLocalizations implements FlutterAppCustomizer {
  @override
  void customize(FlutterAppSettings app) {
    app.localizationsDelegates.add(LegalTerms.delegate);
    app.builder = (context, child) => MediaQuery.withClampedTextScaling(
      maxScaleFactor: 1.3,
      child: child!,
    );
  }
}
```

`FlutterAppSettings` のフィールド:

| フィールド | 由来 | 意味 |
|---|---|---|
| `type` | `spring.flutter.app.type`、未設定ならスターターが決めた種類 | アプリのウィジェットを組み立てるアプリファクトリーの種類。`String` (`widgets`、`material`、`cupertino`) |
| `title` | `spring.flutter.app.title` | OS に対するアプリの名前 |
| `debugShowCheckedModeBanner` | `spring.flutter.app.debug-banner` | DEBUG バナー |
| `supportedLocales` | `spring.flutter.app.locales` またはメッセージファイル | アプリのロケール |
| `localizationsDelegates` | アプリファクトリーのもの (種類に応じた Flutter のもの) | アプリ独自のものをここに追加する |
| `navigatorObservers` | `NavigatorObserver` Bean | ナビゲーターのオブザーバー |
| `builder` | `null` | `MaterialApp.builder` のように、ナビゲーターを包む |
| `scrollBehavior` | `null` | アプリのスクロールの動作 (`WidgetsApp` では使われない) |
| `shortcuts` | `null` | Flutter の形式でのアプリのキーボードショートカット。設定でのアクションについては [キーボードショートカット](shortcuts.md) を参照 |

スターター自身もカスタマイザーを使います。キーボードショートカットとデバッグパネルは、その方法でナビゲーターの周りに組み込まれます。Spring Boot (Java) も、`WebServerFactoryCustomizer` Bean で同じように Web サーバーをカスタマイズします。

## ルート

`home` は最初のページで、アプリは `Navigator` でナビゲートします。`home` がなければ、`SpringApp` はアプリケーションの `RouterConfig<Object>` Bean の上に、アプリのウィジェットのルーター版 (`WidgetsApp.router`、またはデザインのスターターの `MaterialApp.router` や `CupertinoApp.router`) を組み立てます。その Bean は [spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md) が追加するもの、またはアプリ独自のものです。

## アプリファクトリー

`spring.flutter.app.type` はテキストです。アプリのウィジェットを組み立てる `SpringAppFactory` Bean の種類です。種類は大文字と小文字を区別せずに比べられます。

| 種類 | アプリファクトリー | 提供元 |
|---|---|---|
| `widgets` | `WidgetsAppFactory` | `spring_boot_starter_flutter` (自身のもの) |
| `material` | `MaterialAppFactory` (Bean `materialAppFactory`) | [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) |
| `cupertino` | `CupertinoAppFactory` (Bean `cupertinoAppFactory`) | [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md) |

独自のデザインは、もう一つの Bean です。

```dart
// 会社独自のデザインシステムのアプリのウィジェット。
@Component()
class OceanAppFactory implements SpringAppFactory {
  @override
  String get type => 'ocean';

  @override
  List<LocalizationsDelegate<Object?>> get localizationsDelegates =>
      const [GlobalWidgetsLocalizations.delegate];

  @override
  Widget build(BuildContext context, SpringAppRequest app) =>
      OceanApp(title: app.settings.title, home: app.home);
}
```

これで `spring.flutter.app.type: ocean` は `OceanApp` を組み立てます。アプリケーションにデザインのスターターがなければ、唯一の独自のファクトリーが決めるので、種類を設定する必要はありません。`SpringAppRequest` は、設定、テーマ、テーマの選択、表示されるテーマ、そのまま渡す `builder`、そして `home` または `router` を持ちます。[デザインライブラリ](design-libraries.md) を参照してください。

## 起動時にチェックされる

設定は、アプリケーションの起動時にコンテキストごとに一度作られます。不正な値 (`debug-banner=maybe`) は、プロパティを示す失敗のレポートとともに起動を失敗させます。どのアプリファクトリーも持たない種類も同じです。スターターのない `material` や `cupertino` は、追加すべきスターターを示し (`the app widget of type material is built by spring_boot_starter_flutter_material: add it to the dependencies (this application has: widgets)`)、それ以外の種類は既知の種類を列挙します (`type=swing` なら `one of: widgets`)。

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

`SpringApplicationWidget(child: ...)` では独自のアプリのウィジェットを書き、これらのキーは使われません。ウィジェットテストでは、プロパティのアプリのウィジェットを得るために、`SpringScope` の下に `SpringApp` を置きます ([テスト](testing.md) を参照)。

## 関連項目

- [SpringApplicationWidget](application-widget.md)
- [デザインライブラリ](design-libraries.md)
- [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md)
- [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md)
- [テーマ](themes/index.md)
- [メッセージと言語](messages.md)
- [すべてのプロパティ](properties.md)
