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 以降

ページの中の値

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 ビルドのブラウザーキャッシュ を参照してください。

関連項目