
# テーマの背景

テーマは**背景**を持てます。ベースの色、画像、画像の上に描くもの (色やグラデーション)、そして画像のゆっくりした動きです。アプリはそれをすべての画面の背後に描きます。テーマの切り替えや新しい画像はクロスフェードします。一つの画面 (例えばログイン画面) は独自の背景を持てます。

```yaml
spring:
  flutter:
    theme:
      animations:
        background-drift:
          duration: 40s
          curve: ease-in-out
          repeat: reverse
      background:
        color: $colors.surface-container-lowest
        image:
          source: https://cdn.example.com/neon/background.jpg
          fallback: assets/images/background.jpg
          refresh: 1d
          fit: cover
          alignment: center
          opacity: 0.9
          blur: 4
        overlay:
          color: '#330A0C12'
          gradient:
            type: linear
            begin: top
            end: bottom
            colors: [transparent, '#CC0A0C12']
            stops: [0, 1]
        animation: background-drift
        effect: drift
        transition: 400ms ease-out
        screens:
          login:
            image:
              source: assets/images/login.jpg
              blur: 0
            overlay:
              color: '#66000000'
```

## プロパティ

テーマは、`background` の下に少なくとも一つのキーを持たない限り、背景を持ちません。それ以外のキーは起動を止め、有効なものを列挙します。

