ページローダー

spring_flutter_page_loader ビルダーは、アプリの web/index.html にページローダーを書き込みます。ページの最初のバイトから、Flutter 自身のスプラッシュが描画されるまでの間にブラウザーが表示するものです。アクティブなテーマの splash から作られるので、Web ページとアプリのスプラッシュは同じ見た目になります。同じビルダーは、設定からページの <head> と web/manifest.json にも値を入れます。

使う理由

Flutter Web アプリは、ブラウザーがエンジンとアプリのコードをダウンロードして起動するまで何も表示しません。多くの場合、数秒間の白いページです。Flutter のスプラッシュは Flutter が動き出してから現れるので、その時間を覆うことはできません。

ブラウザーがすぐに表示できるのはページの HTML だけです。そこでビルダーは、ビルド時にテーマのスプラッシュを HTML と CSS に変えます。スプラッシュの背景、ロゴ、タイトル、ローダーを、テーマの色で表したものです。スプラッシュをテーマに一度記述すれば、ページとアプリの両方がそれを使います。

動くとき

ビルダーは、名前が spring_boot_starter_flutter で始まる依存関係 (または開発用の依存関係) を持ち、web/index.html が存在するパッケージで動きます。存在しないページが作られることはありません。テーマの問題でビルドを止めることはありません。使えないものは警告になります。テーマのエラーは 型付きキー のビルダーが報告します。

spring_flutter_seo より前に動くので、検索エンジン向けのページ はローダーがすでに入ったページのコピーです。

例

ロゴ、タイトル、組み込みの bar ローダーを表示するスプラッシュを持つテーマ:

# lib/resources/application.yml
spring:
  flutter:
    theme:
      loaders:
        boot:
          kind: bar
          color: '#336699'
          track: '#DDE6F0'
          height: 4
      splash:
        background: { color: '#FFFFFF' }
        logo: { source: assets/images/logo.png, size: 64 }
        title: Books
        loader: boot

ビルダーは <body> の直後にこのブロックを書き込みます (簡略化。固定の CSS ルールとスクリプトは ... に短縮しています)。

