
# Cupertino のテーマのプロパティ

テーマの `cupertino` のセクションは、Cupertino のウィジェットが `CupertinoThemeData` から読む値のうち、テーマの他の部分では設定されないものを設定します。読むのは [spring_boot_starter_flutter_cupertino](index.md) です。これはテーマ自体のセクションで、`spring.flutter.theme.cupertino` (一つのテーマだけなら `spring.flutter.theme.themes.<name>.cupertino`) にあります。Material のものである `components` の下ではありません。

このセクションがなければ、`CupertinoThemeData` は iOS 自身の見た目で、iOS が青を使う場所にはテーマの primary の色が使われます ([プロパティからのテーマ](themes.md) を参照)。

## 使う理由

- **テーマごとの iOS の見た目を YAML で。** バー、ページの背景、iOS のテキストスタイルは、ライト、ダーク、ブランドのテーマで異なります。各テーマはそれを書くか、継承元のテーマから受け継ぎます。
- **パレットに従う値。** 値はロール (`$colors.primary`) やトークン (`$brand.accent`) を参照できます。色を変えるダークのテーマは、それを参照するすべての `cupertino` の値を変えます。
- **起動時にチェック。** キーのつづりの誤りや誤った値は、プロパティの名前と有効なキーを示して起動を止めます。

## 例

```yaml
# lib/resources/application.yml
spring:
  flutter:
    app:
      type: cupertino            # デザインのスターターがこれ一つなら省略可
    theme:
      seed-color: '#0057B8'
      typography:
        font-family: Inter
        title-large: { size: 17, weight: 600 }
      cupertino:
        primary-color: $colors.secondary
        primary-contrasting-color: white
        scaffold-background-color: '#F2F2F7'
        bar-background-color: { color: $colors.surface-container, alpha: 85% }
        selection-handle-color: $colors.primary
        apply-theme-to-all: true
        text-theme:
          nav-title-text-style: title-large
          nav-large-title-text-style: { size: 34, weight: 800, letter-spacing: 0.4 }
          action-text-style:
            color: $colors.primary
            weight: 500
```

```properties
# lib/resources/application.properties: 同じもの
spring.flutter.app.type=cupertino
spring.flutter.theme.seed-color=#0057B8
spring.flutter.theme.typography.font-family=Inter
spring.flutter.theme.typography.title-large.size=17
spring.flutter.theme.typography.title-large.weight=600
spring.flutter.theme.cupertino.primary-color=$colors.secondary
spring.flutter.theme.cupertino.primary-contrasting-color=white
spring.flutter.theme.cupertino.scaffold-background-color=#F2F2F7
spring.flutter.theme.cupertino.bar-background-color.color=$colors.surface-container
spring.flutter.theme.cupertino.bar-background-color.alpha=85%
spring.flutter.theme.cupertino.selection-handle-color=$colors.primary
spring.flutter.theme.cupertino.apply-theme-to-all=true
spring.flutter.theme.cupertino.text-theme.nav-title-text-style=title-large
spring.flutter.theme.cupertino.text-theme.nav-large-title-text-style.size=34
spring.flutter.theme.cupertino.text-theme.nav-large-title-text-style.weight=800
spring.flutter.theme.cupertino.text-theme.nav-large-title-text-style.letter-spacing=0.4
spring.flutter.theme.cupertino.text-theme.action-text-style.color=$colors.primary
spring.flutter.theme.cupertino.text-theme.action-text-style.weight=500
```

`$colors.secondary` と `$colors.surface-container` はここでは宣言されていません。宣言されていないロールへの参照は、テーマの `seed-color` から作られるパレットを読みます ([シードからのパレット](palette.md) を参照)。

## プロパティ

