
# Web

ブラウザーでの Flutter アプリは、HTML ページの中のキャンバスに描画します。スターターとそのジェネレーターが、そのページとその周りのものを扱います。タイトル、説明、色を `web/index.html` に書き込み、Flutter のダウンロード中に表示されるページのローダー、アプリ内ブラウザーのための修正、`flutter run` の開発サーバー、そして求めに応じて検索エンジンのためのアドレスごとの本物の HTML ページを書き出します。そのすべてがプロパティから来て、ビルド時に `spring_core_dart_generator` が読みます。このページは Web のすべての機能を、それぞれのページへのリンクとともに並べます。

## 使う理由

素の Flutter の Web ビルドには、ダウンロード中の空白のページ、開発中のランダムなポート、検索エンジンやリンクのプレビューのためのテキストがないこと、アプリ内ブラウザーでスワイプすると閉じてしまうページ、そして必要な 9 倍のピクセルを描くスマートフォンがあります。それぞれの修正は忘れやすい数行の HTML や YAML です。ここではそれらはプロパティで、`application-web.yml` で他の設定とともに保持されます。

## 例

```yaml
# lib/resources/application-web.yml: ブラウザーだけが読む
spring:
  flutter:
    web:
      page:
        swipe-to-close: false     # アプリ内ブラウザー: スワイプはスクロールになる
        max-pixel-ratio: 2        # スマートフォンの 3 倍の画面を 2 倍で描く
        translate: false          # 機能しない翻訳の提案を出さない
      dev-server:
        port: 5050
        proxy:
          - prefix: /api/
            target: http://localhost:8080
      seo:
        enabled: true
        site-url: https://books.example.com
        from-routes: true
```

`dart run build_runner build` を実行し、次に `flutter run -d chrome` または `flutter build web` を実行します。

## 一覧

