Web
ブラウザーでの Flutter アプリは、HTML ページの中のキャンバスに描画します。スターターとそのジェネレーターが、そのページとその周りのものを扱います。タイトル、説明、色を web/index.html に書き込み、Flutter のダウンロード中に表示されるページのローダー、アプリ内ブラウザーのための修正、flutter run の開発サーバー、そして求めに応じて検索エンジンのためのアドレスごとの本物の HTML ページを書き出します。そのすべてがプロパティから来て、ビルド時に spring_core_dart_generator が読みます。このページは Web のすべての機能を、それぞれのページへのリンクとともに並べます。
使う理由
素の Flutter の Web ビルドには、ダウンロード中の空白のページ、開発中のランダムなポート、検索エンジンやリンクのプレビューのためのテキストがないこと、アプリ内ブラウザーでスワイプすると閉じてしまうページ、そして必要な 9 倍のピクセルを描くスマートフォンがあります。それぞれの修正は忘れやすい数行の HTML や YAML です。ここではそれらはプロパティで、application-web.yml で他の設定とともに保持されます。
例
# 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 で表示 | ページローダー |
flutter run の開発サーバー |
固定のポート、プロキシ、ヘッダー、Content Security Policy | 下記 |
| アドレス | # のないパス、#見出し へのリンク |
Web とディープリンク |
| ディープリンク | web/ の下の .well-known のファイル |
ディープリンク |
| SEO | アドレスごとの本物の HTML ページ、サイトマップ、リンクのプレビュー | SEO |
| フォント | 言語ごとのフォント。フォールバックのダウンロードなし | 下記 |
| 必要なときのアセット | ページや画像は読まれるときだけダウンロードされる | 下記 |
| WebAssembly | flutter build web --wasm |
下記 |
| Markdown のプレースホルダー | ページの中の {{key}} を設定から |
下記 |
| フレームメーター | 毎秒のフレーム数。リリースでも | 下記 |
| タイムライン | 起動とすべての観測。リリースでも | タイムライン |
| ログイン | サーバーがログインさせるか、ブラウザーが自分で行う | 下記 |
| ホスティング | 静的ホストと spring_boot_starter_web |
下記 |
| ブラウザーキャッシュ | spring.web.resources.cache.cachecontrol.* から web/_headers を書き出す。ビルドのファイルは問い合わせ直し、アセットは保持する |
Web ビルドのブラウザーキャッシュ |
アプリを囲むページ
ジェネレーターは、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 のページも同じ属性を得ます。
すべてのブロックとそのマーカー: ページのヘッドとマニフェスト。
ブラウザーのバーの色
テーマがあれば、ビルドはその primary の色を <meta name="theme-color"> として、surface をページの背景とマニフェストの background_color として書き込みます。スマートフォンのブラウザーは、そのバーをその色で塗ります。system (ライトとダークのテーマ) では、prefers-color-scheme: light 用と dark 用の二つの theme-color タグと、ダークの背景も書き込みます。バーは訪問者が見ているテーマに合います。テーマの色 を参照してください。
ページのローダー
ブラウザーが Flutter をダウンロードする間、ページは、ジェネレーターがアクティブなテーマの splash から書き出すもの (その背景、ロゴ、タイトル、ローダー) を HTML と CSS で表示します。Flutter のスプラッシュが描かれると、途切れなく引き継ぎます。書き出されるものについては ページローダー を、テーマ側については ローダーとスプラッシュ を、ブラウザーがアプリをコンパイルする間も動き続けるアニメーションについては 止まらない 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_boot_starter_flutter_navigation を使うと、アドレスバーはルートを # の後ではなくパス (/catalog/books/1) として表示します。/docs/beans#bean-methods へのリンクは、最初の読み込みでも、その見出しまでスクロールしたページを開きます。ホストはアプリのすべてのアドレスにページで応える必要があります。ブラウザーのアドレス を参照してください。
ディープリンク
同じアドレスでモバイルアプリを開くこともできます。Web アプリでは、ジェネレーターが apple-app-site-association と assetlinks.json を web/.well-known/ に書き出すため、サイトはアプリとともにそれらを配信します。Web とディープリンク と ディープリンク を参照してください。
SEO
検索エンジンとリンクのプレビューはアプリを実行しないため、空のページを見ます。spring.flutter.web.seo.enabled を使うと、ビルドはアドレスごとに本物の HTML ページを書き出します。タイトル、説明、プレビューのタグ、テキストを持ち、sitemap.xml、robots.txt、llms.txt、各ページの Markdown のコピーも書き出します。手順は SEO にあります。
フォント
一つの言語のために宣言したフォント (spring.flutter.fonts.families.<family>.languages) は、アプリがその言語を表示するときだけダウンロードされます。テーマの font-family-fallback で指定すると、メインのフォントにない文字のために Web のエンジンがページごとに自分のフォールバックのフォントを取りに行くことも止まります。アセットとフォント と 言語のためのフォント を参照してください。それ以外の文字は、フォントのウォームアップ が必要なものをスプラッシュの背後でダウンロードします。
必要なときにダウンロードされるファイル
デフォルトでは lib/resources/ のすべてのファイルがプログラムに埋め込まれるため、ブラウザーはそのすべてをダウンロードします。spring.resources.embed.exclude は glob に一致するもの (content/**、images/**) を外します。それらは Flutter のアセットになり、ブラウザーはアプリが読むときだけダウンロードします。このサイトでは、main.dart.wasm が 11.6 MB から 3.7 MB になりました。ファイルをバイナリーから外す を参照してください。どの Flutter のアセットも asset:path として読めます。アセットとフォント を参照してください。 spring.resources.prefetch は、アプリが表示されたあとにそれらを 1 つのファイルでまとめてダウンロードするので、以後どのページもすぐに開きます (まとめてダウンロードする)。検索も同じように、言語ごとに 1 ファイルの自分のインデックスを読みます (ビルドが書くインデックス)。
WebAssembly
アプリは flutter build web --wasm でビルドしてください。Dart のコードは WebAssembly として実行され、JavaScript ビルドより高速です。対応していないブラウザーには、自動的に JavaScript ビルドが渡されます。アプリがブラウザーで実行できるパッケージはすべて Wasm にコンパイルでき、CI がそれを確かめます。詳しくは WebAssembly を参照してください。
Flutter のローダーは、指定がなければ WebAssembly のビルドを Chrome と Edge でだけ実行します。spring.flutter.web.page.wasm-allow-list を使うと、Firefox と Safari でも実行されます。
# 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 も同じ値を受け取ります。設定の値 を参照してください。
リリースでのフレームメーター
フレームメーターは、アプリが実際に描画する毎秒のフレーム数を表示します。リリースビルドにもそれだけで含められる (spring.flutter.debug.frame-meter.enabled) ため、本物のスマートフォンで本物のサイトを計測できます。⌘⇧X、または 5 回のタップと長押しで開きます。フレームメーター を参照してください。タイムライン (⌘⇧L) も同じようにリリースに含められ、起動の時間がどこに使われているかを示します。どちらもデバッグオーバーレイのドックを通じて同じ隅を共有します。
ブラウザーでのログイン
spring_boot_starter_flutter_security は、ブラウザーで spring.flutter.security.web.* を読みます。サーバーがユーザーをログインさせる (サーバーモード) か、ブラウザーが自分で行います (spa モード。上記の用意された Content Security Policy も設定します)。
ホスティング
flutter build web は build/web/ を書き出します。どの静的ホストでも配信できる、ただのファイルです。SEO のページがある場合は、ホストに合わせて spring.flutter.web.seo.page-files を選んでください。Cloudflare Pages、GitHub Pages、Netlify には html です。これらは <path>.html をリダイレクトなしで <path> で配信します。ページの配信 を参照してください。独自の Dart のサーバーからビルドを配信するには、静的リソース (spa-fallback、directory-index) を参照してください。
Cloudflare Pages では、ブラウザーがファイルを保持する期間は web/_headers で決まります。spring.web.resources.cache.cachecontrol.* を設定すると、ビルドのたびにそこへ規則のブロックが書き込まれます。ページ、main.dart.js などハッシュのないファイルには no-cache、アプリのアセットには設定した Cache-Control が付きます。Web ビルドのブラウザーキャッシュ を参照してください。