テーマの画像

テーマは画像を指定できます。背景 の画像、個々の画面の画像、そして 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 にわたって)。

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

画像のトークン

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 がないこともエラーです。すべての画像に必要です。

関連項目