
# プロパティからのテーマ

このスターターを持つアプリでは、`spring.flutter.theme.*` のすべてのテーマが Material の `ThemeData` でもあります。テーマは一度だけ、すべてのアプリが共有するプロパティ (色、タイポグラフィ、形状、モーション、背景: [テーマ](../spring-boot-starter-flutter/themes/index.md) を参照) と、Material だけが持ついくつかのプロパティで書きます。スターターは各テーマの `ThemeData` を作り、`MaterialApp`、`Theme.of(context)`、すべての Material のウィジェットがそれを使います。Flutter 自身の Material 3 のテーマと異なるのは、プロパティが設定したものだけです。

## 使う理由

Material のアプリは、ふつう `ThemeData` を Dart で組み立てます。`ColorScheme`、`TextTheme`、十数個のコンポーネントのテーマを、ライトとダークで一度ずつです。ここでは、同じテーマが設定です。デザイナーが `application.yml` を変え、プロファイルがプラットフォームごとにそれを変え、実行時にダウンロードされたテーマがリリースなしにそれを変えます。そして同じファイルが、Material のアプリ、Cupertino のアプリ、デザインライブラリのないアプリに使えます。

## 例

フレームワークの例の Theme Showcase の Material のアプリから:

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      active: system
      seed-color: '#3F51B5'
      scheme-variant: tonalSpot
      typography:
        font-family: Inter
        title-large: { weight: 600 }
      shape:
        medium: 16
      components:
        app-bar:
          center-title: true
          background-color: $colors.primary-container
        card:
          elevation: 2
      themes:
        dark:
          brightness: dark
        ocean:
          extends: light
          seed-color: teal
          scheme-variant: vibrant
          shape: { medium: 20, large: 28 }
          colors:
            secondary: '#0277BD'
          components:
            card: { elevation: level0 }
        ocean-night:
          extends: ocean
          brightness: dark
