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 の 設定のページ がここでも当てはまります。このページでは、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 # テキスト (日本語)
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がそのコードを書き直し、次のホットリロードが新しい値でコンテキストを再起動します (ホットリロード を参照)。
両方の形式での同じ設定:
# 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 # なくてもよい
- インポートされたファイルはそれをインポートするファイルより優先され、独自のプロファイルの変種を持ちます:
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 の下のキーを設定します。
# 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
- 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 のキー を参照してください。 - ビルド時に定義したものはすべてアプリに入り、そこから読めます。シークレットを置いてはいけません。
OS の環境
SpringApplicationWidget は環境変数を読みません。デスクトップのビルドでは有効にできます。
flutter run -d macos --dart-define=spring.flutter.scan-os-environment=true
このキーは環境をそもそも読むかどうかを決めるため、設定できるのは --dart-define だけで、設定ファイルからは設定できません。引数付きで起動するデスクトップアプリは、SpringApplicationWidget(args: ...) でそれらを渡します。それらは --name=value のプロパティとして読まれます。
どのソースが優先されるか
優先度の高いものから:
- テストでの
springBootTest(properties: ...) SpringApplicationWidget(args: ...)--dart-defineの値- OS の環境変数 (
spring.flutter.scan-os-environment=trueの場合のみ) - 設定ファイル: インポートされたファイルはそれをインポートするファイルより上。プロファイルのファイルは普通のファイルより上で、最後のプロファイルが最も上 (そのためビルドのプロファイル、次にプラットフォームの具体的なもの、次にそのグループ)。
.propertiesは.ymlより、.ymlは.yamlより上。後のドキュメントは前のドキュメントより上 SpringApplication(defaultProperties: ...)- スターターが 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