アセットとフォント

Spring アプリが src/main/resources とその静的コンテンツを持つように、Flutter アプリにはファイルの置き場所が二つあります。どちらも Spring の Resource として読まれるため、ファイルを読む Bean はそれがどこから来るかを気にしません。アセットの中のフォントファイルは、ファイルが示すファミリーに自動的に読み込まれます。

lib/resources/ Flutter のアセット (pubspec.yaml の flutter: assets:)
用途 設定、メッセージ、小さなテキストやテンプレート 画像、動画、音声、大きなデータ、フォント
方法 デフォルトでは生成コードに埋め込まれる (ファイルあたり 1 MB まで)。spring.resources.embed.exclude で外したファイルはアセットとして読まれる アプリのアセットバンドルの中にあり、読むときに読み込まれる
場所 resources:mail/welcome.txt asset:assets/intro.mp4
読み込み 同期または非同期 非同期

使う理由

rootBundle を通じてアセットを読むと、サービスが Flutter に結び付き、テストしにくくなります。@Value で注入される Resource としてなら、同じ Bean がアプリではアセットを、テストではフェイクを読みます。そして、綴りを誤ったアセットのパスは、ユーザーの前のアプリではなくビルドを失敗させます。

例

// About 画面のロゴとテキスト。
@Component()
class AboutContent {
  AboutContent(
    @Value('asset:assets/images/logo.png') this.logo,
    @Value('asset:assets/texts/about.md') this.text,
  );

  final Resource logo;
  final Resource text;

  Future<String> read() => text.readAsString();

  // Flutter の画像、動画、音声の API はアセットのキーを受け取る。
  ImageProvider get logoImage => AssetImage((logo as AssetResource).key);
}

asset: の場所

resources: と asset: は同じように動く

lib/resources/ のファイルと Flutter のアセットは同じ機能を持つので、Markdown のページはどちらにも置けます。

resources: asset:
読み込み readAsString、readAsBytes (非同期) 同じ
exists() 埋め込みファイル、またはアセットマニフェスト アセットマニフェスト
パターン resources:content/**/*.md asset:docs/**/*.md
Markdown ページ間の相対リンク 使える 使える
検索エンジン向けのページ 作られる 作られる
検索 spring.search.markdown[n].location 同じ。場所は asset:

AssetResource は ContextResource です。pathWithinContext は、見つかったルートの中でのパスです。SpringApplicationWidget は、アプリのアセットマニフェストがあるとき、アセットをリソースルート (AssetResourceRoot) として登録するので、パターンでそれらを列挙できます。唯一の違いは、同期読み込み (readAsStringSync) が埋め込まれたファイルでのみ動くことです。非同期のものを使ってください。

ファイルは flutter: assets: の下のどこにでも置いて asset:path として読むことも、lib/resources/ に置いて resources: として読むこともできます。デフォルトでは、ビルドは lib/resources/ のすべてのファイルをバイナリーに埋め込みます。読み込みは即座で、アセットを宣言しなくてもすべてのプラットフォームで動きます。spring.resources.embed.exclude はファイルをバイナリーから外します。

# lib/resources/application.yml
spring:
  resources:
    embed:
      exclude: [content/**, images/**]
# pubspec.yaml
flutter:
  assets:
    - lib/resources/content/
    - lib/resources/content/docs/
    - lib/resources/images/

このドキュメントサイトでは、ページを外したことで main.dart.wasm が 11.6 MB から 3.7 MB (圧縮後は約 1 MB) に、JavaScript のフォールバックが 14.5 MB から 4.2 MB になりました。ページを開くと、834 個すべてを抱える代わりに、そのページの Markdown 2 ファイルをダウンロードします。埋め込みリソースを参照してください。

ビルド時にチェックされる

ジェネレーターは、すべての @Value('asset:...') をチェックします。存在しないファイルや、flutter: assets: の下で宣言されていないファイルは、追加すべき行とともにビルドを失敗させます。

@Value('asset:assets/sounds/tap.mp3') in ...#Sounds: assets/sounds/tap.mp3 is
not declared in pubspec.yaml, so the app would not contain it. Add it under
`flutter: assets:`:

flutter:
  assets:
    - assets/sounds/

ディレクトリのエントリー (- assets/sounds/) は、Flutter と同じく、そのディレクトリのファイルを取り込みますが、サブディレクトリのファイルは取り込みません。プレースホルダーを持つキー (asset:${sound.file}) と他のパッケージのアセット (asset:packages/...) は実行時にしかわからないため、チェックされません。

フォント

フォントファイルは flutter: assets: の下の任意のディレクトリに置き、他のどこにも列挙しません。アプリケーションの起動時 (スプラッシュの背後で)、スターターはアプリのアセットの中のすべての .ttf と .otf のファイルを、ファイル自身が示すファミリー (その name テーブル) に読み込みます。Inter-SemiBold.ttf は Inter のウェイトの一つになります。テーマはファミリーの名前だけを指定します。

# pubspec.yaml
flutter:
  assets:
    - assets/fonts/          # Inter-Regular.ttf、Inter-SemiBold.ttf、JetBrainsMono.ttf
# lib/resources/application.yml
spring:
  flutter:
    theme:
      typography:
        font-family: Inter
        code: { font-family: JetBrains Mono, size: 13 }
    fonts:
      exclude: [assets/pdf/**]   # 画面ではなく PDF のためのフォント
キー 型 デフォルト 意味
spring.flutter.fonts.auto-load bool true 最初のフレームの前に、すべての .ttf と .otf のアセットを読み込む。false: この方法ではフォントファイルは読み込まれない。flutter: fonts: のフォントは引き続き動く
spring.flutter.fonts.exclude glob のリスト (* はディレクトリ内、** はディレクトリをまたぐ) なし 読み込まないフォントのアセット。PDF の作成にだけ使うフォントなど
spring.flutter.fonts.families.<family>.files アセットのリスト なし 名前で宣言したファミリーのファイル (.ttf、.otf。ウェブでは .woff2)。そのファミリーに読み込まれる。auto-load はこれらに触れない
spring.flutter.fonts.families.<family>.languages 言語タグのリスト なし ファミリーが対象とする言語 (ja。ja-JP を含む)。アプリがその言語で起動するときは最初のフレームの前に、そうでなければ切り替わるときに読み込まれる。なし: 起動時

一つの言語 (日本語) のためのフォントは、languages とともに名前で宣言します。他の言語はそれをダウンロードすることがなく、ウェブエンジンは主フォントにない文字のために、ページごとに自前の代替フォントを取りに行くことがありません。typography.font-family-fallback に指定してください。タイポグラフィを見てください。

Web では、アプリのフォントにない文字は Flutter がダウンロードするフォントで描かれます。フォントのウォームアップ を参照してください。

Spring (Java) との対応

@Value("classpath:...") は ClassPathResource を注入します。ここでは resources: がクラスパスで、asset: が Flutter のアセットバンドルを加えます。

関連項目