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

このスターターを持つアプリでは、`spring.flutter.theme.*` のすべてのテーマは `CupertinoThemeData` でもあり、`CupertinoApp` は選ばれたテーマのものを表示します。プロパティがなければ iOS 自身の見た目です。プロパティが設定したものがその上に重なります。まず Flutter のスターターのテーマのプロパティ (パレット、タイポグラフィ、背景)、次にこのスターターだけが読む `cupertino` のセクションです。

## 使う理由

- **すべてのウィジェットに一つのテーマ。** Cupertino のウィジェットは `CupertinoThemeData` を読み、アプリ独自のウィジェットは `SpringTheme` を読みます。どちらも同じプロパティから作られるので、`cupertino_ui` のボタンと独自のカードは同じ primary の色を表示します。
- **Dart にテーマを書かない。** iOS の見た目、ダークのテーマ、任意の数の独自のテーマは YAML です。デザイナーはコードをビルドせずにそれらを変更でき、テーマは実行時にサーバーから届くことさえあります。
- **起動時にチェックされる。** `cupertino` の下のつづりを誤ったキーや誤った色は、それを使う最初の画面ではなく、プロパティの名前とともに起動を止めます。

## 例

iOS のシステムカラーのライトのテーマと、色だけを変えるダークのテーマです。`cupertino` の値はパレットのロール (`$colors.primary`) を参照するので、ダークのテーマは独自の `cupertino` のセクションを必要としません。

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      active: system           # デバイスに従う: ライトまたはダーク
      colors:
        primary: '#007AFF'
        on-primary: '#FFFFFF'
        tertiary: '#FF9500'
        surface: '#F2F2F7'
      typography:
        body-large: { size: 17, height: 1.3 }
        title-large: { size: 22, weight: bold }
      cupertino:
        primary-color: $colors.primary
        primary-contrasting-color: $colors.on-primary
        scaffold-background-color: $colors.surface
        bar-background-color: { color: $colors.surface, alpha: 80% }
        selection-handle-color: $colors.tertiary
        text-theme:
          nav-title-text-style: { size: 17, weight: 600 }
      themes:
        dark:
          brightness: dark
          colors:
            primary: '#0A84FF'
            tertiary: '#FF9F0A'
            surface: '#000000'
