YAML による Flutter のテーマ

spring_boot_starter_flutter では、アプリの見た目は ThemeData のコードではなく設定にあります。色、フォント、形状、コンポーネントのスタイル、背景、アニメーションを、application.yml の spring.flutter.theme の下に書きます。スターターはアプリの起動時にそれらを読み、独自のテーマ (SpringThemeData: パレット、タイプスケール、余白、形状、トークン、スタイル、背景、モーション) にします。これはすべてのアプリが持ち、デザインライブラリのないアプリも持ちます。デザインのスターターがあれば、同じテーマは Material の ThemeData (spring_boot_starter_flutter_material) や Cupertino の CupertinoThemeData (spring_boot_starter_flutter_cupertino) にもなります。デザイナーは、ウィジェットに触れずに、一つのファイルで、プロファイルやプラットフォームごとに見た目を変えられます。

最初のテーマ

spring:
  flutter:
    theme:
      colors:
        primary: '#0057B8'
        on-primary: '#FFFFFF'
        surface: '#FAFAFA'
      typography:
        font-family: Inter
        title-large: { weight: 600 }
      shape:
        medium: 16
      spacing:
        m: 16

これで完全なテーマで、どのアプリでも動きます。デザインライブラリのないアプリでも、Material のアプリでも、Cupertino のアプリでもです。書かなかったものはすべて Flutter の Material 3 のデフォルトのままです。設定しないロールは Flutter のベースラインのパレットから、設定しないテキストスタイルは Material 3 のタイプスケールのままです。プロパティを一つも持たないテーマは、Flutter 自身のベースラインです。

デザインライブラリ

spring_boot_starter_flutter はデザインライブラリを知りません。すべてのデザインが共有するもの (パレットのロール、タイポグラフィ、形状、余白、トークン、スタイル、モーション、背景、ローダー、画像) は、これらのページにあります。一つのデザインに属するものは、そのスターターとともに説明しています。

デザインのスターターがあれば、最初のテーマはもっと短くできます。シードが 46 のロールすべてを作ります。

spring:
  flutter:
    theme:
      seed-color: deepPurple    # デザインのスターターが必要
      typography:
        font-family: Inter

これらのページのうち seed-color を使う例は、デザインのスターターを持つアプリのためのものです。それを持たないアプリは、ロールを colors.* の下に書きます (色 と デザインライブラリ を参照)。

すべての値は起動時にチェックされます。綴りを誤ったキー、存在しない色、単語が期待される場所の数値は、プロパティ、値、許可されるものを示すメッセージとともに、しばしば「did you mean」付きで起動を止めます。黙って無視されるものはありません。スターターがアプリにないデザインのプロパティ (components、cupertino、そしてデザインのプロパティに挙げたその他のもの) は受け入れられ、チェックされず、ログで一度だけ名前を挙げられます。

テーマの選ばれ方

三つの部分があります。

  1. spring.flutter.theme のルートは、すべてのテーマで共有されます。
  2. light と dark は常に存在します。それらで異なる部分だけを変えるには、themes.light や themes.dark を書きます。
  3. 任意の数の独自のテーマが themes.<name> の下にあります。それぞれは変更する部分だけを持ちます。
spring:
  flutter:
    theme:
      active: system          # system、またはテーマの名前
      system-light: light     # ライトモードで "system" が表示するもの
      system-dark: dark       # ダークモードで "system" が表示するもの

      seed-color: deepPurple  # すべてのテーマで共有

      themes:
        dark:
          seed-color: deepPurple.shade200
        ocean:
          seed-color: teal
          scheme-variant: vibrant
        ocean-night:
          extends: ocean      # ルートではなく ocean から始める
          brightness: dark
キー 場所 働き
active ルート 起動時に表示するテーマ。system (デフォルト) はデバイスのライトモードまたはダークモードに従う
system-light ルート デバイスがライトモードのときに system が表示するテーマ。デフォルトは light
system-dark ルート デバイスがダークモードのときに system が表示するテーマ。デフォルトは dark
remember ルート ユーザーが選んだテーマを実行をまたいで保持し、スプラッシュの表示中に再び表示する。デフォルトは true
themes.<name> ルート 独自のテーマ、または light や dark への変更
extends themes.<name> の中 ルートの代わりに別のテーマからテーマを始める。連鎖も使える。循環や未知の名前は起動を止める

テーマは層で作られ、それぞれが前の層の上に重なります。

  1. その明るさ (dark テーマでは dark、それ以外は light)。
  2. ルート、またはそれが extends するテーマ。
  3. それ自身のキー。

後の層のリストは、前の層のリスト全体を置き換えます。参照 ($colors.primary) は層が組み合わされた後に解決されるため、colors.primary を変えるテーマは、それを参照するすべてのものも変えます。トークンと参照 を参照してください。

