
# アセットとフォント

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 がアプリではアセットを、テストではフェイクを読みます。そして、綴りを誤ったアセットのパスは、ユーザーの前のアプリではなくビルドを失敗させます。

## 例

```dart
// 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: の場所

- `asset:` は `rootBundle` の `AssetResource` を返します。`AssetBundle` Bean は、例えばテストで `rootBundle` を置き換えます。
- `asset:/assets/x.png` も、`context.getResource('asset:...')` も使えます。
- `exists()` は、`SpringApplicationWidget` が起動前に読み込むアプリのアセットのマニフェストでキーを探します。
- `asset:` は設定の場所としても使えます: `spring.config.import: asset:config/app.yml`。
- `@Resource` はこのためのものではありません。Spring でもここでも、名前で Bean を注入します。

## `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` はファイルをバイナリーから外します。

```yaml
# lib/resources/application.yml
spring:
  resources:
    embed:
      exclude: [content/**, images/**]
```

```yaml
# pubspec.yaml
flutter:
  assets:
    - lib/resources/content/
    - lib/resources/content/docs/
    - lib/resources/images/
```

- 同じ `resources:` の場所は引き続き動きます。アプリはファイルをアセットとして読みます。モバイルやデスクトップのアプリではパッケージの中にあり、Web ではファイルは読まれたときにだけダウンロードされます。
- Flutter のアセットのディレクトリは、そのディレクトリ自身のファイルだけを含み、サブディレクトリのファイルは含まないので、ディレクトリごとに列挙してください。足りないものがあると、ビルドが追加すべき行をそのまま表示します。
- 設定 (`application*.yml`、`application*.properties`、すべての `.properties`、`config/`) は常に埋め込まれます。
- 起動時に読む小さなファイルはバイナリーに入れます。必要なときに読む多数または大きなファイル (ドキュメントのページ、画像) はアセットに入れます。

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

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

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

```text
@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` のウェイトの一つになります。テーマはファミリーの名前だけを指定します。

```yaml
# pubspec.yaml
flutter:
  assets:
    - assets/fonts/          # Inter-Regular.ttf、Inter-SemiBold.ttf、JetBrainsMono.ttf
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      typography:
        font-family: Inter
        code: { font-family: JetBrains Mono, size: 13 }
    fonts:
      exclude: [assets/pdf/**]   # 画面ではなく PDF のためのフォント
```

- `flutter: fonts:` の下で宣言したファミリーは引き続き動きます。
- テーマが指定しながら、アセットにも `flutter: fonts:` にもないファミリーは、警告としてログに出ます。それでも `.SF UI Text` のような、プラットフォーム自身のフォントの一つである可能性があります。
- `.ttc` のコレクションのように、ファミリーを読めないファイルは警告とともにスキップされます。
- パッケージのフォントは、Flutter と同じく、そのパッケージとともに指定します: `packages/neon_ui/Space Grotesk`。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `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` に指定してください。[タイポグラフィ](themes/typography.md#言語のためのフォント)を見てください。

Web では、アプリのフォントにない文字は Flutter がダウンロードするフォントで描かれます。[フォントのウォームアップ](splash.md#アプリのテキストのためのフォント) を参照してください。

## Spring (Java) との対応

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

## 関連項目

- [spring_core_dart のリソース](../spring-core-dart/resources/index.md)
- [タイポグラフィ](themes/typography.md)
- [埋め込まれたリソース](../spring-core-dart-generator/resources.md)