```

```properties
# lib/resources/application.properties: 同じもの
spring.flutter.theme.active=system
spring.flutter.theme.colors.primary=#007AFF
spring.flutter.theme.colors.on-primary=#FFFFFF
spring.flutter.theme.colors.tertiary=#FF9500
spring.flutter.theme.colors.surface=#F2F2F7
spring.flutter.theme.typography.body-large.size=17
spring.flutter.theme.typography.body-large.height=1.3
spring.flutter.theme.typography.title-large.size=22
spring.flutter.theme.typography.title-large.weight=bold
spring.flutter.theme.cupertino.primary-color=$colors.primary
spring.flutter.theme.cupertino.primary-contrasting-color=$colors.on-primary
spring.flutter.theme.cupertino.scaffold-background-color=$colors.surface
spring.flutter.theme.cupertino.bar-background-color.color=$colors.surface
spring.flutter.theme.cupertino.bar-background-color.alpha=80%
spring.flutter.theme.cupertino.selection-handle-color=$colors.tertiary
spring.flutter.theme.cupertino.text-theme.nav-title-text-style.size=17
spring.flutter.theme.cupertino.text-theme.nav-title-text-style.weight=600
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.dark.colors.primary=#0A84FF
spring.flutter.theme.themes.dark.colors.tertiary=#FF9F0A
spring.flutter.theme.themes.dark.colors.surface=#000000
```

Dart は不要です。`SpringApplicationWidget(home: ...)` がこのテーマで `CupertinoApp` を組み立てます ([アプリのウィジェット](app-widget.md) を参照)。

## コアから来るもの

これらは Flutter のスターターのテーマのプロパティです。どの種類のアプリもこれらを読み、このスターターはそれらを `CupertinoThemeData` に入れます。

| テーマのプロパティ | `CupertinoThemeData` での現れ方 |
|---|---|
| `brightness` | `brightness`: ライトまたはダーク。それとともに、ライトとダークの値を持つすべての iOS の色 (`CupertinoColors.label`、デフォルトの背景) |
| `colors.primary` | `primaryColor`。`cupertino.primary-color` が設定されていないとき |
| `colors.surface` | `scaffoldBackgroundColor`。`cupertino.scaffold-background-color` が設定されていないとき |
| `background` | [背景](../spring-boot-starter-flutter/themes/background.md) を持つテーマではスキャフォールドが透明になり、背景がそれらを透けて見える |
| `typography.font-family`、`typography.font-family-fallback` | iOS の八つのテキストスタイルのフォント |
| `typography.<style>` | 対応する iOS のテキストスタイル (下記) のサイズ、太さ、行の高さ、文字間隔 |
| 参照による任意の値 | `$colors.primary`、`$brand.accent`: `cupertino` の値はテーマの任意の値を参照できる ([テーマのトークンと参照](../spring-boot-starter-flutter/themes/tokens-and-references.md) を参照) |

使われるのは `colors.*` の下で宣言したロールだけです。`seed-color` から作られたパレットは primary の色を与えますが (下記)、スキャフォールドの背景は与えません。それは `colors.surface` か `cupertino.scaffold-background-color` が別の指定をしない限り、iOS 自身のもののままです。

### タイポグラフィからのテキストスタイル

テーマがタイポグラフィ (フォントファミリー、フォールバック、または任意のテキストスタイル) を設定すると、iOS の八つのテキストスタイルはそれぞれ、そのフォントと、テーマの対応するスタイルに `typography.*` が書いたものを受け取ります。

| Cupertino のテキストスタイル | テーマから受け取るもの |
|---|---|
| `textStyle` | `body-large` |
| `actionTextStyle` | `label-large` |
| `tabLabelTextStyle` | `label-small` |
| `navTitleTextStyle` | `title-large` |
| `navLargeTitleTextStyle` | `display-small` |
| `navActionTextStyle` | `label-large` |
| `pickerTextStyle` | `body-large` |
| `dateTimePickerTextStyle` | `body-large` |

変わるのはタイポグラフィが書いたものだけです。`title-large: { weight: bold }` を設定するテーマは、ナビゲーションのタイトルを太字にし、iOS の 17 ポイントを保ちます。タイポグラフィも `cupertino.text-theme` もなければ、テキストテーマは手を加えられていない iOS のものです。`cupertino.text-theme` の下に書いたスタイルは、ここで作られるものを置き換えます ([テーマのプロパティ](theme-properties.md#テキストスタイル) を参照)。

## スターターが加えるもの

| 何を | どこに |
|---|---|
| `cupertino` のセクション: primary とコントラストの色、スキャフォールドとバーの背景、選択ハンドル、`apply-theme-to-all`、八つのテキストスタイル | [テーマのプロパティ](theme-properties.md) |
| `seed-color`、`scheme-variant`、`contrast` による Material 3 のパレット。Material なしで | [シードからのパレット](palette.md) |
| `motion.page-transition: cupertino`、そして Cupertino のアプリでは iOS のスライドとしての `platform` | [ページのトランジション](page-transitions.md) |
| テーマを表示する `CupertinoApp` | [アプリのウィジェット](app-widget.md) |
| `CupertinoThemeCustomizer` Bean と、置き換える `CupertinoThemeData` Bean | [コードでのテーマ](themes-in-code.md) |

## テーマの作られ方

| `CupertinoThemeData` の | 由来 |
|---|---|
| `brightness` | テーマの `brightness` |
| `primaryColor` | `cupertino.primary-color`、なければ `colors.primary`、なければ `seed-color` のパレットの primary の色、それもなければ iOS の青 |
| `primaryContrastingColor` | `cupertino.primary-contrasting-color`、なければ iOS のもの (白) |
| `scaffoldBackgroundColor` | `cupertino.scaffold-background-color`、なければ `colors.surface`。テーマが背景を持てば透明。それもなければ iOS のもの (`systemBackground`) |
| `barBackgroundColor` | `cupertino.bar-background-color`、なければ、[Material のスターター](../spring-boot-starter-flutter-material/index.md) も持つアプリでは `components.app-bar.background-color`、それもなければ iOS の半透明のバーの色 |
| `selectionHandleColor` | `cupertino.selection-handle-color`、なければ iOS のもの (青) |
| `applyThemeToAll` | `cupertino.apply-theme-to-all`、なければ `false` |
| `textTheme` | iOS の八つのスタイル。アクションのスタイルには primary の色が入り、その上にタイポグラフィ、その後に `cupertino.text-theme.*` |

テーマは読み込まれたテーマごとに一度作られ、その後 `CupertinoThemeCustomizer` Bean がそれを変更します ([コードでのテーマ](themes-in-code.md) を参照)。

## ライト、ダーク、system

テーマ `light` と `dark` は常に存在し、`themes.<name>` は独自のテーマを加えます。`active` は起動時に表示するテーマを選び、`system` (デフォルト) はデバイスに従って `system-light` または `system-dark` (デフォルトでは `light` と `dark`) を表示します。ダークモードに切り替わったデバイスはダークのテーマの Cupertino のテーマを即座に表示し、`ThemeSelection` Bean で選ばれたテーマも同様です。

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

`CupertinoThemeData` は常にテーマの明るさを持ち、それ自身で「デバイスに従う」ことはありません。そのため、ライトとダークの値を持つ iOS の色 (ラベルの色、デフォルトの背景、デフォルトのバーの色) は、ユーザーがライトのデバイスでダークのテーマを選んだときでも、表示されるテーマに従います。

`#RRGGBB` と書いた色は、すべてのテーマで一つの色です。だからこの例は色を `colors` の下に一度だけ書き、`cupertino` にそれを参照させています。ダークのテーマが `colors.primary` を変えれば、それを参照するすべての値が従います。テーマは独自の `cupertino` の値を設定することもできます (`themes.dark.cupertino.bar-background-color`)。別のテーマを `extends` するテーマは、その `cupertino` のセクションを継承し、自分が書いたものだけを変えます。[テーマの選ばれ方](../spring-boot-starter-flutter/themes/index.md#テーマの選ばれ方) を参照してください。

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

