
# テーマの画像

テーマは画像を指定できます。[背景](background.md) の画像、個々の画面の画像、そして Dart で読む**画像のトークン**です。すべて同じマップを使います。画像は、アプリの**アセット**か、**ネットワーク**からのファイルのどちらかです。ネットワークの画像はバックグラウンドでダウンロードされ、再起動後も残るキャッシュに保持され、指定すれば SHA-256 のダイジェストと照合され、求めに応じて更新されます。

```yaml
spring:
  flutter:
    theme:
      background:
        image:
          source: https://cdn.example.com/neon/background.jpg
          refresh: 1d
          source-sha256: 9f2c1a5e7b2d4a6f8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d1f3a
          headers:
            Authorization: Bearer ${cdn.token}
          timeout: 10s
          fallback: assets/images/background.jpg
      tokens:
        brand:
          hero:
            source: https://cdn.example.com/hero.png
            refresh: 1d
```

## プロパティ

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `source` | テキスト | アセットのパス、`https://` の URL、`github:owner/repo/path@ref` のアドレス | 必須 | 画像の場所。スキームのないパス (と `C:` のような Windows のドライブ) はアセットで、アドレスはダウンロードされる。`http://` は、`spring.remote.allow-insecure` が `true` でない限り起動を止める ([安全でない接続](properties.md#安全でない接続) を参照)。それ以外のスキームは起動を止める |
| `refresh` | 期間 | `30m`、`12h`、`1.5d` | なし | ファイルをバックグラウンドで再び確認するまでにキャッシュが古くなってよい期間。なければ最初のダウンロードが永久に保持され、二度とリクエストはない |
| `source-sha256` | テキスト | 64 桁の 16 進数 | なし | ファイルはちょうどこのダイジェストを持たなければならない。それ以外のファイルは拒否される |
| `headers` | マップ | ヘッダー名から値へ | なし | `Authorization` などのリクエストヘッダー。`${...}` のプレースホルダーはアプリケーションの設定で解決される。ヘッダー名は綴りを保つ |
| `timeout` | 期間 | `10s`、`1m` | `10s` | ダウンロードにかけられる最長の時間 |
| `fallback` | テキスト | アセットのパス | なし | ネットワークの画像がまだない間に表示されるアセット |

ここでの期間は、テーマのどこでも同じです。単位 (`ms`、`s`、`m`、`h`、`d`) 付きの数値 (小数も可) で、`1.5s` や `0.5d` のように書きます。単なる数値はミリ秒です。ISO-8601 (`PT1H30M`) は受け付けられません。

[背景の画像](background.md#画像) では、これらのキーは `fit`、`alignment`、`opacity`、`blur` の隣に置きます。それ以外のキーは起動を止め、有効なものを列挙します。

参照 (`$colors.primary`) は `source`、`fallback`、`source-sha256`、`headers` では解決されないため、プレースホルダーから来たシークレットの中の `$` はそのまま残ります。[トークンと参照](tokens-and-references.md) を参照してください。

## 何がいつ表示されるか

起動がネットワークを待つことはありません。

| 状況 | アプリが表示するもの |
|---|---|
| アセット | アセットを即座に |
| キャッシュのあるネットワークの画像 | キャッシュされた画像を即座に |
| キャッシュがなく、`fallback` があるネットワークの画像 | フォールバック。ダウンロードはバックグラウンドで実行され、届いた画像がそれを置き換える |
| キャッシュもフォールバックもないネットワークの画像 | 何もなし。背景ではその `color` |

ダウンロードが終わると、新しい画像がフェードインします (背景では、その [`transition`](background.md#トランジション) にわたって)。

## ダウンロードとキャッシュ

- **場所。** キャッシュは、アプリの `support` のファイルの場所の `spring/images/<sha256 of source and digest>/` (`image` と `meta.json`) にあります。再起動後も残ります。ブラウザーでは IndexedDB にあります。フォルダーはソースとダイジェストに属するため、`source` や `source-sha256` を変えると再びダウンロードされます。どのテーマにもなくなった画像は起動時に取り除かれます。同じ画像を指定する二つのテーマは、一つのダウンロードを共有します。
- **最初の起動。** キャッシュがなければ、バックグラウンドで一度ダウンロードします。リクエストは `image/*` を求めます。
- **更新。** `refresh` があれば、それより古いキャッシュはバックグラウンドで、`If-None-Match` と `If-Modified-Since` 付きで再び読まれます。`304` は経過時間を更新するだけです。新しいファイルは届き次第差し替えられます。ダウンロードが失敗すると、更新の時間の後に、ただし 5 分より後にはならずに再び試されます。
- **ダイジェスト。** SHA-256 が異なるダウンロードしたファイルは拒否され、画面上の画像はそのまま残ります。一致しないキャッシュされたファイルは、警告とともに破棄されます。
- **制限。** ファイルは最大 20 MiB です。空の応答はエラーです。
- **失敗。** オフライン、タイムアウト、誤ったダイジェスト、大きすぎるファイルでは、表示中のものを保ち、ログに警告を書きます。
- **リダイレクト。** 別のホストへのリダイレクトは独自の `headers` を取り除くため、トークンが見知らぬ相手に送られることはありません。
- **Web では**、サーバーが CORS のヘッダー (`Access-Control-Allow-Origin`) であなたのオリジンを許可しなければなりません。そこでダウンロードが失敗すると、ログがそう伝えます。

## 画像のトークン

`source` と、上の表のキー**だけ**を持つマップのトークンは画像です。`source` の隣に別のキーを持つマップはトークンのグループです。画像は少なくとも `tokens.<group>.<key>` にあります。

```yaml
spring:
  flutter:
    theme:
      tokens:
        neon:
          hero: { source: https://cdn.example.com/hero.png, refresh: 1d }
          logo: { source: assets/images/logo.png }
```

```dart
final hero = context.theme.tokens.neon.hero;      // ThemeImage
ValueListenableBuilder(
  valueListenable: hero.listenable,
  builder: (context, provider, _) =>
      provider == null ? const SizedBox() : Image(image: provider),
);
```

`ThemeImage.provider` は今描く画像で (ネットワークの画像がキャッシュもフォールバックも持たない間は `null`)、`listenable` はダウンロードが届いたり更新されたりすると通知します。`theme.tokenImage('neon.hero')` は、ジェネレーターなしで同じ画像を読みます。

## エラー

誤った値はプロパティを示して起動を止めます。例えば `tokens.neon.hero.source-sha256` に「must be 64 hexadecimal digits」です。`http://` のソースは、`spring.remote.allow-insecure` が `true` でない限り、アドレスとプロパティを示して「the connection is not secure」で起動を止めます。`source` がないこともエラーです。すべての画像に必要です。

## 関連項目

- [背景](background.md)
- [トークンと参照](tokens-and-references.md)
- [プロパティ](properties.md#url-からのテーマ): URL からのテーマ全体