| 機能 | 得られるもの | 詳細 |
|---|---|---|
| アプリを囲むページ | タイトル、説明、色、スワイプで閉じる、ピクセル比、翻訳 | [下記](#アプリを囲むページ) |
| ブラウザーのバーの色 | テーマからの `theme-color`。ライトとダーク | [下記](#ブラウザーのバーの色) |
| ページのローダー | Flutter のダウンロード中に、テーマのスプラッシュを HTML で表示 | [ページローダー](../spring-core-dart-generator/flutter/page-loader.md) |
| `flutter run` の開発サーバー | 固定のポート、プロキシ、ヘッダー、Content Security Policy | [下記](#flutter-run-の開発サーバー) |
| アドレス | `#` のないパス、`#見出し` へのリンク | [Web とディープリンク](../spring-boot-starter-flutter-navigation/web-and-deep-links.md) |
| ディープリンク | `web/` の下の `.well-known` のファイル | [ディープリンク](../spring-core-dart-generator/flutter/deep-links.md) |
| SEO | アドレスごとの本物の HTML ページ、サイトマップ、リンクのプレビュー | [SEO](seo.md) |
| フォント | 言語ごとのフォント。フォールバックのダウンロードなし | [下記](#フォント) |
| 必要なときのアセット | ページや画像は読まれるときだけダウンロードされる | [下記](#必要なときにダウンロードされるファイル) |
| WebAssembly | `flutter build web --wasm` | [下記](#webassembly) |
| Markdown のプレースホルダー | ページの中の `{{key}}` を設定から | [下記](#ページの中の値) |
| フレームメーター | 毎秒のフレーム数。リリースでも | [下記](#リリースでのフレームメーター) |
| タイムライン | 起動とすべての観測。リリースでも | [タイムライン](timeline.md) |
| ログイン | サーバーがログインさせるか、ブラウザーが自分で行う | [下記](#ブラウザーでのログイン) |
| ホスティング | 静的ホストと `spring_boot_starter_web` | [下記](#ホスティング) |
| ブラウザーキャッシュ | `spring.web.resources.cache.cachecontrol.*` から `web/_headers` を書き出す。ビルドのファイルは問い合わせ直し、アセットは保持する | [Web ビルドのブラウザーキャッシュ](cache-headers.md) |

## アプリを囲むページ

ジェネレーターは、`build_runner` の実行時にこれらを `web/index.html` に書き込みます。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.app.title` | テキスト | なし | `<title>`、そして `web/manifest.json` の `name` と `short_name` |
| `spring.flutter.app.description` | テキスト | なし | `<meta name="description">` とマニフェストの `description` |
| `spring.flutter.web.page.swipe-to-close` | bool | `true` | `false` は、アプリ内ブラウザー (メッセンジャーやソーシャルアプリのもの) で下にスワイプしてもページを開いたままにする。スワイプはアプリをスクロールする |
| `spring.flutter.web.page.max-pixel-ratio` | 1 以上の数値 | 画面自身のもの | Flutter が描画するポイントあたりの最大のピクセル数 |
| `spring.flutter.web.page.translate` | bool | `true` | `false` は `translate="no"` と `<meta name="google" content="notranslate">` を書き込み、ブラウザーと Google がページの翻訳を提案しないようにする |

**スワイプで閉じる。** メッセンジャーやソーシャルアプリで開いたリンクは、アプリ内ブラウザーに表示されます。そのブラウザーは、ページが先頭にあるときに下にスワイプするとページを閉じます。Flutter のページは常に先頭にある (キャンバスの中でスクロールする) ため、下へのスワイプはすべてページを閉じてしまいます。`false` にすると、タッチスクリーンでは、ページを画面千個分の高さにし、Flutter のビューを固定したまま末尾までスクロールしておきます。ページは決して先頭にならないため、下へのスワイプは Flutter のものになります。

**ピクセル比。** スマートフォンの画面はポイントあたり 3 ピクセルなので、すべてのフレームがページの 9 倍のピクセルになり、そのグラフィックチップは全画面のスクロールでフレームを落とします。`2` は 2.25 分の 1 のピクセルで描き、テキストは鮮明なままです。`web/index.html` のスクリプトがエンジンの起動前にそれを設定します。値以下の画面はそのままです。

**翻訳。** Flutter はキャンバスにテキストを描くため、翻訳ツールはテキストを見つけられません。`false` は機能しない提案を取り除きます。SEO のページも同じ属性を得ます。

すべてのブロックとそのマーカー: [ページのヘッドとマニフェスト](../spring-core-dart-generator/flutter/page-loader.md#ページのヘッドとマニフェスト)。

## ブラウザーのバーの色

テーマがあれば、ビルドはその `primary` の色を `<meta name="theme-color">` として、`surface` をページの背景とマニフェストの `background_color` として書き込みます。スマートフォンのブラウザーは、そのバーをその色で塗ります。`system` (ライトとダークのテーマ) では、`prefers-color-scheme: light` 用と `dark` 用の二つの `theme-color` タグと、ダークの背景も書き込みます。バーは訪問者が見ているテーマに合います。[テーマの色](themes/colors.md) を参照してください。

## ページのローダー

ブラウザーが Flutter をダウンロードする間、ページは、ジェネレーターがアクティブなテーマの `splash` から書き出すもの (その背景、ロゴ、タイトル、ローダー) を HTML と CSS で表示します。Flutter のスプラッシュが描かれると、途切れなく引き継ぎます。書き出されるものについては [ページローダー](../spring-core-dart-generator/flutter/page-loader.md) を、テーマ側については [ローダーとスプラッシュ](themes/loaders.md) を、ブラウザーがアプリをコンパイルする間も動き続けるアニメーションについては [止まらない Web のページのローダー](themes/loaders.md#止まらない-web-のページのローダー) を参照してください。

## flutter run の開発サーバー

`flutter run -d chrome` は Web 版をランダムなポートで配信します。これは固定のオリジンを必要とするもの、つまりサーバーの CORS のリストや、SSO のログインがブラウザーを戻すページを壊します。Flutter 3.38 以降、`flutter run` は開発サーバーの設定を `web_dev_config.yaml` から読み、ジェネレーターがこれらのキーからそれを書き出します。ジェネレーターは、アプリがブラウザーで設定を読むのと同じように読みます。`application.*`、次に `application-web.*`、そしてそこで `spring.profiles.active` が指定するプロファイルのファイルです。`--dart-define` の値は数に入りません。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.web.dev-server.host` | 空でないテキスト | 任意のアドレス | 待ち受けるアドレス: `localhost`、または LAN 上の他のデバイスのための `0.0.0.0` |
| `spring.flutter.web.dev-server.port` | 0 から 65535 | 空いているポート | ポート。ブラウザーが開くことを拒否するポート (Chromium のブロックリスト) は警告になる |
| `spring.flutter.web.dev-server.base-href` | `/` で始まり `/` で終わるパス | `/` | アプリが配信されるパス (`/shop/`) |
| `spring.flutter.web.dev-server.https.cert-path` | ファイルパス | なし (HTTP) | TLS の証明書 (PEM)。`cert-key-path` とともに設定する |
| `spring.flutter.web.dev-server.https.cert-key-path` | ファイルパス | なし | その秘密鍵 (PEM) |
| `spring.flutter.web.dev-server.headers.<Name>` | テキスト | なし | すべての応答に追加されるヘッダー |
| `spring.flutter.web.dev-server.proxy[n].target` | 絶対 URL | なし | ルール `n` に一致するリクエストの転送先。すべてのルールで必須 |
| `spring.flutter.web.dev-server.proxy[n].prefix` | パス | なし | ルール `n` は、これで始まるパスに一致する (`/api/`) |
| `spring.flutter.web.dev-server.proxy[n].regex` | 正規表現 | なし | または、これに一致するパス。各ルールは `prefix` と `regex` のちょうど一方を設定する |
| `spring.flutter.web.dev-server.proxy[n].replace` | テキスト | パスをそのまま | 転送されるパス。一致した部分が置き換えられ、グループには `$1` を使う |
| `spring.flutter.web.dev-server.content-security-policy` | テキスト | なし。セキュリティスターターの spa モードでは用意されたポリシー | ページの Content Security Policy ヘッダー |
| `spring.flutter.web.dev-server.content-security-policy-report-only` | bool | `false` | ポリシーを `Content-Security-Policy-Report-Only` として送る: 違反は報告され、何もブロックされない |
| `spring.flutter.web.dev-server.content-security-policy-connect-src` | オリジンのリスト | なし | spa モードの用意されたポリシーの `connect-src` に追加するオリジン: アプリが呼ぶ API |

プロキシは、開発中に独自のサーバーと通信する最も簡単な方法です。`/api/` をそこに転送すると、ページと API は一つのオリジンを持ちます。CORS の設定は不要で、セッション Cookie はファーストパーティの Cookie になるため、セッションを使うログインがすべてのブラウザーで動きます。

Content Security Policy を使うと、開発も本番が送るポリシーの下で動きます。spa モードの用意されたポリシーは、Flutter のエンジンが必要とするものと、ページ自身のスクリプト (ページのローダー、スワイプで閉じる、ピクセル比) のハッシュをすでに許可しています。ホットリロードは厳しいポリシーに反するため、邪魔になるときは開発用のプロファイルで `content-security-policy-report-only` を有効にしてください。

不正な値はキーを示してビルドを失敗させ、綴りを誤ったキーは警告になります。`--web-port` や `--web-hostname` のフラグは引き続き優先されます。これらの設定は `flutter run` だけのものです。`flutter build web` は独自の Web サーバーのためのファイルを作り、そのサーバーには独自の設定があります。すべてのルール、生成されるファイル、用意されたポリシー: [Web 開発サーバー](../spring-core-dart-generator/flutter/web-dev-server.md)。

## ブラウザーのアドレスバー

[spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md) を使うと、アドレスバーはルートを `#` の後ではなくパス (`/catalog/books/1`) として表示します。`/docs/beans#bean-methods` へのリンクは、最初の読み込みでも、その見出しまでスクロールしたページを開きます。ホストはアプリのすべてのアドレスにページで応える必要があります。[ブラウザーのアドレス](../spring-boot-starter-flutter-navigation/web-and-deep-links.md#ブラウザーのアドレス) を参照してください。

## ディープリンク

同じアドレスでモバイルアプリを開くこともできます。Web アプリでは、ジェネレーターが `apple-app-site-association` と `assetlinks.json` を `web/.well-known/` に書き出すため、サイトはアプリとともにそれらを配信します。[Web とディープリンク](../spring-boot-starter-flutter-navigation/web-and-deep-links.md#ディープリンク) と [ディープリンク](../spring-core-dart-generator/flutter/deep-links.md) を参照してください。

## SEO

検索エンジンとリンクのプレビューはアプリを実行しないため、空のページを見ます。`spring.flutter.web.seo.enabled` を使うと、ビルドはアドレスごとに本物の HTML ページを書き出します。タイトル、説明、プレビューのタグ、テキストを持ち、`sitemap.xml`、`robots.txt`、`llms.txt`、各ページの Markdown のコピーも書き出します。手順は [SEO](seo.md) にあります。

## フォント

一つの言語のために宣言したフォント (`spring.flutter.fonts.families.<family>.languages`) は、アプリがその言語を表示するときだけダウンロードされます。テーマの `font-family-fallback` で指定すると、メインのフォントにない文字のために Web のエンジンがページごとに自分のフォールバックのフォントを取りに行くことも止まります。[アセットとフォント](assets-and-fonts.md#フォント) と [言語のためのフォント](themes/typography.md#言語のためのフォント) を参照してください。それ以外の文字は、[フォントのウォームアップ](splash.md#アプリのテキストのためのフォント) が必要なものをスプラッシュの背後でダウンロードします。

## 必要なときにダウンロードされるファイル

デフォルトでは `lib/resources/` のすべてのファイルがプログラムに埋め込まれるため、ブラウザーはそのすべてをダウンロードします。`spring.resources.embed.exclude` は glob に一致するもの (`content/**`、`images/**`) を外します。それらは Flutter のアセットになり、ブラウザーはアプリが読むときだけダウンロードします。このサイトでは、`main.dart.wasm` が 11.6 MB から 3.7 MB になりました。[ファイルをバイナリーから外す](../spring-core-dart-generator/resources.md#ファイルをバイナリーから外す) を参照してください。どの Flutter のアセットも `asset:path` として読めます。[アセットとフォント](assets-and-fonts.md) を参照してください。 `spring.resources.prefetch` は、アプリが表示されたあとにそれらを 1 つのファイルでまとめてダウンロードするので、以後どのページもすぐに開きます ([まとめてダウンロードする](../spring-core-dart-generator/resources.md#まとめてダウンロードする))。検索も同じように、言語ごとに 1 ファイルの自分のインデックスを読みます ([ビルドが書くインデックス](../spring-search-dart/searching.md#ビルドが書くインデックス))。

## WebAssembly

アプリは `flutter build web --wasm` でビルドしてください。Dart のコードは WebAssembly として実行され、JavaScript ビルドより高速です。対応していないブラウザーには、自動的に JavaScript ビルドが渡されます。アプリがブラウザーで実行できるパッケージはすべて Wasm にコンパイルでき、CI がそれを確かめます。詳しくは [WebAssembly](../../docs/webassembly.md) を参照してください。

Flutter のローダーは、指定がなければ WebAssembly のビルドを Chrome と Edge でだけ実行します。`spring.flutter.web.page.wasm-allow-list` を使うと、Firefox と Safari でも実行されます。

```yaml
# lib/resources/application-web.yml
spring:
  flutter:
    web:
      page:
        wasm-allow-list:
          gecko: true     # Firefox 147 以降
          webkit: true    # Safari 26.2 以降
```

- **設定しない場合:** 何も書き込まれず、Flutter 自身の選択 (Chrome と Edge だけ) になります。
- **古いブラウザー**や、アプリに必要な WebAssembly の機能がないブラウザーには、これまでどおり JavaScript のビルドが渡されます。Flutter のローダーが先にそれを確かめます。
- **独自の `flutter_bootstrap.js`** が `wasmAllowList` を渡している場合、そこで指定したブラウザーについてはその値が使われます。
- **誤った名前や値** (`opera`、`yes`) はビルドを失敗させます。

## ページの中の値

`spring.flutter.markdown.placeholders: true` を使うと、Markdown のページの `{{key}}` は設定の値を表示します。SEO のページ、その Markdown のコピー、`llms.txt` も同じ値を受け取ります。[設定の値](markdown.md#設定の値) を参照してください。

## リリースでのフレームメーター

フレームメーターは、アプリが実際に描画する毎秒のフレーム数を表示します。リリースビルドにもそれだけで含められる (`spring.flutter.debug.frame-meter.enabled`) ため、本物のスマートフォンで本物のサイトを計測できます。⌘⇧X、または 5 回のタップと長押しで開きます。[フレームメーター](frame-meter.md#リリースで) を参照してください。[タイムライン](timeline.md) (⌘⇧L) も同じようにリリースに含められ、起動の時間がどこに使われているかを示します。どちらも[デバッグオーバーレイのドック](overlays.md)を通じて同じ隅を共有します。

## ブラウザーでのログイン

[spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md) は、ブラウザーで `spring.flutter.security.web.*` を読みます。サーバーがユーザーをログインさせる ([サーバーモード](../spring-boot-starter-flutter-security/web-server-mode.md)) か、ブラウザーが自分で行います ([spa モード](../spring-boot-starter-flutter-security/web-spa-mode.md)。上記の用意された Content Security Policy も設定します)。

## ホスティング

`flutter build web` は `build/web/` を書き出します。どの静的ホストでも配信できる、ただのファイルです。SEO のページがある場合は、ホストに合わせて `spring.flutter.web.seo.page-files` を選んでください。Cloudflare Pages、GitHub Pages、Netlify には `html` です。これらは `<path>.html` をリダイレクトなしで `<path>` で配信します。[ページの配信](seo.md#ページの配信) を参照してください。独自の Dart のサーバーからビルドを配信するには、[静的リソース](../spring-boot-starter-web/static-resources.md) (`spa-fallback`、`directory-index`) を参照してください。

Cloudflare Pages では、ブラウザーがファイルを保持する期間は `web/_headers` で決まります。`spring.web.resources.cache.cachecontrol.*` を設定すると、ビルドのたびにそこへ規則のブロックが書き込まれます。ページ、`main.dart.js` などハッシュのないファイルには `no-cache`、アプリのアセットには設定した `Cache-Control` が付きます。[Web ビルドのブラウザーキャッシュ](cache-headers.md) を参照してください。

## 関連項目

- [SEO](seo.md)
- [Web ビルドのブラウザーキャッシュ](cache-headers.md)
- [Flutter のためのジェネレーター](../spring-core-dart-generator/flutter/index.md)
- [スプラッシュと起動](splash.md)
- [Flutter アプリでの設定](configuration.md)
- [すべてのプロパティ](properties.md)
