テーマの画像
テーマは画像を指定できます。背景 の画像、個々の画面の画像、そして Dart で読む画像のトークンです。すべて同じマップを使います。画像は、アプリのアセットか、ネットワークからのファイルのどちらかです。ネットワークの画像はバックグラウンドでダウンロードされ、再起動後も残るキャッシュに保持され、指定すれば SHA-256 のダイジェストと照合され、求めに応じて更新されます。
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 でない限り起動を止める (安全でない接続 を参照)。それ以外のスキームは起動を止める |
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) は受け付けられません。
背景の画像 では、これらのキーは fit、alignment、opacity、blur の隣に置きます。それ以外のキーは起動を止め、有効なものを列挙します。
参照 ($colors.primary) は source、fallback、source-sha256、headers では解決されないため、プレースホルダーから来たシークレットの中の $ はそのまま残ります。トークンと参照 を参照してください。
何がいつ表示されるか
起動がネットワークを待つことはありません。
| 状況 | アプリが表示するもの |
|---|---|
| アセット | アセットを即座に |
| キャッシュのあるネットワークの画像 | キャッシュされた画像を即座に |
キャッシュがなく、fallback があるネットワークの画像 |
フォールバック。ダウンロードはバックグラウンドで実行され、届いた画像がそれを置き換える |
| キャッシュもフォールバックもないネットワークの画像 | 何もなし。背景ではその color |
ダウンロードが終わると、新しい画像がフェードインします (背景では、その transition にわたって)。
ダウンロードとキャッシュ
- 場所。 キャッシュは、アプリの
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> にあります。
spring:
flutter:
theme:
tokens:
neon:
hero: { source: https://cdn.example.com/hero.png, refresh: 1d }
logo: { source: assets/images/logo.png }
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 がないこともエラーです。すべての画像に必要です。