Flutter アプリでの設定

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

使う理由

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

ルールは Spring Boot のものなので、spring_core_dart の 設定のページ がここでも当てはまります。このページでは、Flutter アプリに特有のことを挙げます。

ファイル

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        # テキスト (日本語)

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

# 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
# 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 が必要です。デザインのスターターがそれ一つなら、type: material は省けます。Spring Boot がクラスパスから Web アプリケーションの種類を推定するのと同じように、スターターが決めます (種類を設定しないとき を参照)。デザインライブラリのないアプリは widgets の種類で、色を colors.* の下に設定します (デザインライブラリ を参照)。

spring.* のキーはフレームワークを設定します。すべてのプロパティ にこのスターターのものを列挙しています。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 より優先されます。

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 も同じプロファイルに従います。

// 各プラットフォームが独自のプッシュサービスを得る。
@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 より優先されます。

# 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 を使います。

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> は一つのプロファイルで他のプロファイルを有効にします。プラットフォームとビルドのプロファイルは独自のものに追加され、置き換えられることはありません。ルール (どのファイルがどのキーを設定できるか、プロファイルの式) は プロファイル を参照してください。

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

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

# 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 は、設定ファイルの中からさらにファイルを読みます。大きな設定を分割するのに使ってください。テーマごと、機能ごと、地域ごとに一つのファイルです。

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

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 の下のキーを設定します。

# 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
# 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 が読みます (テーマのプロパティ を参照)。

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

リモートのファイル

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

# 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 でバックグラウンドで再び読まれる (テーマのプロパティ を参照)
すべてのテーマで共有する値 spring.flutter.theme.source テーマと同じ
テーマの画像 画像の source: https://... アプリのファイルにキャッシュされる。起動を遅らせることはない (画像 を参照)
独自のサーバーからのテーマ コードでの SpringThemes.loadYaml(yaml) コードがそれを呼ぶたびに (テーマ を参照)

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

--dart-define

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

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

OS の環境

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

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 データベース を参照)

独自の設定を読む

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

// 任意のファイルや 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 と @Value を参照してください。

起動時にチェックされる

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

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

実際の設定

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

# 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/[email protected]
      active: system
      system-light: spring-dart-light
      system-dark: spring-dart
# 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
# lib/resources/application-release.yml: リリースビルドだけが読む
logging:
  level:
    root: warn

関連項目