```

```properties
spring.flutter.theme.active=system
spring.flutter.theme.seed-color=#3F51B5
spring.flutter.theme.scheme-variant=tonalSpot
spring.flutter.theme.typography.font-family=Inter
spring.flutter.theme.typography.title-large.weight=600
spring.flutter.theme.shape.medium=16
spring.flutter.theme.components.app-bar.center-title=true
spring.flutter.theme.components.app-bar.background-color=$colors.primary-container
spring.flutter.theme.components.card.elevation=2
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.ocean.extends=light
spring.flutter.theme.themes.ocean.seed-color=teal
spring.flutter.theme.themes.ocean.scheme-variant=vibrant
spring.flutter.theme.themes.ocean.colors.secondary=#0277BD
spring.flutter.theme.themes.ocean-night.extends=ocean
spring.flutter.theme.themes.ocean-night.brightness=dark
```

ウィジェットは、どの Material のアプリとも同じようにテーマを読みます。

```dart
final scheme = Theme.of(context).colorScheme;
final title = Theme.of(context).textTheme.titleLarge;
Card(color: scheme.surfaceContainerLow, child: Text('Ocean', style: title));
```

## ThemeData の作られ方

1. **Flutter のスターターがテーマを読みます。** `SpringThemeData` に、`light` または `dark` の層、ルート、`extends`、テーマ自身のキーを読み、すべての `$` の参照を解決します。これはどのアプリでも同じです。
2. **パレットが作られます。** このスターターのデザインが、`seed-color`、`scheme-variant`、`contrast` から Material の `ColorScheme.fromSeed` で、どれも設定されていなければ Flutter のベースラインから作り、その上に `colors.*` のロールを置きます ([シードからのパレット](palette.md) を参照)。
3. **`ThemeData` が作られます。** テーマから (`toMaterial()`)。その後、`components.*` の下の各コンポーネントがそれに適用されます。
4. **`ThemeCustomizer` Bean がそれを変更します。** `@Order` の順です。`theme` または `darkTheme` という名前の `ThemeData` Bean は、それより前に、作られた `light` または `dark` のテーマに取って代わります ([コードでのテーマ](themes-in-code.md) を参照)。
5. **`MaterialThemes` Bean が結果を保持します。** テーマごとに一度だけ作られ、`MaterialApp` がそれを表示します。

### Flutter のスターターから来るもの

これらの部分は Flutter のスターターのプロパティで、どのアプリでも同じです。このスターターは、それらを Material のテーマに置き場所のあるところに置きます。

| テーマのプロパティ | `ThemeData` では |
|---|---|
| 46 のパレットのロール: `colors.*`、またはシードから作られたもの | `colorScheme`: テーマのパレットのすべてのロールを持つ Material の `ColorScheme` |
| `typography.font-family`、`typography.font-family-fallback` | `fontFamily`、`fontFamilyFallback` |
| 15 のテキストスタイル (`display-large` ... `label-small`) | `textTheme`: テーマが設定したスタイルは Material のものを置き換え、それ以外は Material のまま |
| `shape.*` | 専用のフィールドはない: トークンに従うコンポーネント (カードは `medium`、ダイアログは `extra-large`、ボタンは `full`、...) は、テーマがそのトークンを変えるとそれを受け取り、コンポーネントの `shape: large` はそれを読む ([コンポーネント](components/index.md#形状とエレベーション) を参照) |
| `elevation.*` | コンポーネントの `elevation: level2` がそのレベルを読む |
| `motion.page-transition` | `pageTransitionsTheme`: すべてのプラットフォームで同じトランジション。`platform` (または何も設定しない) では、プラットフォームごとの Flutter 自身のもの |
| `background` | `scaffoldBackgroundColor` が透明になり、すべての `Scaffold` 越しに背景が見える |
| Material に置き場所のないもの: `spacing`、`tokens`、`styles`、`code` のスタイル、`animations`、`loaders` | `extensions` の中の `SpringThemeExtension` ([後述](#テーマを読む) を参照) |

### このスターターが追加するもの

| テーマのプロパティ | `ThemeData` では | ページ |
|---|---|---|
| `seed-color`、`scheme-variant`、`contrast` | それらから Material 3 が作るパレット | [シードからのパレット](palette.md) |
| `components.<name>.*` | 約 50 のコンポーネントのテーマ: `cardTheme`、`appBarTheme`、`filledButtonTheme`、`inputDecorationTheme`、... | [コンポーネントのテーマ](components/index.md) |
| `visual-density` | `visualDensity` | [密度とインク](density-and-ink.md) |
| `tap-target-size` | `materialTapTargetSize` | [密度とインク](density-and-ink.md) |
| `splash` (一語) | `splashFactory` | [密度とインク](density-and-ink.md) |
| `motion.page-transition: zoom` | `ZoomPageTransitionsBuilder`: Material のズームのトランジション | [モーション](../spring-boot-starter-flutter/themes/motion-and-animations.md#ページのトランジション) |

どれも名前付きのテーマの中にも書けます (`themes.<name>.components.card.*`)。`seed-color`、`scheme-variant`、`contrast` は [Cupertino のスターター](../spring-boot-starter-flutter-cupertino/palette.md) も同じ色で計算します。それ以外は Material だけのものです。

## ライト、ダーク、システム

`light` と `dark` は常に存在します。表示されるものは `spring.flutter.theme.active` が選びます。

| `active` | `MaterialApp` が受け取るもの |
|---|---|
| `system` (デフォルト) | `theme`: `system-light` のテーマ (デフォルトは `light`)、`darkTheme`: `system-dark` のテーマ (デフォルトは `dark`)、`themeMode: ThemeMode.system`。Material はデバイスに従ってそれらを切り替える |
| テーマの名前 | `theme`: そのテーマ、`themeMode: ThemeMode.light`。ダークのテーマは、パレットがダークなので、そのまま表示される |

`ThemeSelection` Bean は実行時に選択を変え、アプリは新しいテーマを即座に表示します。

```dart
class ThemeMenu extends SpringStatelessWidget<(ThemeSelection,)> {
  const ThemeMenu({super.key});

  @override
  Widget build(BuildContext context) {
    final (selection,) = beans;
    return PopupMenuButton<String>(
      onSelected: selection.select,
      itemBuilder: (_) => [
        for (final name in ['system', 'light', 'dark', 'ocean'])
          PopupMenuItem(value: name, child: Text(name)),
      ],
    );
  }
}
```

`system-light`、`system-dark`、`remember`、`extends` については [テーマ](../spring-boot-starter-flutter/themes/index.md#テーマの選ばれ方) を参照してください。

## 実行時に読み込まれるテーマ

テーマは起動の後に届くこともあります。プロパティの中の URL から (`themes.<name>.source`。[URL からのテーマ](../spring-boot-starter-flutter/themes/properties.md#url-からのテーマ) を参照)、またはコードから `SpringThemes` Bean で読み込みます。

```dart
@Service()
class WinterThemes {
  WinterThemes(this.themes, this.selection);

  final SpringThemes themes;
  final ThemeSelection selection;