テーマ名とプロパティ名は、大文字小文字、-、_ を区別せずに比較されます。seed-color、seedColor、seed_color は同じキーで、Ocean-Night と ocean_night は同じテーマです。

実行時に選び、切り替える

ThemeSelection Bean が選択を保持します。設定ページが select を呼ぶと、アプリ全体が即座に変わります。

selection.select('ocean');    // テーマ
selection.select('system');   // 再びデバイスに従う

選択は実行をまたいで保持されます (remember: true、デフォルト)。ThemeSelection はそれをアプリのファイルに書き込み、次の起動ではスプラッシュの表示中に再び表示するため、再読み込みでデフォルトのテーマが一瞬表示されることはありません。ThemeChoiceStore Bean は、サーバー上のアカウントの設定など、別の場所にそれを保持します。テーマは実行時に届くこともあります。themes.loadYaml(yaml) はサーバーからの YAML を追加し、テーマは単独で URL からダウンロードすることもできます (プロパティ を参照)。

Dart でテーマを読む

SpringTheme.of(context) は、どの種類のアプリでも、テーマのすべてを持ちます。

final theme = SpringTheme.of(context);
Container(
  padding: EdgeInsets.all(theme.space('m')),
  color: theme.colorScheme.surfaceContainer,
  child: Text(isbn, style: theme.textStyle('code')),
);

デザインライブラリのウィジェットは、テーマをそれぞれの形で読みます。Material のものは Theme.of(context) から (プロパティからのテーマ を参照)、Cupertino のものは CupertinoTheme.of(context) からです。

型付きのキー: context.theme

ビルドのジェネレーターはプロパティを読み、lib/spring_gen/theme.spring.keys.dart を書き出します。そこから、context.theme は宣言したすべてのキーのゲッターを持つため、プロパティの名前を変えると、実行時の驚きではなくコンパイルエラーになります。

context.theme.colors.surfaceContainerLow;   // Color
context.theme.spacing.m;                    // double
context.theme.typography.titleLarge;        // TextStyle
context.theme.tokens.brand.accent;          // Color
context.theme.styles.neonChip;              // ThemeStates のための AppStyleNeonChip
context.theme.motion.fast;                  // Duration
context.theme.motion.curves.out;            // Curve
context.theme.animations.borderSpin;        // AnimationSpec
context.theme.background;                   // ThemeBackgroundData?
AppThemes.ocean;                            // ThemeSelection.select のための 'ocean'

キーを追加したら dart run build_runner build を実行してください。ゲッターは呼ばれたときに表示されているテーマを読むため、テーマを切り替えると新しい値を返し、ウィジェットは再構築されます。生成されるのは宣言したキーだけです。シードから計算されるロールは SpringTheme.of(context).colorScheme に残ります (MaterialApp では Theme.of(context).colorScheme にもあります)。使うには spring_gen/main.spring.dart をインポートしてください。

名前は Dart の名前になります。- と _ は新しい単語を始め (surface-container-low は surfaceContainerLow)、先頭の数字の前には $ が付き (2xl は $2xl)、Dart のキーワードの後ろには $ が付きます (default は default$)。同じ Dart の名前になる二つのキーはビルドを失敗させます。

このリファレンスのページ

ページ 扱う内容
プロパティ spring.flutter.theme とテーマのすべてのプロパティ: active、extends、brightness、どのデザインのスターターがどれを読むか、そして URL からダウンロードするテーマ
色 Material 3 の 46 の色のロール、デザインのスターターがあるときとないときのパレット、名前付きの色、16 進数の形式、alpha と mix
タイポグラフィ 15 のテキストのロールと code、すべてのスタイルのキー、アセットからのフォント
形状、余白、エレベーション 角のスケール、余白の名前、エレベーションのレベル
トークンと参照 独自の値、値の型の決まり方、$ の参照と $$
スタイルと状態 独自のウィジェットのための状態ごとの見た目、状態の優先順位、ThemeStates、コードの色
モーションとアニメーション 長さ、カーブ、ページのトランジション、animations.*、視差効果を減らす設定
背景 すべての画面の背後の色、画像、オーバーレイ、ゆっくりしたアニメーション
ローダーとスプラッシュ スピナー、ドット、バー、スケルトン、独自のローダー、そしてアプリの起動中に表示されるスプラッシュ
画像 キャッシュ、更新、チェックサム、フォールバックを持つ、アセットやネットワークからの画像

デザインのページはそのスターターとともにあります。Material のプロパティからのテーマ、パレット、密度とインク、コンポーネントのテーマ、そして Cupertino のテーマのプロパティです。

関連項目