ページローダー
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 -->
順を追うと:
- 固定のルールは、ローダーをページ全体の上に置き (
position:fixed、最大のz-index)、その内容を中央に配置します。 #spring-loader{...}ルールは、ページの背景 (background:#ffffff)、背景の明るさから選ばれた文字色 (明るい背景では#1a1a1a、暗い背景では#f5f5f5)、ロゴのサイズ、そしてローダーのすべてのキーを CSS 変数として保持します。barの種類のルールは、デフォルト付きでそれらの変数を読みます:var(--height,3)、var(--color, <テーマの primary>)。<div>はロゴ、タイトル、ローダーの HTML を保持します。- スクリプトは Flutter の起動を追い、Flutter の準備ができたらローダーを取り除きます。
ブロックの置き場所
ブロックは <!-- spring:loader:start --> と <!-- spring:loader:end --> の間にあります。
- マーカーがある場合は、その間のブロックが置き換えられます。ファイルの他の部分は変わりません。
- マーカーがない場合は、ブロックは
<body>の直後に (<body>のないページでは</html>の前か末尾に) 置かれます。 - アクティブなテーマにスプラッシュがない場合は、ブロックはマーカーごと取り除かれます。
- マーカーが正しい順序の一組になっていない場合 (end のない start、二つの start)、ビルダーは警告し、ヘッドも含めてファイルを何も変えません。マーカーを直すか取り除いてください。
ブロックはビルドのたびに書き直されるので、ブロックではなくテーマを編集してください。
どのテーマか
ビルダーは型付きキーのビルダーと同じようにテーマを読みます。プロファイルにかかわらず 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>
ファイルは次の順で探されます。
- アプリの
lib/resources/<path>。 - アプリのディレクトリの下の
<path>。 - アプリの
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 の場合のみ。それ以外ではエラー |
ダウンロード:
- 最大 10 秒かかり、最大 5 回のリダイレクトを
httpsにだけたどります (安全でない接続が許可されていればhttpも)。 - 512 KiB を超えるファイルを拒否します。
web-sha256があれば、別のダイジェストのファイルを拒否し、保持しません。- アドレスとピンをキーとして、
.dart_tool/spring/loaders/にコピーを保持します。後のダウンロードが失敗した場合は警告とともにコピーが使われるので、オフラインでのビルドも動きます。
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" を持つ。ループするフェーズが先に来る場合は書かれない |
スクリプト
スクリプトはどのアプリでも同じで、その動作を変えるのは上の属性だけです。
-
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 doneFlutter の最初のフレーム ( flutter-first-frame)1 段階の中では、進捗はその段階の上限へゆっくり近づきます。表示される値はそれに向かって滑らかに動き (最大で範囲全体を 300 ms で)、アニメーションのフレームごとに
--spring-progressに書き込まれます。data-fill-minがあれば、表示される進捗は、Flutter のスプラッシュと同じく、イージングをかけた時計に合わせられます。 -
段階を報告します。
window.springLoaderはprogress、stage、elapsed、stages(到達した段階とその時刻)、handOff()を公開します。各段階に初めて到達するとspring-splash-stageイベントも発生します。 -
Flutter に引き継ぎます。 Flutter のスプラッシュが描画されると、
spring_boot_starter_flutterがwindow.springLoaderHandOff(progress)を呼びます。スクリプトはローダーの<div>とその<style>を取り除きます。 -
永遠に残ることはありません。 引き継ぎがなければ、ローダーは 60 秒後、または Flutter の最初のフレームから 3 秒後に取り除かれます。
-
動きを減らす設定を尊重します。
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 ページがないからです。