### 背景

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `background.color` | 色 | 任意の [色](colors.md#色の書き方) | テーマの `surface` | 他のすべての下にあるベースの層。画像の読み込み中にも表示される |
| `background.image` | マップ | 以下の画像のキー | なし | 色の上に描かれる画像 |
| `background.overlay` | マップ | `color`、`gradient` | なし | 画像の上に描かれるもの |
| `background.animation` | テキスト | `animations.<name>` の名前 | なし | 画像を動かすアニメーション |
| `background.effect` | 列挙 | `drift`、`zoom`、`pulse` | `animation` が設定されていれば `drift` | 画像の動き方 |
| `background.transition` | テキスト | `<duration> [<curve>]`、例えば `400ms ease-out` | `300ms ease-out` | 背景が変わるときのクロスフェード |
| `background.frame-rate` | 数値または `every-frame` | ゼロより大きい | `15` | 動く画像を一秒に何回再描画するか |
| `background.screens.<name>` | マップ | `screens` を除く上記のキー | なし | 一つの画面の背景。[画面ごとの背景](#画面ごとの背景) を参照 |

### 画像

`background.image` は、[画像](images.md) のすべてのキー (`source`、`refresh`、`source-sha256`、`headers`、`timeout`、`fallback`、`allow-http`) と、画像が画面をどう満たすかに関する四つのキーを受け取ります。

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `source` | テキスト | アセットのパス、`https` の URL、`allow-http` 付きの `http` の URL | 必須 | 画像。ダウンロード、キャッシュ、更新のキーについては [画像](images.md) を参照 |
| `fit` | 列挙 | `cover`、`contain`、`fill`、`fit-width`、`fit-height`、`none`、`scale-down` | `cover` | 画像が画面を満たす方法 |
| `alignment` | 配置 | 後述 | `center` | 画像のどの部分を見える範囲に残すか |
| `opacity` | 数値 | `0` から `1` | `1` | 画像の不透明度。残りの部分からは色が透けて見える |
| `blur` | 数値 | `0` 以上 | `0` | 画像をどれだけぼかすか (論理ピクセルでのその半径のガウスぼかし)。`0` は鮮明 |

`fit` の値:

| 値 | 働き |
|---|---|
| `cover` | 形を保ったまま画面を満たし、収まらない部分を切り取る |
| `contain` | 形を保ったまま画像全体を画面の中に表示し、空いたスペースを残す |
| `fill` | 形を変えて画像を画面に引き伸ばす |
| `fit-width` | 幅を画面に合わせる。高さは切り取られたり足りなかったりする |
| `fit-height` | 高さを画面に合わせる。幅は切り取られたり足りなかったりする |
| `none` | 画像をそれ自身のサイズで表示する |
| `scale-down` | `contain` と同じだが、画像をそれ自身のサイズより大きくすることはない |

`alignment` の値:

| 値 | 位置 |
|---|---|
| `center` | 中央 |
| `top` または `top-center` | 上端、中央 |
| `bottom` または `bottom-center` | 下端、中央 |
| `left` または `center-left` | 左端、中央 |
| `right` または `center-right` | 右端、中央 |
| `top-left`、`top-right`、`bottom-left`、`bottom-right` | 角 |
| `x, y` | `-1` (左または上) から `1` (右または下) の二つの数値。`0, 0` は中央、`0, -0.5` は上への中間 |

`fit` と `alignment` は、画像と画面の形が異なるときに意味を持ちます。`cover` では、`alignment: top` は画像の上部を残します。

### オーバーレイ

オーバーレイは画像の上に描かれるため、テキストが読みやすいままになります。平坦な `color`、`gradient`、またはその両方 (グラデーションが上) を持てます。

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `overlay.color` | 色 | アルファ付きの任意の色 | なし | 画面全体の上の平坦な色。ある程度透明な色を使う (`'#330A0C12'`、`{ color: $colors.scrim, alpha: 30% }`) |
| `overlay.gradient.type` | 列挙 | `linear`、`radial` | `linear` | グラデーションの種類 |
| `overlay.gradient.begin` | 配置 | `alignment` と同じ | `top` (線形)、`center` (放射状) | 線形グラデーションの始まり。放射状グラデーションでは中心 |
| `overlay.gradient.end` | 配置 | `alignment` と同じ | `bottom` | 線形グラデーションの終わり。放射状グラデーションは使わない: `type: radial` で `end` を指定すると起動が止まる (「radial uses begin as its center」) |
| `overlay.gradient.colors` | 色のリスト | 少なくとも二つ | 必須 | `begin` から `end` まで (または中心から外へ) の色 |
| `overlay.gradient.stops` | 数値のリスト | `0` から `1`、`colors` と同じ数 | 均等な間隔 | 各色がグラデーションに沿ってどこに位置するか |

放射状グラデーションの半径は、画面の短い辺の 0.8 です。`colors` と `stops` は YAML のリストか一つのカンマ区切りの値です。二つ未満の色のリストや、`colors` と長さの異なる `stops` は起動を止めます。

```yaml
spring:
  flutter:
    theme:
      background:
        color: '#0A0C12'
        overlay:
          gradient:
            type: radial
            begin: top-right
            colors: ['#33FF40A0', transparent]
```

### 描画の順序

奥から手前へ: `color`、画像 (ぼかしとその不透明度付き)、`overlay.color`、`overlay.gradient`。`animation` があるときに動くのは画像だけで、色とオーバーレイは静止したままです。

### アニメーションと効果

`animation` は、同じテーマの [`animations`](motion-and-animations.md#アニメーション) のエントリーを指定します。そうでない名前は起動を止め、アニメーションを列挙します (このテーマのアニメーションが存在しなければなりません)。それが速度、カーブ、繰り返しを与えます。`effect` は、0 から 1 に進む進行 `t` で画像が何をするかを示します。

| 効果 | 画像がすること |
|---|---|
| `drift` | どの端も見えないよう画像を 12% 大きくし、ゆっくり行き来させる: 横に幅の最大 4%、縦に高さの最大 2% |
| `zoom` | 画像が通常のサイズから 12% 大きくなる |
| `pulse` | 画像が少しフェードイン・アウトする: その不透明度の 70% から 100% の間 |

注記:

- `effect` には隣に `animation` が必要です。なければ起動が失敗し、そう伝えます。`animation` があって `effect` がなければ `drift` です。
- `image` がなければ、動かすものはありません。
- `repeat: loop` では動きは実行の終わりに跳んで戻ります。`repeat: reverse` では滑らかに往復し、背景に適しています。長い `duration` (30 秒以上) は落ち着いた動きを保ちます。
- デバイスが動きを減らすよう求めている場合、画像は静止します。

### フレームレート

動く背景は画面全体です。それが動くたびに、画面上のすべてが再描画されます。40 秒の漂いは画像を一秒に 1、2 ピクセル動かすので、毎フレーム (一秒に 60 や 120) 描くと、他に何も変わらないのに画面が再描画され続けます。Web ではこれがスクロールに必要な時間とバッテリーを奪います。

`frame-rate` は、画像が一秒に何回進むかです。デフォルトは 15 で、ゆっくりした漂いでは毎フレームと区別できません。その二つの段階の間、画面は背景のために描かれません。`every-frame` は、速いアニメーションのために、画面のすべてのフレームで動かします。

```yaml
background:
  animation: background-drift
  effect: drift
  frame-rate: 10          # または every-frame
```

### トランジション

`transition` は、背景が変わるときのクロスフェードです。テーマの切り替え、ネットワークからの新しい画像、変わった色です。長さと省略可能な [カーブ](motion-and-animations.md#カーブ) です: `400ms ease-out`、`1s`、`250ms linear`。デフォルトは `300ms ease-out` です。デバイスが動きを減らすよう求めている場合、フェードはありません。

新しいネットワークの画像はまず読み込まれ、古いものの上にフェードインするため、空白が一瞬表示されることはありません。

## 画面ごとの背景

`background.screens.<name>` は、その名前の画面の背景を変えます。`screens` を除く同じキーを使います。

```yaml
spring:
  flutter:
    theme:
      background:
        color: $colors.surface
        image: { source: assets/images/main.jpg, opacity: 0.8 }
        screens:
          login:
            image: { source: assets/images/login.jpg }
          settings:
            image: { blur: 12 }         # テーマと同じ画像を、ぼかして
            overlay: { color: '#80000000' }
```

画面はテーマの背景から始まり、書いたものを変えます。

- `color`、`animation`、`effect`、`transition` はテーマのものを置き換えます。
- `image` はテーマの画像の上にキーごとに重なります。画面は `blur` だけを書いてテーマの画像を保てます。テーマの画像がない画面は `source` を与えなければなりません。そうでなければ起動が止まります。
- `overlay` はテーマのオーバーレイ全体を置き換えます。マージはされません。

名前は、大文字小文字、`-`、`_` を区別せずに比較されます。

## 表示する

`SpringApp` (つまり `SpringApplicationWidget`) は、アクティブなテーマが背景を持つとき、アプリのナビゲーターの周りに背景を置くため、すべての画面がそれを表示します。それを見えるようにするため、背景を持つテーマでは **Material の Scaffold** (`spring_boot_starter_flutter_material` による `MaterialApp` で) と **Cupertino のページ** (`spring_boot_starter_flutter_cupertino` による `CupertinoApp` で) の背景も透明にします。`cupertino.scaffold-background-color` を設定する Cupertino のテーマは、その色を保ちます。

三つのウィジェットが画面に制御を与えます。

```dart
// テーマの背景 (アプリ自身が使うもの)。
ThemeBackground(child: const HomePage());

// テーマ自身のものの上の background.screens.login。テーマが列挙しない名前は
// デバッグでは FlutterError を投げる (テーマが持つ画面と最も近い名前を列挙する)。
// リリースでは子だけを表示する。
ThemeBackground.screen('login', child: const LoginForm());

// テーマのものを隠す、surface の色の簡素な背景。
ThemeBackground.none(child: const ReaderPage());
```

Dart では `context.theme.background` で値を読みます。これは `ThemeBackgroundData?` で、背景のないテーマでは `null` です。

```dart
final bg = context.theme.background;
bg?.color;          // Color?
bg?.screen('login'); // ログイン画面の解決済みの背景
```

背景のないテーマでは、Scaffold は再び不透明になります。テーマの切り替えで背景が追加されたり取り除かれたりしても、画面はその状態を保ちます。

## 関連項目

- [画像](images.md): すべての画像のキー、キャッシュ、更新
- [モーションとアニメーション](motion-and-animations.md): `animations.*` とカーブ
- [色](colors.md): オーバーレイのための `alpha`
- [プロパティ](properties.md)
