
# Flutter アプリでの設定

このスターターを使う Flutter アプリは、Spring Boot アプリと同じく、設定を設定ファイルに保持します。`lib/resources/` の `application.yml` または `application.properties` です。アプリのウィジェット、テーマ、スプラッシュ、ショートカット、言語、そして独自の設定がすべてそこにあります。このページでは、ファイルの置き場所、どのデバイスとビルドでどのファイルが読まれるか、どのソースが優先されるかを説明します。

## 使う理由

Dart のコードにある設定は、変更のたびに新しいビルドと開発者を必要とし、同じ `if (Platform.isIOS)` が多くの場所に書かれます。ファイルにすれば:

- デザイナーは一つの YAML ファイルでテーマを変更できます。
- プラットフォームは、コードではなくファイル名 (`application-ios.yml`) で独自の値を得ます。
- リリースビルドは、より静かなログなど、独自の値 (`application-release.yml`) を得ます。
- 顧客やステージ向けのビルドは、ファイルに触れずに `--dart-define` で値を変えます。

ルールは Spring Boot のものなので、`spring_core_dart` の [設定のページ](../spring-core-dart/config/index.md) がここでも当てはまります。このページでは、Flutter アプリに特有のことを挙げます。

## ファイル

```text
lib/
  main.dart
  resources/
    application.yml               # 常に読まれる
    application-web.yml           # ブラウザーでだけ読まれる
    application-ios.properties    # iPhone と iPad でだけ読まれる
    application-desktop.yml       # macOS、Windows、Linux で読まれる
    application-release.yml       # リリースビルドでだけ読まれる
    application-dev.yml           # dev プロファイルがアクティブなときに読まれる
    themes/
      ocean.yml                   # application.yml がインポートする
    messages.properties           # テキスト (英語)
    messages_ja.properties        # テキスト (日本語)
```

- **`pubspec.yaml` のエントリーは不要です。** ジェネレーターは `lib/resources/` のすべてのファイルを生成コード (`lib/spring_gen/main.spring.dart`) に埋め込みます。そのためファイルは、どのプラットフォームでも、デバッグビルドでもリリースビルドでも、Web でも同じように動きます。1 MB より大きいファイルは埋め込まれません (ビルドが警告します)。代わりに Flutter のアセットとして同梱してください。
- **YAML と `.properties` は同じ意味です。** どちらか、または両方を使ってください。一つの場所に両方がある場合、`.properties` が `.yml` より、`.yml` が `.yaml` より優先されます。
- **`resources:` は `lib/resources/` の中を指します。** `resources:themes/ocean.yml` は `lib/resources/themes/ocean.yml` です。Spring がクラスパスと呼ぶものです。
- **変更はホットリロードです。** ファイルは生成コードの一部なので、保存すると `build_runner watch` がそのコードを書き直し、次のホットリロードが新しい値でコンテキストを再起動します ([ホットリロード](hot-reload.md) を参照)。

両方の形式での同じ設定:

```yaml
# lib/resources/application.yml
spring:
  application:
    name: neon-books
  flutter:
    app:
      type: material
      title: NEON Books
      locales: en, ja
    theme:
      seed-color: deepPurple
shop:
  api-url: https://api.neon.books
  page-size: 20
```

```properties
# lib/resources/application.properties
spring.application.name=neon-books
spring.flutter.app.type=material
spring.flutter.app.title=NEON Books
spring.flutter.app.locales=en,ja
spring.flutter.theme.seed-color=deepPurple
shop.api-url=https://api.neon.books
shop.page-size=20
```