ここではキーをケバブケースで書いています。`primaryColor` と `primary_color` は同じキーです。色はすべて、テーマの [色の値](#色) です。

| プロパティ | 型 | デフォルト | 変えるもの |
|---|---|---|---|
| `cupertino.primary-color` | 色 | テーマが宣言していれば `colors.primary`、なければ `seed-color` があればそのパレットの primary、それもなければ iOS の青 (`systemBlue`) | Cupertino のウィジェットのアクセント: 塗りつぶしの `CupertinoButton` の塗りと通常のもののテキスト、`CupertinoTabBar` のアクティブなタブ、`CupertinoTextField` のカーソル、スライダー、セグメンテッドコントロール、ナビゲーションバーのアクション。アクションのテキストスタイルがこの色を持つ |
| `cupertino.primary-contrasting-color` | 色 | iOS のもの (白) | `primary-color` の上に表示される色: 塗りつぶしの `CupertinoButton` のラベルとアイコン、`CupertinoSegmentedControl` の選択されていないセグメント |
| `cupertino.scaffold-background-color` | 色 | テーマが宣言していれば `colors.surface`。テーマが [背景](../spring-boot-starter-flutter/themes/background.md) を持てば透明。それ以外は iOS のもの (`systemBackground`: 白、ダークのテーマでは黒) | `CupertinoPageScaffold` と `CupertinoTabScaffold` の背景 |
| `cupertino.bar-background-color` | 色 | アプリに `spring_boot_starter_flutter_material` もあれば `components.app-bar.background-color`、なければ iOS の半透明のバーの色 (`#F0F9F9F9`、ダークでは `#F01D1D1D`) | `CupertinoNavigationBar`、`CupertinoSliverNavigationBar`、`CupertinoTabBar` の背景 |
| `cupertino.selection-handle-color` | 色 | iOS のもの (`systemBlue`)。primary の色ではない | Cupertino のテキストフィールドでのテキスト選択のハンドル |
| `cupertino.apply-theme-to-all` | 真偽値 | `false` | デフォルトで iOS の固定の色を使うウィジェットが、代わりにテーマの色を使うかどうか。現在は `CupertinoSwitch` が該当する: オンのとき緑、`true` では `primary-color` |
| `cupertino.text-theme.primary-color` | 色 | `primary-color` | ここのキーでは設定しない唯一のアクションのスタイル、つまり小さな `CupertinoButton` (`sizeStyle: CupertinoButtonSize.small`) のテキストの色。下のアクションのスタイルはすでに `primary-color` を持っている。それらの色を変えるには `color` を指定する |
| `cupertino.text-theme.text-style` | テキストスタイル | iOS の本文のスタイル (17 ポイント)。`typography.body-large` を反映 | Cupertino のウィジェットのテキストのデフォルトのスタイル |
| `cupertino.text-theme.action-text-style` | テキストスタイル | iOS のもの (17 ポイント、`primary-color`)。`typography.label-large` を反映 | ボタンとアクションのテキスト |
| `cupertino.text-theme.tab-label-text-style` | テキストスタイル | iOS のもの (10 ポイント、medium)。`typography.label-small` を反映 | `CupertinoTabBar` のラベル |
| `cupertino.text-theme.nav-title-text-style` | テキストスタイル | iOS のもの (17 ポイント、semibold)。`typography.title-large` を反映 | ナビゲーションバーの中央のタイトル |
| `cupertino.text-theme.nav-large-title-text-style` | テキストスタイル | iOS のもの (34 ポイント、bold)。`typography.display-small` を反映 | `CupertinoSliverNavigationBar` の大きなタイトル |
| `cupertino.text-theme.nav-action-text-style` | テキストスタイル | iOS のもの (`primary-color`)。`typography.label-large` を反映 | ナビゲーションバーのボタン (`leading`、`trailing`、戻るボタン) |
| `cupertino.text-theme.picker-text-style` | テキストスタイル | iOS のもの (21 ポイント)。`typography.body-large` を反映 | `CupertinoPicker` と `CupertinoTimerPicker` の項目 |
| `cupertino.text-theme.date-time-picker-text-style` | テキストスタイル | iOS のもの (21 ポイント)。`typography.body-large` を反映 | `CupertinoDatePicker` の項目 |

「`typography.<style>` を反映」とは、テーマがタイポグラフィを設定していれば、iOS のスタイルがテーマのフォントと `typography.<style>` に書かれた値を受け取るという意味です ([プロパティからのテーマ](themes.md#タイポグラフィからのテキストスタイル) を参照)。`text-theme` の下に書いたスタイルは、それを置き換えます。

テーマの `brightness` が Cupertino のテーマの明るさになります。このセクションのキーではありません。

### 色

このセクションの色はすべて、テーマのどこでも色を書くのと同じ方法で書きます ([色の書き方](../spring-boot-starter-flutter/themes/colors.md#色の書き方) を参照)。

| 形式 | 例 | 注記 |
|---|---|---|
| `#RRGGBB`、`#RGB` | `'#F2F2F7'` | 不透明。YAML では引用符で囲む: `#` はコメントの始まり |
| `#AARRGGBB` | `'#B3FFF1E6'` | 8 桁: **最初が alpha (不透明度)**、続いて赤、緑、青。`B3` は 70% の不透明度。CSS の `#RRGGBBAA` ではない |
| `Colors` の名前 | `white`、`transparent`、`teal.shade700` | Flutter の色の名前 |
| 参照 | `$colors.primary`、`$colors.on-primary`、`$brand.accent` | パレットのロール (宣言したもの、またはシードから作られたもの)、またはテーマの任意の値 |
| 色のオブジェクト | `{ color: $colors.surface, alpha: 80% }` | 不透明度 (`alpha`) を持つ色、または別の色と混ぜた色 (`mix: { with: white, amount: 20% }`) |

ロールの名前だけでは色になりません。`bar-background-color: surface-container` は起動を止めます。`$colors.surface-container` と書いてください。

完全に不透明ではないバーの色は、バーを半透明にします。iOS はその下をスクロールするページをぼかし、`CupertinoPageScaffold` はコンテンツをバーの下から始めます。同じ種類のバーにする三つの方法です。

```yaml
spring:
  flutter:
    theme:
      cupertino:
        bar-background-color: '#CCF2F2F7'                           # #AARRGGBB: 不透明度 80%
      themes:
        ocean:
          cupertino:
            bar-background-color: { color: $colors.surface, alpha: 80% }   # パレットに従う
        sunset:
          background: { color: $colors.surface }
          cupertino:
            scaffold-background-color: transparent                  # 背景があればすでにデフォルト
            bar-background-color: '#B3FFF1E6'                       # 不透明度 70%、画像が透けて見える
```

### テキストスタイル

`text-theme` の各スタイルは、二つの方法のいずれかで書きます。

```yaml
spring:
  flutter:
    theme:
      cupertino:
        text-theme:
          nav-title-text-style: title-large          # テーマのスタイルの一つを名前で
          action-text-style:                         # またはマップ
            style: label-large                       # ベース (省略可能)
            color: $colors.primary
            font-family: Inter
            size: 17
            weight: semibold
            height: 1.3
            letter-spacing: -0.4
            italic: false
            decoration: none
```

| キー | 型 | 値 | 働き |
|---|---|---|---|
| 名前 | テキスト | `display-large` ... `label-small` (15 のスタイル)、または `code` | テーマのその名前のスタイル。`SpringTheme.of(context).textStyle(name)` が返すもの |
| `style` | テキスト | 同じ名前 | 他のキーが変更するベース。なければベースはそのスロットの iOS 自身のスタイル |
| `color` | 色 | [色](#色) | テキストの色 |
| `font-family` | テキスト | ファミリー | フォント |
| `size` | 数値 | 論理ピクセル | フォントのサイズ |
| `weight` | 数値または名前 | `100` ... `900`、`thin`、`light`、`normal`、`medium`、`semibold`、`bold`、`black` | フォントのウェイト |
| `height` | 数値 | サイズの倍数 | 行の高さ |
| `letter-spacing` | 数値 | 論理ピクセル | 文字の間隔 |
| `italic` | 真偽値 | `true`、`false` | イタリックか正体か |
| `decoration` | 列挙 | `none`、`underline`、`line-through`、`overline` | テキストの装飾 |

それぞれの書き方について知っておくこと:

- **名前**はテーマのスタイルを与えます。テーマのフォント、on-surface の色、そして `typography.<name>` が書く値だけです。Material 3 のタイプスケールのサイズは加えません。タイポグラフィが `size` を与えないスタイルは、Flutter のデフォルトのサイズになります。例の `title-large` のように、タイポグラフィでサイズを設定しているスタイルを名前で指定してください。
- **`style` のないマップ**は、タイポグラフィから作られたスタイルではなく、そのスロットの iOS のスタイルから始まります。`nav-title-text-style: { weight: 600 }` は、iOS のフォントでウェイト 600 の iOS のナビゲーションタイトルです。テーマのフォントを保つには `font-family` (または `style`) を加えてください。
- **`style` のあるマップ**は、その名前のテーマのスタイルから始まり、それを変更します。
- 書かなかったスタイルは、タイポグラフィから作られたもの、または iOS のものを保ちます。

## テーマごとの値

`cupertino` はルートですべてのテーマのために設定し、一つのテーマで変更できます。別のテーマを `extends` するテーマは、その `cupertino` の値から始まります。

```yaml
spring:
  flutter:
    theme:
      cupertino:
        primary-color: $colors.primary
        bar-background-color: { color: $colors.surface, alpha: 80% }
      themes:
        graphite:
          extends: dark
          colors:
            primary: '#FF9F0A'
          cupertino:
            scaffold-background-color: transparent
            text-theme:
              nav-large-title-text-style: { size: 34, weight: 800, letter-spacing: 0.4 }
```

`graphite` はルートの `primary-color` (`colors.primary` を参照しているので、ここではオレンジ) とバーの色を保ち、独自のスキャフォールドと大きなタイトルを加えます。

## スターターなしで

`spring_boot_starter_flutter_cupertino` のないアプリでも `cupertino` のセクションは受け入れられるので、テーマのライブラリは Cupertino のアプリのための値を持てます。表示されず、チェックされず、ログで一度だけ名前を挙げられます。キー `cupertino` 自体はそれでもチェックされます: `cupertio` は起動を止めます。[デザインのプロパティ](../spring-boot-starter-flutter/themes/properties.md#デザインのプロパティ) を参照してください。

## Material との違い

- **コンポーネント。** `components.*` は、`spring_boot_starter_flutter_material` が読む Material の `ThemeData` を設定します。Cupertino のウィジェットが読むのは `cupertino.*` と、Material のスターターもアプリにあればデフォルトのバーの色として使われる `components.app-bar.background-color` ([アプリバー](../spring-boot-starter-flutter-material/components/app-bar.md) を参照) だけです。
- **状態。** Material のコンポーネントのプロパティは状態 (`pressed`、`disabled`) ごとに値を持てます。Cupertino のテーマには状態がなく、`cupertino` の値はどれも一つの値です。
- **ページのトランジション。** このセクションではなく、どの種類のアプリとも同じく `motion.page-transition` にあります。[ページのトランジション](page-transitions.md) を参照してください。

## 関連項目

- [プロパティからのテーマ](themes.md): `CupertinoThemeData` の作られ方
- [シードからのパレット](palette.md)
- [コードでのテーマ](themes-in-code.md): どのプロパティにもないもの
- [色](../spring-boot-starter-flutter/themes/colors.md)
- [タイポグラフィ](../spring-boot-starter-flutter/themes/typography.md): Cupertino がテキストスタイルを受け取る元
- [トークンと参照](../spring-boot-starter-flutter/themes/tokens-and-references.md)
- [背景](../spring-boot-starter-flutter/themes/background.md)
- [Flutter のスターターのテーマのプロパティ](../spring-boot-starter-flutter/themes/properties.md)
