
# 形状、余白、エレベーション

すべてのテーマの下に、三つの小さなスケールがあります。**形状**は角の丸みの大きさです。**余白**は独自のウィジェットのための間隔の集合です。**エレベーション**はサーフェスがどれだけ浮いているかです。一か所で段階に名前を付け、コンポーネントとウィジェットはそれを名前で参照します。

```yaml
spring:
  flutter:
    theme:
      shape:
        medium: 16
        large: 24
        full: infinity
      elevation:
        level1: 2
      spacing:
        m: 16
        gutter: 20
      components:
        card:
          shape: large
          elevation: level1
```

## 形状: 角のスケール

`shape.<token>` は、角の半径を論理ピクセルで設定します。名前は Material 3 のもので、ケバブケースで書きます。

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `shape.none` | 数値 | 半径 | `0` | 四角い角 |
| `shape.extra-small` | 数値 | 半径 | `4` | ごく小さな丸み: テキストフィールド、ツールチップ、スナックバー |
| `shape.small` | 数値 | 半径 | `8` | チップ |
| `shape.medium` | 数値 | 半径 | `12` | カード |
| `shape.large` | 数値 | 半径 | `16` | フローティングアクションボタン |
| `shape.large-increased` | 数値 | 半径 | `20` | large と extra large の間の段階 |
| `shape.extra-large` | 数値 | 半径 | `28` | ダイアログとボトムシート |
| `shape.extra-large-increased` | 数値 | 半径 | `32` | extra large の一つ上の段階 |
| `shape.extra-extra-large` | 数値 | 半径 | `48` | 最も大きな丸み |
| `shape.full` | 数値 | 半径または `infinity` | 無限大 | スタジアム: 完全に丸い端。ボタンが使う |

それ以外のトークン名は起動を止め、この十個を列挙します。

### 形状のトークンが使われる場所

独自のウィジェットは、`theme.shape('medium')` や `$shape.medium` の参照でトークンを読みます。Material のアプリでは、いくつかのコンポーネントが、書かなくてもトークンに従います (カードは `medium`、ダイアログは `extra-large`、ボタンは `full`、...)。そのため、トークンを変えるとそれらも変わります。一覧は[コンポーネントのテーマ](../../spring-boot-starter-flutter-material/components/index.md#形状とエレベーション)にあります。

### コンポーネントが形状を参照する方法

コンポーネントの中では、`shape` はトークン名、半径、`stadium`、`circle`、またはマップを受け取ります。

```yaml
spring:
  flutter:
    theme:
      components:
        card:
          shape: large                      # トークン
        chip:
          shape: 6                          # 半径
        filled-button:
          shape: stadium
        dialog:
          shape:
            type: continuous                # rounded、continuous、beveled、stadium、circle
            radius: extra-large
            side: { color: $colors.outline, width: 1 }
```

角の種類: `rounded` (デフォルト)、`continuous` (iOS の滑らかなカーブ)、`beveled` (切り落とした角)、`stadium`、`circle`。`rounded` の種類で半径が `infinity` (`full` トークン) ならスタジアムになります。`radius` や `border-radius` のプロパティも、トークン名か数値を受け取ります。

テーマのどこでも、参照はトークンを読めます。書いていないものでもです: `$shape.extra-small` は、テーマが変えない限り `4` です。これにより、`styles` のエントリーの角がテーマに従います。

```yaml
spring:
  flutter:
    theme:
      styles:
        tag:
          radius: $shape.small
```

## エレベーションのレベル

`elevation.<level>` は、Material 3 の六つのレベルの一つの高さを設定します。

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `elevation.level0` | 数値 | 任意の数値 | `0` | サーフェスの上に平らに |
| `elevation.level1` | 数値 | 任意の数値 | `1` | カード、静止状態のボタン |
| `elevation.level2` | 数値 | 任意の数値 | `3` | 持ち上がった、またはスクロールされたアプリバー |
| `elevation.level3` | 数値 | 任意の数値 | `6` | メニューと静止状態のフローティングボタン |
| `elevation.level4` | 数値 | 任意の数値 | `8` | より高いメニュー、ホバーされたフローティングボタン |
| `elevation.level5` | 数値 | 任意の数値 | `12` | ドラッグされたサーフェス |

それ以外の名前は起動を止め、`level0` ... `level5` を列挙します。

コンポーネントのプロパティがエレベーションを受け取る場所では、レベルの名前か数値を書けます。

```yaml
spring:
  flutter:
    theme:
      elevation:
        level1: 2          # level1 を指定するすべてのコンポーネントが 2 を使うようになる
      components:
        card:
          elevation: level1
        app-bar:
          elevation: 0
          scrolled-under-elevation: level2
        filled-button:
          elevation: { default: level1, hovered: level2, pressed: level0 }
```

レベルを変えると、それを指定するコンポーネントだけが変わります。エレベーションを与えていないコンポーネントは Flutter の値を保ちます。

## 余白

`spacing.<name>` は、**独自のウィジェット**のための間隔の集合です。Material のコンポーネントはこれを読みません。どんな名前でも使え、値は論理ピクセルの数値です。

| 名前 | デフォルト | 用途 |
|---|---|---|
| `xs` | 4 | 最も小さな間隔 |
| `s` | 8 | 関連する項目の間の小さな間隔 |
| `m` | 16 | 通常のページの余白 |
| `l` | 24 | セクションの間の間隔 |
| `xl` | 32 | 大きな間隔 |
| それ以外の名前 | なし | `gutter: 20` のような独自のもの |

```yaml
spring:
  flutter:
    theme:
      spacing:
        m: 12             # デフォルトを変える
        gutter: 20        # 独自のものを追加する
      themes:
        compact:
          spacing: { s: 4, m: 8 }
```

### Dart で読む

```dart
final theme = SpringTheme.of(context);
EdgeInsets.all(theme.space('m'));        // 16、またはテーマが指定する値
theme.space('gutter');                   // 20
theme.shape('large');                    // 角の半径。デフォルトは 16
theme.elevation('level2');               // デフォルトは 3

EdgeInsets.all(context.theme.spacing.gutter);   // 型付き
```

`space`、`shape`、`elevation` は、任意の綴り (`extra-large`、`extraLarge`) の名前を受け付けます。未知の名前は `ArgumentError` を投げます。ジェネレーターがあれば、`context.theme.spacing` は宣言した各名前のゲッターを持ちます。書いていないデフォルトにはゲッターがないため、`context.theme.spacing.m` を使いたい場合は `s` と `m` を宣言してください。形状とエレベーションは生成されません。`theme.shape(...)` と `theme.elevation(...)` で読んでください。

## 関連項目

- [プロパティ](properties.md)
- [コンポーネントのテーマ](../../spring-boot-starter-flutter-material/components/index.md): Material のコンポーネントごとの `shape`、`elevation`、`padding`
- [トークンと参照](tokens-and-references.md): `$spacing.m` と `$shape.large`
- [スタイルと状態](styles-and-states.md): 独自のウィジェットのための数値と余白
