
# YAML による Flutter のテーマ

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

## 最初のテーマ

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

- **Material** は [spring_boot_starter_flutter_material](../../spring-boot-starter-flutter-material/index.md) で:
  各テーマが Material の `ThemeData` になります。一つの[シードカラー](../../spring-boot-starter-flutter-material/palette.md)からのパレット、
  `components.*` の下の[コンポーネントのテーマ](../../spring-boot-starter-flutter-material/components/index.md)、
  [密度とインク](../../spring-boot-starter-flutter-material/density-and-ink.md)、
  そして[コードでのテーマ](../../spring-boot-starter-flutter-material/themes-in-code.md)。
- **Cupertino** は [spring_boot_starter_flutter_cupertino](../../spring-boot-starter-flutter-cupertino/index.md) で:
  各テーマが Cupertino の `CupertinoThemeData` になります。`cupertino.*` の下の
  [Cupertino のテーマのプロパティ](../../spring-boot-starter-flutter-cupertino/theme-properties.md)と、
  同じシードからのパレット。

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

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

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

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

## テーマの選ばれ方

三つの部分があります。

1. `spring.flutter.theme` の**ルート**は、すべてのテーマで共有されます。
2. **`light` と `dark`** は常に存在します。それらで異なる部分だけを変えるには、`themes.light` や `themes.dark` を書きます。
3. 任意の数の**独自のテーマ**が `themes.<name>` の下にあります。それぞれは変更する部分だけを持ちます。

```yaml
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` を変えるテーマは、それを参照するすべてのものも変えます。[トークンと参照](tokens-and-references.md) を参照してください。

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

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

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

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

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

## Dart でテーマを読む

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

```dart
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)` から ([プロパティからのテーマ](../../spring-boot-starter-flutter-material/themes.md#テーマを読む) を参照)、Cupertino のものは `CupertinoTheme.of(context)` からです。

### 型付きのキー: `context.theme`

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

```dart
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 の名前になる二つのキーはビルドを失敗させます。

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

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

デザインのページはそのスターターとともにあります。Material の[プロパティからのテーマ](../../spring-boot-starter-flutter-material/themes.md)、[パレット](../../spring-boot-starter-flutter-material/palette.md)、[密度とインク](../../spring-boot-starter-flutter-material/density-and-ink.md)、[コンポーネントのテーマ](../../spring-boot-starter-flutter-material/components/index.md)、そして [Cupertino のテーマのプロパティ](../../spring-boot-starter-flutter-cupertino/theme-properties.md)です。

## 関連項目

- [デザインライブラリ](../design-libraries.md): デザインライブラリのないときと、Material や Cupertino があるときにテーマがすること。
- [spring_boot_starter_flutter_material](../../spring-boot-starter-flutter-material/index.md) と [spring_boot_starter_flutter_cupertino](../../spring-boot-starter-flutter-cupertino/index.md)。
- [設定のリファレンス](../configuration.md): 設定ファイル、プロファイル、インポート、プレースホルダー。どれもテーマの中で動きます。
- [Flutter のテスト](../testing.md): ウィジェットテストでのテーマの選択とゴールデンファイル。
