アプリのウィジェット

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

使う理由

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

例

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

# 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
# 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
# lib/resources/application-ios.yml: iPhone では iOS の見た目
spring:
  flutter:
    app:
      type: cupertino
@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、アプリファクトリー を参照) その種類
複数の種類のアプリファクトリー (たとえば二つのデザインのスターター) なし: 起動は失敗し、プロパティの設定を求める

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

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 はスターターに含まれています。メッセージと言語 を参照してください。

テーマ

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

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

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

// ユーザーが開くすべての画面をログに出す。
@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 を受け取ります。

// アプリ独自の翻訳と、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 の形式でのアプリのキーボードショートカット。設定でのアクションについては キーボードショートカット を参照

スターター自身もカスタマイザーを使います。キーボードショートカットとデバッグパネルは、その方法でナビゲーターの周りに組み込まれます。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.flutter.app.type はテキストです。アプリのウィジェットを組み立てる SpringAppFactory Bean の種類です。種類は大文字と小文字を区別せずに比べられます。

種類 アプリファクトリー 提供元
widgets WidgetsAppFactory spring_boot_starter_flutter (自身のもの)
material MaterialAppFactory (Bean materialAppFactory) spring_boot_starter_flutter_material
cupertino CupertinoAppFactory (Bean cupertinoAppFactory) spring_boot_starter_flutter_cupertino

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

// 会社独自のデザインシステムのアプリのウィジェット。
@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 を持ちます。デザインライブラリ を参照してください。

起動時にチェックされる

設定は、アプリケーションの起動時にコンテキストごとに一度作られます。不正な値 (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 を置きます (テスト を参照)。

関連項目