テーマはアプリの実行中に届くこともあります。サーバーからの YAML (`SpringThemes.loadYaml`)、コードからのプロパティ (`SpringThemes.load`)、または URL からダウンロードされたテーマです ([URL からのテーマ](../spring-boot-starter-flutter/themes/properties.md#url-からのテーマ) を参照)。それらの `cupertino` の値は、何かが変わる前に、ファイルのものと同じようにチェックされます。誤った値は例外を投げ、アプリは自分のテーマを保ちます。

```dart
@Component()
class SeasonThemes {
  SeasonThemes(this.themes);

  final SpringThemes themes;

  Future<void> download() async => themes.loadYaml(
    await http.read(Uri.parse('https://cdn.example.com/themes.yml')),
  );
}
```

```yaml
# サーバーの themes.yml
themes:
  winter:
    colors:
      primary: '#5AC8FA'
    cupertino:
      bar-background-color: '#E6F2F2F7'   # #AARRGGBB: 不透明度 90%
```

読み込み直されたテーマはそれぞれ改めて Cupertino のテーマとして作られ、カスタマイザーが改めてそれに適用され、`CupertinoApp` は新しい値を即座に表示します。`SpringThemes.unload()` はファイルのテーマに戻します。

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

`cupertino` の下の誤った値や未知のキーは、ルートでもすべての `themes.<name>` でも、プロパティの名前と有効なキーとともに起動を止めます。

```yaml
spring:
  flutter:
    theme:
      themes:
        ocean:
          cupertino:
            primary: blue        # キーは primary-color
```

```text
Invalid theme property spring.flutter.theme.themes.ocean.cupertino.primary: 'blue'; expected a property of cupertino: primary-color, text-theme, primary-contrasting-color, scaffold-background-color, bar-background-color, selection-handle-color, apply-theme-to-all (did you mean 'primary-color'?).
```

このスターターのないアプリでも、テーマは `cupertino` のセクションを持てます。テーマのライブラリは、Cupertino を使うアプリのためにそれを持つからです。その場合それは受け付けられますが、表示もチェックもされず、ログの INFO の 1 行が一度、このスターターの名前を挙げてそれを伝えます。[デザインライブラリ](../spring-boot-starter-flutter/design-libraries.md#検査されずに受け付けられるもの) を参照してください。

## アプリ独自のウィジェットのためのテーマ

`SpringTheme.of(context)` は、アプリのウィジェットのための同じテーマです。すべてのロールを持つパレット (`colorScheme.surfaceContainer`)、テキストスタイル、余白、トークンです。`SpringTheme.of(context).toCupertino()` は、表示されるテーマの、プロパティから作られたままの (カスタマイザーを適用しない) `CupertinoThemeData` です。`CupertinoTheme.of(context)` はアプリが表示しているものです。

```dart
final theme = SpringTheme.of(context);
return Container(
  color: theme.colorScheme.surfaceContainer,
  padding: EdgeInsets.all(theme.space('m')),
  child: Text(
    'NEON',
    style: CupertinoTheme.of(context).textTheme.navTitleTextStyle,
  ),
);
```

## 関連項目

- [テーマのプロパティ](theme-properties.md): `cupertino.*` のすべてのキー
- [シードからのパレット](palette.md)
- [コードでのテーマ](themes-in-code.md)
- [Flutter のスターターのテーマ](../spring-boot-starter-flutter/themes/index.md)
- [テーマの色](../spring-boot-starter-flutter/themes/colors.md)
- [テーマのタイポグラフィ](../spring-boot-starter-flutter/themes/typography.md)