  Future<void> show() async {
    themes.loadYaml(
      await http.read(Uri.parse('https://themes.example.com/winter.yml')),
    );
    selection.select('winter');
  }
}
```

読み込まれたテーマは、ファイルのテーマと同じように、Material の部分も含めてチェックされます。未知のコンポーネントや誤った値は `ThemePropertyException` を投げ、何も変えません。その後、`MaterialThemes` Bean が、最初に表示されるときに、その `ThemeData` を (カスタマイザーとともに) 作ります。

## このスターターが読むプロパティ

| キー | 値 | デフォルト | 働き |
|---|---|---|---|
| `spring.flutter.theme.seed-color` | 色 | なし | パレットを作る元の色 |
| `spring.flutter.theme.scheme-variant` | `tonalSpot`、`fidelity`、`content`、`vibrant`、`expressive`、`monochrome`、`neutral`、`rainbow`、`fruitSalad` | `tonalSpot` | シードからパレットをどう作るか |
| `spring.flutter.theme.contrast` | `-1` から `1` | `0` | パレットのコントラスト |
| `spring.flutter.theme.components.<name>.*` | [コンポーネントのリファレンス](components/index.md) を参照 | Flutter のもの | 一つの Material のコンポーネントのテーマ。Flutter のプロパティ名をケバブケースで |
| `spring.flutter.theme.visual-density` | `adaptive`、`standard`、`comfortable`、`compact` | プラットフォームごとの Flutter のもの | Material のコントロールをどれだけ密に並べるか |
| `spring.flutter.theme.tap-target-size` | `padded`、`shrink-wrap` | プラットフォームごとの Flutter のもの | タップが当たる最小の領域 |
| `spring.flutter.theme.splash` | `ripple`、`sparkle`、`none` | プラットフォームごとの Flutter のもの | タップのインク。`splash` の下のマップは別物で、すべてのアプリが読む起動時のスプラッシュ画面 |
| `spring.flutter.theme.motion.page-transition` | `zoom` | | Material のズームのトランジション。それ以外の値は Flutter のスターターのもの |

## 起動時にチェックされる

スターターは、ウィジェットが最初に必要とするときではなく、アプリケーションの起動時にすべてのテーマの自分の部分を読みます。未知のコンポーネントやプロパティ、誤った値、Flutter が拒む組み合わせは起動を失敗させ、プロパティと有効な値を示し、近いものがあれば "did you mean" を添えます (ここではリストを短くしています)。

```text
Invalid theme property spring.flutter.theme.components.crad (theme light): ''; expected a component: app-bar, badge, banner, ... (did you mean 'card'?).
```

実行時に読み込まれたテーマも、何かを置き換える前に、同じようにチェックされます。

## このスターターがない場合

このスターターのないアプリでも、テーマは `components`、`visual-density`、`tap-target-size`、一つの値の `splash` を持てます。テーマのライブラリは、Material を使うアプリのためにそれらを持つからです。その場合それらは受け付けられますが、表示もチェックもされず、それぞれについて一度、ログの INFO の 1 行がそれを伝えます。

```text
The theme property components is not shown and not checked: spring_boot_starter_flutter_material, which reads it, is not in the application.
```

キーはそれでもチェックされます。`componets` は起動を失敗させます。`SpringThemeData.unreadDesignProperties` は、それぞれを読むスターターとともに、それらを列挙します。`seed-color`、`scheme-variant`、`contrast`、`zoom` のトランジションは異なり、デザインのスターターがなければ、それを示して起動を失敗させます。両方のデザインのスターターを持つアプリでは、Material のプロパティはアプリの種類にかかわらず読まれ、チェックされます。[デザインライブラリ](../spring-boot-starter-flutter/design-libraries.md) を参照してください。

## テーマを読む

Material のウィジェットは `Theme.of(context)` を読みます。Material のテーマに置き場所のないものは、どのアプリでも `SpringTheme` にあります。

```dart
final theme = SpringTheme.of(context);
final gap = theme.space('m');
final code = theme.textStyle('code');
```

Material の `ThemeData` しか手元にないコード (関数に渡された `ThemeData`、独自の `Theme` の下のウィジェット) は、作られたすべての `ThemeData` が持つ拡張を通じてそれに届きます。

```dart
final spring = Theme.of(context).extension<SpringThemeExtension>()!.data;
final gap = spring.space('s');
```

表示されているもの以外のテーマは、Material の `ThemeData` として、アプリのものと同じようにカスタマイズされて、`MaterialThemes` Bean から得られます。

```dart
// ウィジェットの中では: 注入された Bean。
class OceanPreview extends SpringStatelessWidget<(MaterialThemes,)> {
  const OceanPreview({super.key});

  @override
  Widget build(BuildContext context) {
    final (themes,) = beans;
    return Theme(data: themes.theme('ocean'), child: const PreviewCard());
  }
}

// ウィジェットの外では: アプリケーションコンテキストから。
final ocean = MaterialThemes.of(applicationContext).theme('ocean');
```

`SpringThemeData.toMaterial()` は一つのテーマの `ThemeData` をカスタマイザーなしで返し、`materialColorScheme` はそのパレットを Material の `ColorScheme` として返します。

## Spring (Java) との対応

相当するものはありません。Spring にはアプリのテーマがありません。

## 関連項目

- [テーマ](../spring-boot-starter-flutter/themes/index.md): すべてのアプリが共有するプロパティ
- [シードからのパレット](palette.md)
- [密度とインク](density-and-ink.md)
- [コンポーネントのテーマ](components/index.md)
- [コードでのテーマ](themes-in-code.md)
- [デザインライブラリ](../spring-boot-starter-flutter/design-libraries.md)