`type: material` と `seed-color` には、依存関係に [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) が必要です。デザインのスターターがそれ一つなら、`type: material` は省けます。Spring Boot がクラスパスから Web アプリケーションの種類を推定するのと同じように、スターターが決めます ([種類を設定しないとき](app-widget.md#種類を設定しないとき) を参照)。デザインライブラリのないアプリは `widgets` の種類で、色を `colors.*` の下に設定します ([デザインライブラリ](design-libraries.md) を参照)。

`spring.*` のキーはフレームワークを設定します。[すべてのプロパティ](properties.md) にこのスターターのものを列挙しています。`shop.*` のキーは独自のもので、`@Value` か `@ConfigurationProperties` クラスで読みます ([独自の設定を読む](#独自の設定を読む) を参照)。

## プラットフォームのプロファイル

プロファイルとは、設定ファイルと Bean を有効にする名前です。`SpringApplicationWidget` は、設定なしで、プラットフォームをアクティブなプロファイルにします。

| プラットフォーム | プロファイル |
|---|---|
| Android | `mobile`、`android` |
| iOS | `mobile`、`ios` |
| macOS | `desktop`、`macos` |
| Windows | `desktop`、`windows` |
| Linux | `desktop`、`linux` |
| ブラウザー | `web` |
| Fuchsia | `fuchsia` |

具体的なプロファイルはグループの後に来るため、優先されます: `application-ios.yml` が `application-mobile.yml` より、それが `application.yml` より優先されます。

```text
lib/resources/application.yml           shop.images: large
lib/resources/application-mobile.yml    shop.images: small     # スマートフォン: 小さい画像
lib/resources/application-ios.yml       push.provider: apns    # iPhone: Apple のプッシュサービス
```

Bean も同じプロファイルに従います。

```dart
// 各プラットフォームが独自のプッシュサービスを得る。
@Component()
@Profile(['android'])
class FcmPushService implements PushService { ... }

@Component()
@Profile(['ios'])
class ApnsPushService implements PushService { ... }

@Component()
@Profile(['desktop', 'web'])
class NoPushService implements PushService { ... }
```

プロファイルは Flutter の `defaultTargetPlatform` に従います。ウィジェットテストでは、テストが `debugDefaultTargetPlatformOverride` を設定しない限り、プラットフォームは Android です。

## ビルドモードのプロファイル

ビルドもプロファイルで、プラットフォームのものの後に追加されます。

| ビルド | プロファイル |
|---|---|
| `flutter run` (デバッグ) | `debug` |
| `flutter run --profile` | `profile` |
| `flutter run --release`、`flutter build ...` | `release` |

そのため `application-release.yml` はユーザーが実行するものを設定し、`application-web.yml` より優先されます。

```yaml
# lib/resources/application-release.yml
logging:
  level:
    root: warn
spring:
  flutter:
    frame-meter:
      enabled: false
```

ブラウザーでのリリースビルドでは、アクティブなプロファイルは `web` と `release` で、この順です。

## 独自のプロファイル

独自のプロファイル (`dev`、`staging`、`customer-a`) は Spring Boot と同じく選びます。Flutter アプリにはコマンドラインがないため、通常はビルド時の define を使います。

```bash
flutter run --dart-define=SPRING_PROFILES_ACTIVE=dev
flutter build apk --dart-define=SPRING_PROFILES_ACTIVE=staging
```

`spring.profiles.active` は `application.yml` でも設定でき、`spring.profiles.group.<name>` は一つのプロファイルで他のプロファイルを有効にします。プラットフォームとビルドのプロファイルは独自のものに追加され、置き換えられることはありません。ルール (どのファイルがどのキーを設定できるか、プロファイルの式) は [プロファイル](../spring-core-dart/config/profiles.md) を参照してください。

## 一部のプロファイルのためのドキュメント

別のファイルの代わりに、一つのファイルの中のドキュメントを一部のプロファイルに限定できます。プラットフォームごとのいくつかの値に便利です。

```yaml
# lib/resources/application.yml
shop:
  columns: 2
---
spring:
  config:
    activate:
      on-profile: desktop | web
shop:
  columns: 4
---
spring:
  config:
    activate:
      on-profile: ios & release
push:
  sandbox: false
```

`.properties` では、ドキュメントは `#---` の行で区切ります。

## インポート

`spring.config.import` は、設定ファイルの中からさらにファイルを読みます。大きな設定を分割するのに使ってください。テーマごと、機能ごと、地域ごとに一つのファイルです。

```yaml
# lib/resources/application.yml
spring:
  config:
    import:
      - resources:themes/ocean.yml
      - resources:themes/neon.yml
      - optional:resources:local.yml   # なくてもよい
```

- インポートされたファイルはそれをインポートするファイルより優先され、独自のプロファイルの変種を持ちます: `themes/ocean-web.yml` はブラウザーで読まれます。
- 相対的な場所は、インポートするファイルからの相対です。
- ファイルは一度だけ読まれるため、循環しても害はありません。
- `optional:` は、なくてもよい場所にします。

Flutter アプリがインポートできる場所:

| 場所 | 読むもの |
|---|---|
| `resources:themes/ocean.yml` | アプリに埋め込まれた `lib/resources/` のファイル |
| `asset:config/app.yml` | アプリのアセットバンドルからの Flutter のアセット (`flutter: assets:` の下で宣言) |
| `https://cfg.example.com/app.yml` | アプリの起動中に読まれるネットワーク上のファイル ([リモートのファイル](#リモートのファイル) を参照) |
| `file:./local.yml` | ディスク上のファイル。デスクトップアプリ用で、ブラウザーにはない |

## 独自のファイルに置くテーマ

テーマも他の設定と同じなので、独自のファイルに置けます。そのファイルは `spring.flutter.theme` の下のキーを設定します。

```yaml
# lib/resources/themes/ocean.yml
spring:
  flutter:
    theme:
      themes:
        ocean:
          extends: light
          seed-color: teal
          scheme-variant: vibrant
          components:
            card: { elevation: level0 }
        ocean-night:
          extends: ocean
          brightness: dark
```

```yaml
# lib/resources/application.yml
spring:
  config:
    import: resources:themes/ocean.yml
  flutter:
    theme:
      active: system
      system-light: ocean
      system-dark: ocean-night
```

このテーマは Material のアプリのためのものです。`seed-color` と `scheme-variant` にはデザインのスターターが必要で、`components` は spring_boot_starter_flutter_material が読みます ([テーマのプロパティ](themes/properties.md) を参照)。

テーマはライブラリから来ることもあります。アプリが依存するパッケージの `lib/resources/` フォルダーは同じクラスパス上にあるため、`lib/resources/themes/neon.yml` を同梱するパッケージは、アプリのファイルとまったく同じく `resources:themes/neon.yml` でインポートされます (`neon_ui` の NEON テーマはそのように使われます)。また、テーマは `themes.<name>.source` で単独でダウンロードし、キャッシュし、更新できます ([テーマのプロパティ](themes/properties.md) を参照)。

## リモートのファイル

Flutter アプリは非同期に起動するため、設定ファイルはネットワークから来ることもあります。`spring.config.import` の `https://` の場所です。起動はスプラッシュの背後でそのファイルを待ちます。

```yaml
# lib/resources/application.yml
spring:
  config:
    import: optional:https://config.neon.books/app/application.yml
```

三種類のリモートのコンテンツがサポートされており、それぞれ独自の動作をします。

| 対象 | 方法 | 読まれる時 |
|---|---|---|
| 設定ファイル | `spring.config.import: https://...` | 起動のたびに、Bean が作られる前 |
| テーマ | `spring.flutter.theme.themes.<name>.source` | 一度ダウンロードされてキャッシュされる。`refresh` でバックグラウンドで再び読まれる ([テーマのプロパティ](themes/properties.md) を参照) |
| すべてのテーマで共有する値 | `spring.flutter.theme.source` | テーマと同じ |
| テーマの画像 | 画像の `source: https://...` | アプリのファイルにキャッシュされる。起動を遅らせることはない ([画像](themes/images.md) を参照) |
| 独自のサーバーからのテーマ | コードでの `SpringThemes.loadYaml(yaml)` | コードがそれを呼ぶたびに ([テーマ](themes/index.md) を参照) |

テーマがダウンロードするすべてのアドレスは `https://` (または `github:owner/repo/path@ref`) でなければなりません。`http://` のアドレスは、`spring.remote.allow-insecure=true` でない限り、プロパティを示して「the connection is not secure」で起動を止めます。

## `--dart-define`

Flutter アプリにはコマンドラインがなく、スマートフォンでは OS の環境は役に立ちません。一つのビルドのための値は、代わりに `--dart-define` から来ます。それらは設定ファイルより優先されるプロパティソースになります。

```bash
flutter run --dart-define=SPRING_PROFILES_ACTIVE=dev --dart-define=SHOP_API_URL=http://localhost:8080
flutter build web --dart-define-from-file=config/prod.json
```

- define は Spring Boot の環境変数と同じように読まれます。`SHOP_API_URL` は `shop.api-url` と `@Value(r'${SHOP_API_URL}')` に応えます。そのままの名前 (`shop.api-url`) も使えます。
- コンパイルされたアプリが読めるのは、ジェネレーターが `main.spring.dart` に名前を書き込んだ define だけです。`String.fromEnvironment` は定数の名前を必要とするためです。ジェネレーターはアプリが読めるすべての名前を書き込みます。アノテーションの `${...}` のプレースホルダー、`@ConfigurationProperties` クラスのフィールド、設定ファイルのキー、そして `spring.profiles.active` などいくつかのものです。それ以外の名前の define は見えません。[--dart-define のキー](../spring-core-dart-generator/dart-defines.md) を参照してください。
- ビルド時に定義したものはすべてアプリに入り、そこから読めます。シークレットを置いてはいけません。

## OS の環境

`SpringApplicationWidget` は環境変数を読みません。デスクトップのビルドでは有効にできます。

```bash
flutter run -d macos --dart-define=spring.flutter.scan-os-environment=true
```

このキーは環境をそもそも読むかどうかを決めるため、設定できるのは `--dart-define` だけで、設定ファイルからは設定できません。引数付きで起動するデスクトップアプリは、`SpringApplicationWidget(args: ...)` でそれらを渡します。それらは `--name=value` のプロパティとして読まれます。

## どのソースが優先されるか

優先度の高いものから:

1. テストでの `springBootTest(properties: ...)`
2. `SpringApplicationWidget(args: ...)`
3. `--dart-define` の値
4. OS の環境変数 (`spring.flutter.scan-os-environment=true` の場合のみ)
5. 設定ファイル: インポートされたファイルはそれをインポートするファイルより上。プロファイルのファイルは普通のファイルより上で、最後のプロファイルが最も上 (そのためビルドのプロファイル、次にプラットフォームの具体的なもの、次にそのグループ)。`.properties` は `.yml` より、`.yml` は `.yaml` より上。後のドキュメントは前のドキュメントより上
6. `SpringApplication(defaultProperties: ...)`
7. スターターが SQLite のために設定する値 (`spring.datasource.sqlite.*`)。すべてより下 ([SQLite データベース](sqlite.md) を参照)

## 独自の設定を読む

独自のキーは、どの Spring アプリとも同じように読みます。設定のグループは `@ConfigurationProperties` クラスで、起動時にチェックされます。

```dart
// 任意のファイルや define からの shop.api-url と shop.page-size。
@ConfigurationProperties('shop')
@Validated()
class ShopProperties {
  String apiUrl = 'https://api.neon.books';

  @Min(5)
  @Max(100)
  int pageSize = 20;
}

@Service()
class Catalog {
  Catalog(this.shop, @Value(r'${shop.currency:EUR}') this.currency);

  final ShopProperties shop;
  final String currency;
}
```

`SizeConstraint` は、別の名前の `@Size` 制約です。Flutter の `Size` はウィジェットのコードのいたるところにあるためです。[@ConfigurationProperties](../spring-core-dart/config/configuration-properties.md) と [@Value](../spring-core-dart/config/value.md) を参照してください。

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

スターターのすべてのキーは、アプリケーションの起動時にチェックされます。不正な値 (`spring.flutter.app.type=swing`)、綴りを誤ったテーマのキー (`seed-colour`)、どの記法でも読めないショートカットは、起動を止めます。その場合 `SpringApplicationWidget` は失敗画面を表示し、プロパティ、値、許可されるものを示すレポートを、しばしば「did you mean」付きでログに出します。黙って無視されるものはありません。スターターがアプリケーションにないデザインのテーマのプロパティ (`components`、`cupertino` など) は受け入れられ、チェックされず、ログで一度だけ名前を挙げられます ([テーマのプロパティ](themes/properties.md) を参照)。

ジェネレーターはスターターのメタデータも書き出すため、補完機能のあるエディターは、すべてのキーをその型と説明とともに候補に出します ([エディター用のメタデータ](../spring-core-dart-generator/metadata.md) を参照)。

## 実際の設定

これらのスターターで作られたサイト (今読んでいるもの) は、三つのファイルを使います。

```yaml
# lib/resources/application.yml (一部)
spring:
  config:
    import: resources:themes/neon.yml
  flutter:
    app:
      type: widgets
      title: Spring for Dart
      description: Spring's programming model for Dart and Flutter.
      debug-banner: false
    shortcuts:
      search.open: [primary+k, slash]
    web:
      dev-server:
        port: 5110
        host: 127.0.0.1
    theme:
      source: github:farum-azula/themes/themes/code.yml@code-v0.2.0
      active: system
      system-light: spring-dart-light
      system-dark: spring-dart
```

```yaml
# lib/resources/application-web.yml (一部): ブラウザーだけが読む
spring:
  flutter:
    splash:
      warm-up:
        text:
          enabled: true
    web:
      page:
        swipe-to-close: false
        max-pixel-ratio: 2
        translate: false
```

```yaml
# lib/resources/application-release.yml: リリースビルドだけが読む
logging:
  level:
    root: warn
```

## 関連項目

- [spring_core_dart の設定](../spring-core-dart/config/index.md)
- [プロファイル](../spring-core-dart/config/profiles.md)
- [プレースホルダー](../spring-core-dart/config/placeholders.md)
- [すべてのプロパティ](properties.md)
- [テーマ](themes/index.md)