<!-- spring:loader:start -->
<!-- Written by spring_core_dart_generator from the splash of the active theme; rewritten on every build. -->
<style id="spring-loader-style">
#spring-loader{position:fixed;top:0;right:0;bottom:0;left:0;z-index:2147483647;...;--spring-progress:0}
...
@media (prefers-reduced-motion:reduce){#spring-loader *{animation:none!important;transition:none!important}}
#spring-loader{background:#ffffff;color:#1a1a1a;--spring-logo-size:64px;--color:#336699;--track:#dde6f0;--height:4}
#spring-loader .sl-bar{width:calc(var(--width,220) * 1px);...}#spring-loader .sl-logo{width:var(--spring-logo-size);height:var(--spring-logo-size)}
</style>
<div id="spring-loader" role="status" aria-busy="true" aria-label="Loading" data-kind="bar" data-stage="start"><div class="sl-body"><img class="sl-logo" src="assets/assets/images/logo.png" alt="" decoding="async"><div class="sl-title">Books</div><div class="sl-kind"><div class="sl-bar"><span></span></div></div></div></div>
<script>
(function () {
  var root = document.getElementById('spring-loader');
  ...
})();
</script>
<!-- spring:loader:end -->

順を追うと:

  1. 固定のルールは、ローダーをページ全体の上に置き (position:fixed、最大の z-index)、その内容を中央に配置します。
  2. #spring-loader{...} ルールは、ページの背景 (background:#ffffff)、背景の明るさから選ばれた文字色 (明るい背景では #1a1a1a、暗い背景では #f5f5f5)、ロゴのサイズ、そしてローダーのすべてのキーを CSS 変数として保持します。
  3. bar の種類のルールは、デフォルト付きでそれらの変数を読みます: var(--height,3)、var(--color, <テーマの primary>)。
  4. <div> はロゴ、タイトル、ローダーの HTML を保持します。
  5. スクリプトは Flutter の起動を追い、Flutter の準備ができたらローダーを取り除きます。

ブロックの置き場所

ブロックは <!-- spring:loader:start --> と <!-- spring:loader:end --> の間にあります。

ブロックはビルドのたびに書き直されるので、ブロックではなくテーマを編集してください。

どのテーマか

ビルダーは型付きキーのビルダーと同じようにテーマを読みます。プロファイルにかかわらず lib/resources/ のすべての .properties、.yml、.yaml ファイルと、spring.config.import が resources: で指定し、依存関係の lib/resources/ が保持するファイル (ライブラリが同梱するテーマ) です。

spring.flutter.theme.active がテーマを選びます。

active ブロック ダークのルール
テーマの名前 そのテーマのスプラッシュ なし
system、または未設定 system-light のテーマ (デフォルトは light) @media (prefers-color-scheme:dark){...} の中に system-dark のテーマ (デフォルトは dark)

system では、ブロックが書かれるにはライトのテーマにスプラッシュがなければなりません。ダークのルールは、ダークのテーマにもスプラッシュがあり、その値が異なる場合にだけ追加されます。それはダークのテーマの値で #spring-loader{...} の宣言を繰り返します。ローダーの HTML はライトのテーマのものなので、両方のテーマで一つのローダーの種類を使うべきです。

色はビルド時に解決されます。参照 ($colors.primary)、色オブジェクト ({ color: $colors.primary, alpha: 14% })、シードカラーが作る Material のロールです。このサイトのライトのテーマは primary: '#8A6A00' を宣言しているので、そのページは theme-color #8a6a00 を受け取ります。

入るもの

背景、ロゴ、タイトル

スプラッシュのキー ページでは
background.color ローダーの background
background.gradient (type: linear または radial、colors、stops、begin、end) begin から end への角度の linear-gradient(...)、または begin を中心とする radial-gradient(circle min(80vw,80vh) at x% y%, ...)。二色以上が必要
どちらもない テーマの surface の色
logo.source <img class="sl-logo">。アセットのパス (assets/images/logo.png) は、Flutter がアセットを配信するアドレス assets/assets/images/logo.png になる。http(s):// の URL と data:image/ の URL はそのまま使われる。それ以外 (別のスキーム、//、..) はロゴなしと警告になる
logo.size --spring-logo-size。ピクセル単位。デフォルトは 96
title <div class="sl-title">。HTML 用にエスケープされる
loader loaders.* の下のローダーの名前。ローダーでない名前は警告になり、ページはロゴとタイトルだけを表示する

組み込みのローダーの種類

五つの組み込みの種類 (spinner、dots、pulse、bar、skeleton) には CSS の形があります。それぞれ CSS 変数を通してローダーのキーを読むので、color や size のようなキーは、アプリを変えるのと同じようにページを変えます。

種類 HTML 読む変数とデフォルト
spinner リング --color (primary)、--size (40)、--track (transparent)、--animation-duration (900ms)
dots count 個のドット (デフォルトは 3、1 から 12) --color、--size (10)、--animation-duration (900ms)、--animation-curve (ease-in-out)
pulse 大きくなる円 --color、--size (40)、--animation-duration (1200ms)、--animation-curve (ease-out)
bar --spring-progress に従うプログレスバー --color、--track (primary の 20%)、--width (220)、--height (3)、--radius (999)
skeleton きらめく三本の線 --base (surface-container-high)、--highlight (surface-container-highest)、--radius (6)、--shimmer-angle (20)、--shimmer-duration (1200ms)

サイズはピクセル数です。CSS がそれを掛け算します (calc(var(--size,40) * 1px))。

アプリ独自の種類: web:

アプリが宣言する種類 (@ThemeLoaderKind('spring-leaf')) のローダーは Dart のコードで描画されますが、ページにはそれがありません。その web: キーは、ページの中でそれを描画する HTML ファイルを指定します。ファイルのテキストはそのままブロックに入ります。このサイトのローダー:

# neon_farum_azula: lib/resources/application.yml (短縮)
loaders:
  spring-leaf:
    kind: spring-leaf
    phases:
      enter: { duration: 1400ms, curve: linear }
      fill: { progress: true, min-duration: 1.8s }
      exit: { duration: 700ms, curve: linear }
    leaf:
      color: $neon.green
      size: 120
    ring:
      track: { color: $neon.cyan, alpha: 14% }
    title:
      text: SPRING DART
    web: loaders/spring-leaf.html
splash:
  background: { color: '#04070D' }
  loader: spring-leaf
<!-- neon_farum_azula: lib/resources/loaders/spring-leaf.html (冒頭) -->
<style>
#spring-loader .sk-leaf{width:calc(var(--leaf-size,120) * 1px);...}
#spring-loader .sk-title::before{content:var(--title-text)}
...
</style>
<div class="sk">...</div>

ファイルは次の順で探されます。

  1. アプリの lib/resources/<path>。
  2. アプリのディレクトリの下の <path>。
  3. アプリの dependencies の各パッケージの lib/resources/<path> (テーマとそのローダーを同梱するライブラリ)。

パスはディレクトリの下にとどまらなければなりません。絶対パスや .. を含むパスは警告とともに拒否されます。ファイルがない場合は警告になり、ローダーは空のままです。web: のないアプリ独自の種類は、警告とともに代わりに組み込みの bar を受け取ります。

ダウンロードする web: ファイル

web: はアドレスにもでき、パッケージなしでローダーを共有できます。

loaders:
  gate:
    kind: neon-gate
    web: github:owner/loaders/[email protected]
    web-sha256: 3f5a...e9   # ファイルの SHA-256 (16 進数)
アドレス ダウンロード元
https://... 書かれたとおり
github:owner/repo/path/to/file@ref raw.githubusercontent.com。ブランチ、タグ、またはコミット ref
http://... spring.remote.allow-insecure: true の場合のみ。それ以外ではエラー

ダウンロード:

HTML はスクリプトも含めてそのままページに入ります。信頼できるアドレスから、タグかコミットで取得し、web-sha256 で固定してください。

CSS 変数としてのローダーのキー

ローダーのすべてのキーは、そのパスをケバブケースにした名前で、#spring-loader の CSS 変数になります。leaf.size は --leaf-size、ring.track は --ring-track、title.letter-spacing は --title-letter-spacing です。トップレベルの kind、web、web-sha256 は除外されます。値:

値 CSS では このサイトの例
色、色への参照、色オブジェクト #rrggbb、透明度があれば rgba(r, g, b, a) --leaf-color:#2a8c52、--ring-track:rgba(11, 127, 143, 0.141)
数値 単位なし: calc(var(--x) * 1px) を使う --leaf-size:120
期間 ミリ秒 --phases-fill-min-duration:1800ms
true / false 1 / 0 --phases-fill-progress:1
curve という名前のキー CSS のタイミング関数: linear、ease、ease-in、ease-out、ease-in-out、そして decelerate、fast-out-slow-in、emphasized、emphasized-decelerate、emphasized-accelerate、ease-in-cubic、ease-out-cubic、ease-in-out-cubic には cubic-bezier(...)。それ以外は ease --tracks-draw-curve:ease-out
その他のテキスト 引用符付きの CSS 文字列 --title-text:"SPRING DART"
リスト 要素を , でつないだもの。色のリストは、円形のグラデーションを閉じるために最初の色を --<name>-first としても与える --edge-colors:#ff0000,#00ff00,#0000ff、--edge-colors-first:#ff0000

インセットと画像は書かれません。テーマの中の何ものも、ページの中で自分の場所から出ることはできません。CSS 文字列は引用符、バックスラッシュ、<、>、&、改行をエスケープし、タイトルと属性は HTML 用にエスケープされます。</style><script>alert(1) というタイトルはテキストのままです。

ページは #spring-loader に独自の変数と属性を追加します。

名前 意味
--spring-progress 0 から 1: Flutter の起動がどこまで進んだか
data-stage start、次に load、app、engine、run、done
data-splash-stage ページのスクリプトが動くと page、Flutter のエンジンが起動すると engine
data-kind ローダーの種類の素の形 (spring-leaf なら springleaf)
data-fill-at、data-fill-min 進捗のフェーズに min-duration があるローダーで、そのフェーズが始まる時点 (それより前のアニメーションのフェーズの後) とその最小値、ミリ秒単位。このサイトは data-fill-at="1400" data-fill-min="1800" を持つ。ループするフェーズが先に来る場合は書かれない

スクリプト

スクリプトはどのアプリでも同じで、その動作を変えるのは上の属性だけです。

  1. Flutter のローダーを追います。 _flutter.loader.load をラップし (flutter_bootstrap.js が後で _flutter.loader を定義する場合も)、段階を進めます。

    段階 タイミング 進捗の範囲
    load ページが動き、load が呼ばれる 0.08 から 0.45
    app アプリのエントリーポイントが読み込まれる 0.5 から 0.6
    engine エンジンが起動する 0.6 から 0.88
    run エンジンの準備ができる 0.9 から 0.95
    done Flutter の最初のフレーム (flutter-first-frame) 1

    段階の中では、進捗はその段階の上限へゆっくり近づきます。表示される値はそれに向かって滑らかに動き (最大で範囲全体を 300 ms で)、アニメーションのフレームごとに --spring-progress に書き込まれます。data-fill-min があれば、表示される進捗は、Flutter のスプラッシュと同じく、イージングをかけた時計に合わせられます。

  2. 段階を報告します。 window.springLoader は progress、stage、elapsed、stages (到達した段階とその時刻)、handOff() を公開します。各段階に初めて到達すると spring-splash-stage イベントも発生します。

  3. Flutter に引き継ぎます。 Flutter のスプラッシュが描画されると、spring_boot_starter_flutter が window.springLoaderHandOff(progress) を呼びます。スクリプトはローダーの <div> とその <style> を取り除きます。

  4. 永遠に残ることはありません。 引き継ぎがなければ、ローダーは 60 秒後、または Flutter の最初のフレームから 3 秒後に取り除かれます。

  5. 動きを減らす設定を尊重します。 prefers-reduced-motion: reduce の下では、CSS ルールがローダーのすべてのアニメーションを止め、進捗はイージングをかけた時計を待たなくなります。

Content Security Policy

スクリプトのテキストは決して変わらないので、Content Security Policy はそのハッシュ 'sha256-...' で許可できます。ジェネレーターはそれを WebPageLoader.scriptHash として公開しています。Web 開発サーバー の spa モード (spring.flutter.security.web.mode: spa) の既製のポリシーは、アクティブなテーマにスプラッシュがある場合、そのハッシュを script-src に追加します。swipe-to-close: false と max-pixel-ratio (下記) のスクリプトも、設定されていればそのハッシュを追加します (WebPageHead.hashOf)。各スクリプトはタグの間に他に何もなく書かれるので、ブラウザーが計算するハッシュはポリシーの中のものと一致します。独自のポリシーでは、同じハッシュをその script-src に追加してください。

ページのヘッドとマニフェスト

同じビルダーは、設定の値を web/index.html の残りと web/manifest.json に書き込むので、手で繰り返すものはありません。Flutter のテンプレートは独自の値 (A new Flutter project.、プロジェクトの名前、#0175C2) を書きます。設定で設定された各値はテンプレートのものを置き換え、設定されていない値はファイルのものをそのままにします。これはスプラッシュの有無にかかわらず、ページのビルドのたびに行われます。

出どころ web/index.html web/manifest.json
spring.flutter.app.title <title>、そしてページにそのタグがあれば apple-mobile-web-app-title name、short_name
spring.flutter.app.description <meta name="description">。なければ追加される description
アクティブなテーマの primary (テーマが与えなければ #6750a4) <meta name="theme-color">。なければ追加される theme_color
アクティブなテーマの surface (テーマが与えなければ #ffffff) 背景のブロック (下記) background_color

色は、アプリに spring.flutter.theme.* キーがあれば常に書かれます。active: system (ライトとダークのテーマ) では、ページは両方を受け取ります。二つの theme-color のタグで、ライトのテーマの primary には media="(prefers-color-scheme: light)"、ダークのテーマのものには media="(prefers-color-scheme: dark)" が付き、<!-- spring:page:theme-color:start --> と <!-- spring:page:theme-color:end --> の間に書かれます (ページ自身の一つのタグを置き換えます)。背景のブロックにも、@media (prefers-color-scheme:dark){...} の中にダークの背景が入ります。スマートフォンのブラウザーのバーは、訪問者が見ているテーマの色になります。マニフェストは一つの色しか持てないため、ライトのテーマのものを受け取ります。spring.flutter.web.seo.* のヘッドを持つページは、独自の <title> と説明を保ちます。SEO のビルドがそのページのためにそれらを書いたからです。マニフェストは、レイアウトのためではなく、値が変わったときにだけ書き直されます。JSON オブジェクトでないマニフェストは、警告とともにそのままにされます。

さらにいくつかのブロックが、それぞれ独自のマーカーの間に、ヘッドに入ります。

ブロック マーカー 条件 内容
ビューポート なし: 一つの <meta name="viewport"> ページにビューポートのタグがない width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no。Flutter が起動時に設定するタグです。これがないと、スマートフォンはページを約 980 ポイントの幅でレイアウトするので、ローダーは三分の一のサイズで表示され、その後跳ねます。ページ独自のタグは保たれます
背景 <!-- spring:page:background:start --> / end アプリに spring.flutter.theme.* キーがある <style>html,body{background-color:#f5f6f9}</style>: Flutter が描画しない場所 (アプリ内ブラウザーのリサイズ、端の隙間) では、ページは白ではなくテーマの色になる。active: system では、@media (prefers-color-scheme:dark){...} のルールがダークのテーマの surface を加える
テーマの色、ライトとダーク <!-- spring:page:theme-color:start --> / end active: system で、ライトとダークのテーマがある 一つのタグの代わりに二つの <meta name="theme-color"> のタグ。(prefers-color-scheme: light) にはライトの primary、(prefers-color-scheme: dark) にはダークのもの
スワイプで閉じる <!-- spring:page:swipe:start --> / end spring.flutter.web.page.swipe-to-close: false アプリ内ブラウザー (メッセンジャーや SNS アプリのもの) が下へのスワイプでページを閉じないようにする <style> と <script>
ピクセル比 <!-- spring:page:pixel-ratio:start --> / end spring.flutter.web.page.max-pixel-ratio が 1 以上の数値 エンジンが起動する前に window.devicePixelRatio に上限を設けるスクリプト
翻訳 <!-- spring:page:translate:start --> / end、そして <html> の translate="no" spring.flutter.web.page.translate が false <meta name="google" content="notranslate">: キャンバスに描画されたテキストでは機能しえない翻訳を、ブラウザーや Google が提案しなくなる

このサイトのヘッド (書き出されたとおり):

<meta name="theme-color" content="#8a6a00">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

<!-- spring:page:background:start -->
<style>html,body{background-color:#f5f6f9}</style>
<!-- spring:page:background:end -->
<!-- spring:page:swipe:start -->
<style>@media (pointer: coarse){html{scrollbar-width:none}...flutter-view{position:fixed!important;inset:0!important;...}}</style>
<script>(function(){if(!(window.matchMedia&&matchMedia('(pointer: coarse)').matches))return;...})();</script>
<!-- spring:page:swipe:end -->
<!-- spring:page:pixel-ratio:start -->
<script>(function(){var m=2;if(window.devicePixelRatio>m){try{window.devicePixelRatio=m;}catch(e){}}})();</script>
<!-- spring:page:pixel-ratio:end -->

スワイプで閉じる

メッセンジャーや SNS アプリで開いたリンクはアプリ内ブラウザーで表示され、ページが最上部にあるときに下へスワイプするとページが閉じます。Flutter のページはキャンバスの中でスクロールするので常に最上部にあり、下へのスワイプのたびに閉じてしまいます。タッチスクリーン (pointer: coarse) では、このブロックはページを画面千個分の高さにし、末尾までスクロールし、Flutter のビューを画面の四辺に固定し、ブラウザー自身によるページのスクロール (touchmove) を止めます。ページが最上部になることはないので、下へのスワイプは Flutter のものになります。デフォルトの true では、ブロックは取り除かれます。

最大ピクセル比

スマートフォンの画面には 1 ポイントあたり 3 ピクセルがあるので、Flutter はすべてのフレームをページの 9 倍のピクセルで描画し、スマートフォンのグラフィックチップは全画面のスクロールでフレームを落とします。2 にすると描画するピクセルは 2.25 分の 1 になり、テキストは鮮明なままです。ブラウザーは描画を画面に合わせて拡大縮小します。値以下の画面はそのままにされます。1 以上の数値でない値は無視され、ブロックは取り除かれます。

プロパティ

テーマのキーは、プロファイルにかかわらずすべての設定ファイルから来ます (「どのテーマか」を参照)。その他のキーは、アプリがブラウザーで読むのと同じように読まれます。application.*、次に application-web.* (それより優先されます)、アクティブなプロファイルのファイル、インポートで、Web 開発サーバー と同じです。その読み込みが失敗した場合、それらは未設定とみなされます。

キー デフォルト 変えるもの
spring.flutter.theme.active、system-light、system-dark system、light、dark どのテーマのスプラッシュか、そしてダークのルール
spring.flutter.theme.splash.* (またはテーマの themes.<name>.splash.*) なし ブロック: 背景、ロゴ、タイトル、ローダー
spring.flutter.theme.loaders.<name>.* (またはテーマのもの) なし ローダーの種類、その CSS 変数、その web: ファイルと web-sha256
spring.flutter.theme.colors.*、シードカラー (またはテーマのもの) シードのロール 解決された色。ヘッドとマニフェストのための primary と surface
spring.flutter.app.title なし <title>、apple-mobile-web-app-title、マニフェストの名前
spring.flutter.app.description なし description のメタタグ、マニフェストの説明
spring.flutter.web.page.swipe-to-close true false でスワイプのブロックを書く
spring.flutter.web.page.max-pixel-ratio なし ピクセル比のブロックを書く
spring.flutter.web.page.translate true false で翻訳のブロックを書く
spring.remote.allow-insecure false true で web: の http:// アドレスを許可する

Spring (Java) との対応

Spring には対応するものがありません。Spring のアプリケーションには、クライアントのランタイムのダウンロードを待つ Web ページがないからです。

関連項目