ローダーとスプラッシュ
テーマは、アプリのローダーと、アプリの起動中に表示されるスプラッシュ画面を記述できます。それらには三つの場所があり、見た目は一つです。
- コンポーネントのローダー
loaders.<name>。アプリのどこでもThemeLoaderとThemeSkeletonが表示します。 - スプラッシュ
splash。アプリケーションコンテキストの起動中にSpringApplicationWidgetが表示します。 - Web のページのローダー。テーマの
splashからジェネレーターがweb/index.htmlに書き出し、ブラウザーが Flutter をダウンロードする間に表示されます。
spring:
flutter:
theme:
loaders:
dots: { kind: dots, color: $colors.primary, size: 10, count: 3 }
upload: { kind: bar, color: $colors.primary, height: 3 }
card:
kind: skeleton
base: $colors.surface-container-high
highlight: $colors.surface-container-highest
radius: $shape.medium
shimmer: { duration: 1.2s, angle: 20 }
splash:
background: { color: $colors.surface-container-lowest }
logo: { source: assets/images/logo.png, size: 96 }
title: NEON
loader: dots
min-duration: 1.2s
exit: { transition: 400ms ease-out }
組み込みの種類
どのキーも省略できます。色はテーマの唯一の色の形式 (名前、#RRGGBB、$ の参照、または { color, mix, alpha }) を、期間は唯一の期間の構文 (900ms、1.2s) を受け取ります。animation はインラインで書く (duration、curve、repeat) か、animations.<name> の名前です。
| 種類 | キー (デフォルト) |
|---|---|
spinner |
color (テーマの primary)、size (24)、stroke (3)、track (なし)、animation (1s、linear、loop) |
dots |
color、size (8)、count (3)、gap (サイズの半分)、animation (900ms、ease-in-out、loop) |
pulse |
color、size (24)、animation (1.2s、ease-in-out、往復) |
bar |
color、track (20 % の色)、height (4)、width (120)、radius (高さの半分)、animation (1.4s、ease-in-out、loop。不確定のバーのため) |
skeleton |
base (#E0E0E0)、highlight (#F5F5F5)、radius (8)、shimmer.duration (1.2s)、shimmer.curve (linear)、shimmer.angle (20) |
組み込みの種類は暗黙の一つのフェーズを持ち、phases を受け取りません。未知の kind や、その種類が受け取らないキーは、プロパティと最も近い名前を示して起動を止めます。
表示する
// 不確定、または 0 から 1 の進行付き。
ThemeLoader(context.theme.loaders.dots)
ThemeLoader(context.theme.loaders.upload, progress: sent / total)
// コンテンツ、または読み込み中はそのスケルトン。
ThemeSkeleton(
context.theme.loaders.card,
loading: !book.hasLoaded,
placeholder: const BookTilePlaceholder(), // 省略可能: 表示する形
child: BookTile(book),
)
ThemeLoader(spec, {progress, ready, size, onFinished}): バーは progress で満たされます。ローダーが ready になると (デフォルトでは progress が 1 に達したとき)、繰り返すフェーズが終わり、最後のフェーズが再生されます。ThemeSkeleton(spec, {loading, child, placeholder}) は、プレースホルダー (または子) をスケルトンのベースの色で描き、その上をハイライトが横切り、タップとスクリーンリーダーから隠します。プレースホルダーも子もなければ、単なるブロックです。
ローダーは名前で context.theme.loaders.<name> (生成される)、または ThemeKeyReader(theme).loader('neon-gate') で読みます。
独自の種類
独自の種類は、@ThemeLoaderKind('name') を付けたクラスです。ThemeLoaderPainter<P> (キャンバスに描く) か ThemeLoaderWidget<P> (ウィジェットを組み立てる) を継承します。
loaders:
neon-gate:
kind: neon-gate
phases:
enter: { duration: 2s, curve: linear }
fill: { progress: true, min-duration: 2.5s } # 実際の進行、最低 2.5 秒
exit: { duration: 1400ms, curve: linear }
edge: { color: $neon.cyan, accent: $neon.red, width: 2, glow: 6 }
box: { color: $neon.red, width: 420, height: 46, skew: -18 }
web: loaders/neon-gate.html
@ThemeLoaderKind('neon-gate')
class NeonGateLoader extends ThemeLoaderWidget<NeonGateLoaderProps> {
const NeonGateLoader();
@override
Widget build(BuildContext context, LoaderFrame<NeonGateLoaderProps> frame) {
final enter = frame.phase('enter'); // 0..1
final box = frame.props.box; // テーマのキーから型付き
// ... ウィジェットを返す (例えば CustomPaint)
}
}
frame.phase(name)は 0 (未開始) から 1 (完了) です。frame.progressはローダーに与えられた進行 (不確定ならnull)、frame.propsはP、frame.valuesはローダーのキーを型なしで読み (values.color('box.color'))、frame.reduceMotionはシステムが動きを減らすよう求めているときに true です。- フェーズは書いた順に再生されます。アニメーションするフェーズ (
duration、curve、repeat) が再生されると次が始まります。繰り返すフェーズはローダーが準備できるまで続きます。{progress: true}は進行に従い、それが 1 に達すると終わります。複数あるうちの最後のものは準備ができるのを待ちます。min-durationを持つ進行のフェーズは、その時間にわたるイージングされた時計以上には進まないため、速い起動でもゆっくり満たされます (Web のページのローダーもこれに従います)。 - ジェネレーターは、テーマがその種類のローダーに与えるキーから
Pを書き出し、クラスをThemeLoaderKindsに登録します。ジェネレーターがなければ、テーマは起動時に読まれてすべてのkindをチェックするため、アプリケーションの起動前にThemeLoaderKinds.register<P>('neon-gate', widget: NeonGateLoader(), props: NeonGateLoaderProps.from, keys: [...])を呼んでください。 webは、Flutter の実行前に Web のページのローダーでその種類を表示する HTML ファイルを指定します。ローダーのキーはその中で CSS 変数になります (edge.glowは--edge-glow。色のリストは--<name>-firstも与えるため、円錐グラデーションが円を閉じられます)。ページのスクリプトはspringLoader.progressとspringLoader.elapsed(ミリ秒) を公開します。スプラッシュはそのフェーズを進行から (ThemeLoader.resumeFrom)、LoaderFrame.elapsedを経過時間から (ThemeLoader.resumeElapsed)始めるため、ちらつきやグリッチはページが残したところから続きます。- 絵全体を描く種類は
ThemeLoaderPainterかThemeLoaderWidgetです。そうしたローダーを持つスプラッシュにlogoやtitleは不要です。NEON のスプラッシュはこれを行います。光ってちらつく縁を持ち、異なる方向から滑り込む暗いパネルと、進行を示す傾いた赤い箱で、すべてテーマのキーから描かれます (Web のページでは CSS と SVG)。
トラック
フェーズは順に再生されます。それと並行して動くもの、例えば回転、コンテキストとともに始まる光、進行に従う塗りはトラックです。ローダーが毎フレーム frame.track(name) で読む 0 から 1 の値です。トラックを導くものはその follows です。
loaders:
spring-leaf:
kind: spring-leaf
tracks:
spin: { duration: 2.4s, repeat: loop } # follows: time
glow: { follows: stage, from: starting, duration: 1.2s, repeat: reverse }
draw: { follows: stage, from: splash, duration: 900ms, curve: ease-out }
fill: { follows: progress, smoothing: 400ms, curve: ease-in-out }
follows |
キー | 値 |
|---|---|---|
time (デフォルト) |
duration、curve、repeat (none、loop、reverse)、delay |
ローダーの開始から進む。Web ではページのローダーの開始からなので、ページが残したところから続く |
stage |
from (一つの ステージ)、duration、curve、repeat、delay |
起動が from に達するまでは 0、その後進む。ローダーが表示される前に到達したステージは、到達した時点から数える |
progress |
smoothing (300ms)、curve |
起動の進行。時定数 smoothing で実際の値に向かって動く。進行が跳んでも、決して跳ばない |
frame.stage はステージそのもので、時間ではなくステージによって変わる絵のためのものです。システムが動きを減らすよう求めている場合、トラックは静止します。一度再生するトラックは 1、繰り返すものは 0、進行のトラックは進行の値です。
各 follows は LoaderTrackDriver が読み、ドライバーはレジストリ LoaderTrackDrivers を成します。別のもの (ビート、ネットワーク、バッテリー) に導かれる動きは、スターターの変更ではなく、独自のドライバーです。アプリケーションの起動前に登録してください。テーマは起動時に読まれます。
// `follows: beat`: 各 `every` の最初の 100 ms は 1、それ以外は 0。
final class BeatTrackDriver implements LoaderTrackDriver {
const BeatTrackDriver();
@override
String get name => 'beat';
@override
List<String> get keys => const ['every'];
@override
LoaderTrack parse(LoaderValues values) =>
BeatTrack(values.duration('every'));
}
final class BeatTrack implements LoaderTrack, LoaderTrackRun {
const BeatTrack(this.every);
final Duration every;
@override
LoaderTrackRun run() => this; // 状態を持つ実行はそれ自身のオブジェクト
@override
double still(double? progress) => 0;
@override
double advance(LoaderClock clock) =>
clock.elapsed.inMicroseconds % every.inMicroseconds < 100000 ? 1 : 0;
}
void main() {
LoaderTrackDrivers.register(const BeatTrackDriver());
runApp(SpringApplicationWidget(application: createApplication));
}
LoaderClock はドライバーに、時間 (elapsed、前のフレームからの dt)、progress、stage、since(stage) を与えます。LoaderValues はトラックのキーを読み、そのエラーでプロパティを示します (values.fail(key, expected))。ドライバーが列挙しないキーや、どのドライバーも持たない follows は、プロパティと最も近い名前を示して起動を止めます。
ライブラリはそのテーマとともにローダーの種類を同梱できます。種類はライブラリの中に、それを使うテーマはライブラリの設定の中に置きます。
スプラッシュ
splash はマップで、すべてのアプリで読まれます。単なる splash: ripple は、引き続きタップのインクの効果です (Material のもので、spring_boot_starter_flutter_material が読みます。密度とインク を参照)。
| キー | 働き |
|---|---|
background |
テーマの 背景 のキー (screens を除く)。デフォルト: テーマの surface |
logo |
画像。size はその幅 (96) |
title |
ロゴの下のテキスト |
loader |
loaders.<name> の名前。組み込みの種類はタイトルの下に置かれ、独自の種類はロゴとタイトルの背後でスプラッシュ全体を覆う |
animation |
ロゴをフェードさせて大きくする animations.<name> の名前 |
min-duration |
スプラッシュが少なくともこの時間とどまる (デフォルトはなし) |
exit.transition |
フェードアウト: <duration> [<curve>] (デフォルトは 300ms ease-out) |
exit.reveal |
true: ローダーの最後のフェーズが始まると、スプラッシュの背景が消え、ローダーはその下で組み立てられるアプリの上で再生される (ページの上で分かれるパネル)。デフォルトは false |
SpringApplicationWidget は、プロパティが読まれた瞬間からコンテキストの準備ができるまで、アクティブなテーマのスプラッシュを表示します。
- ローダーは起動の進行を受け取ります。作られた Bean 定義と呼ばれたランナーの割合です。
{progress: true}のフェーズがそれに従います。 - コンテキストの準備ができると、ローダーの最後のフェーズが再生され、その後スプラッシュが
exitにわたってフェードアウトします。min-durationより前には終わりません。その間、アプリはその下で組み立てられます。 - ウィジェット自身の
splash:ビルダーは、テーマのスプラッシュより優先されます。 - システムが動きを減らすよう求めている場合、各フェーズは終わりの状態になり、何もちらつかず光らず、スプラッシュはフェードなしで消えます。
Web では、Flutter のスプラッシュが最初のフレームを描くと、ページが定義していれば window.springLoaderHandOff(progress) を呼ぶため、ページのローダーは途切れなく自身を取り除けます。Web 以外では何も呼ばれません。
起動のステージ
SpringApplicationWidget は、起動がどこにあるかをスプラッシュに伝えます。ステージはこの順に来ます (SplashStage)。
| ステージ | 起きること |
|---|---|
page |
ブラウザーがページを開き、アプリのコード (main.dart.js) をダウンロードする。web/index.html のページのローダーが表示される |
engine |
Flutter のエンジン (CanvasKit または skwasm) が起動する。ページのローダーはまだ表示されている |
splash |
Flutter が最初のフレームを描いた: テーマのスプラッシュが画面に出て、ページのローダーが取り除かれる |
starting |
アプリケーションが起動する: 設定が読まれ、Bean が作られる。スプラッシュが進行を表示する |
tasks |
スプラッシュ中のタスク が実行される (フォントのダウンロード、キャッシュの充填)。ローダーはその進行で続く。アプリが一つも持たなければ省略される |
ready |
コンテキストの準備ができた: ローダーが最後のフェーズを再生し、スプラッシュは min-duration まで待つ |
exit |
スプラッシュが退場を演じる (exit.transition または exit.reveal) |
app |
スプラッシュが消え、アプリが表示される |
各プラットフォームは、それが持つステージを通ります。
| プラットフォーム | ステージ | 最初のステージより前 |
|---|---|---|
| Web | page、engine、splash、starting、tasks、ready、exit、app |
なし: ページのローダーはページの最初の描画から表示される |
| Android、iOS | splash、starting、tasks、ready、exit、app |
エンジンの起動中のシステムの起動画面 (launch_background.xml、LaunchScreen.storyboard) |
| macOS、Windows、Linux | splash、starting、tasks、ready、exit、app |
ウィンドウはまだ表示されていない: スターターは、ウィンドウのサイズとタイトルが設定されるまで最初のフレームを保留する |
ステージは前にしか進みません。スプラッシュが表示されない場合 (テーマのスプラッシュも splash: ビルダーもない)、アプリはコンテキストとともに表示されるため、splash は省略されることがあります。
ページのスクリプトは page と engine をその時刻とともに window.springLoader.stages に記録し、ローダーの要素に data-splash-stage を設定し、spring-splash-stage イベントを送るため、ページ自身の CSS が反応できます。Flutter 側は最初のフレームでそれらを読み、同じ時計で続けます。時刻はページの読み込みが始まってからのミリ秒で、どのプラットフォームでも SpringApplicationWidget が作られてからのものです。
ステージは三つの方法で読みます。
- ローダーの中で:
frame.stage、そしてfollows: stageのトラック。 - Bean として:
SplashStages(ValueListenable<SplashStage>)。reached(各ステージとその時刻)、at(stage)、nowを持ちます。 - イベントとして: ステージごとの
SplashStageEvent(stage、at)。コンテキストが存在する前に到達したステージは、準備ができたときに順に発行されるため、リスナーはそのすべてを見ます。
@Component()
class StartMetrics {
@EventListener()
void onStage(SplashStageEvent event) =>
analytics.record('start.${event.stage.name}', event.at);
}
止まらない Web のページのローダー
ページのローダーが表示されている間、ブラウザーは忙しくしています。main.dart.js (数メガバイト) をダウンロードし、解析してコンパイルし、次に CanvasKit か skwasm を起動します。これはすべてブラウザーのメインスレッド、つまりページの JavaScript を実行し、ページをレイアウトし、そのほとんどを描画するスレッドで実行されます。それが忙しい間、それが駆動するものはすべて止まります。動かない進行の数字、描画が止まる SVG の線、脈動が止まる光です。これが、最初の 1、2 秒に見える停止です。
メインスレッドを必要としないアニメーションもあります。ブラウザーは transform と opacity の CSS アニメーションをコンポジター、つまりすでに描画されたレイヤーを動かしたりフェードさせたりする別のスレッドに渡します。それらは、メインスレッドがアプリをコンパイルする間も動き続けます。
| コンポジターで動く (滑らか) | メインスレッドで動く (止まる) |
|---|---|
transform: rotate、scale、translate |
stroke-dashoffset、stroke-dasharray |
opacity |
filter、drop-shadow、box-shadow |
width、height、top、left、background-position |
|
| 色、グラデーション、スクリプトが変える CSS 変数 |
推奨事項:
- スクリプトではなく、CSS の
@keyframesでtransformとopacityをアニメーションさせてください。要素が最初から独自のレイヤーを得るよう、will-change: transform(またはopacity) を追加してください。 - SVG の中の図形ではなく、ページの要素 (
div、または<svg>全体) をアニメーションさせてください。<g>や<path>のtransformはメインスレッドが描画します。動く部分にはそれぞれ独自の<svg>を与えてください。 - 線を描くのに
stroke-dashoffsetをアニメーションさせないでください。完成した線をマスクの下に置き、マスクをtransformで動かしたり回したりしてください。 - 光を脈動させるのに
filter: blur()やdrop-shadowをアニメーションさせないでください。光を独自のぼかしたレイヤーとして一度描き、そのopacity(とtransform: scale) をアニメーションさせてください。 - 回転するグラデーション: グラデーションの角度ではなく、要素を回してください (
transform: rotate)。 - 進行はスクリプトから来る (
--spring-progress) ため、メインスレッドのものです。アプリのコンパイル中は止まります。決して止まらない動き (回転、脈動) の隣に、変数でscaleするバーのような、待てるものとして表示してください。 - ページのローダーは小さく保ってください。その HTML と CSS のすべてのバイトが、何かが表示される前にダウンロードされます。
- Flutter のスプラッシュの最初のフレームに合わせてください。同じサイズと位置で、トラックはページの時計から続く
timeに従うため、引き継ぎで跳ぶことはありません。
ブラウザーの Performance タブで CPU を遅くして (4 倍の減速) 確認してください。メインスレッドの長い「Evaluate script」と「Compile」のブロックが実行される間も、ローダーは動き続けるべきです。
起動中にフレームを譲る
Bean の作成もメインスレッドの処理で、今度は Dart でのものです。Bean が作られる間、Flutter はフレームを描かず、スプラッシュは止まります。Web ではスプラッシュのすべてのフレームを同じスレッドが描くため、数百ミリ秒の起動は目に見える停止になります。
spring.flutter.splash.yield-frames はその間にフレームを入れます。
spring:
flutter:
splash:
yield-frames: true # デフォルト: Web では true、それ以外では false
frame-budget: 8ms # 二つのフレームの間の処理
仕組み:
- Bean のファクトリーは、即時のシングルトンを一つずつ作ります。二つの Bean の間で、その
StartupPacerに待つべきかを尋ねます。 - スターターのペーサー
FramePacerは、前のフレームからの時間を計ります。frame-budget未満なら続けるよう伝え、次の Bean が即座に作られます。超えれば Flutter にフレームを求め、その終わり (SchedulerBinding.endOfFrame) を待ちます。スプラッシュが描かれ、その後 Bean の作成が続きます。 - 予算が 8 ms でフレームが約 16 ms なら、起動が続く間、スプラッシュはフレームの約半分を保ちます。
制限:
- 200 ms かかる一つの Bean は、依然として 200 ms スレッドを占有します。ペーサーは Bean の間でしか待ちません。そうした処理はコンストラクターの外に移してください。
@Asyncメソッド、ランナー、または何かを待つ処理です。 - 起動は、譲ったフレームの分だけ少し長くなります。
yield-frames: falseでは一切ペース配分されず、以前と同じ速さです。 - Web 以外ではスプラッシュはラスタースレッドで描かれますが、UI スレッドは引き続き各フレームを組み立てます。スプラッシュを止める長い起動では、そこでも有効にしてください。
別の StartupPacer は、独自のペース配分のために、ApplicationContextInitializedEvent のリスナーによって Bean のファクトリー (DefaultListableBeanFactory.startupPacer) に設定します。
スプラッシュ中のタスク
アプリが表示される前に必要な処理は、スプラッシュの表示中に実行されます。SplashTask Bean です。それぞれは、Bean が存在するようになってから、ready の前の tasks ステージで一度実行されます。すべてが同時に実行され、ローダーの最後の割合がその進行に従います。
@Component()
class WarmCache extends SplashTask {
WarmCache(this.articles);
final ArticleRepository articles;
@override
String get name => 'articles';
@override
Future<void> run(SplashTaskContext task) async {
final ids = await articles.latest();
for (final (i, id) in ids.indexed) {
await articles.load(id);
task.progress((i + 1) / ids.length);
}
}
}
spring:
flutter:
splash:
tasks:
enabled: true # false: タスクは実行されず、Bean がローダーを占める
timeout: 5s # その時点でアプリが表示される。まだ実行中のタスクは続く
share: 0.2 # タスクが占めるローダーの割合
- 進行を報告しないタスクは、終わったときに数えられます。
- 失敗したタスクは警告としてログに出ます。起動は続きます。
@Order(またはOrdered) が開始の順序を決めます。SplashTaskContext.applicationContextは起動したコンテキストです。
アプリのテキストのためのフォント (Web)
Web では、Flutter はアプリのフォントにない文字 (日本語、中国語、アラビア語、絵文字) のためのフォントを持ちません。それらを初めてレイアウトするときに Noto フォントを断片ごとにダウンロードし、断片が届くたびにすべてのテキストを再びレイアウトします。そのため、言語を初めて変えると一秒ほどカクつきます。
スターターの textWarmUp タスクは、有効にすると、スプラッシュの表示中にアプリのテキストのすべての文字をレイアウトし、フォントがもう届かなくなるまで待ちます。テキストは次から来ます。
spring.flutter.splash.warm-up.text.resourcesのファイル (デフォルト: メッセージ、resources:messages*.properties)。- ファイルにないテキストのための各
TextWarmUpSourceBean。
spring:
flutter:
splash:
warm-up:
text:
enabled: true # デフォルトでは無効
resources:
- resources:messages*.properties
- resources:content/**/contents*.md
first-font: 400ms # この時間内にフォントがなければ、何も必要ない
settle: 250ms # フォントの後、次が届かないままの時間
chunk: 200 # 一フレームでレイアウトする文字数
数えるのは文字だけで、それぞれ一度だけです。大きなファイルは読み込みのコストはかかりますが、レイアウトのコストはかかりません。文字は一フレームに一つのチャンクとして chunk 個ずつレイアウトされるため、スマートフォンでもスプラッシュは動き続け、レイアウトは一度だけです。エンジンは最初のレイアウトで必要なすべてのフォントを求めます。そこに含まれない文字は、表示されるときに引き続きダウンロードされます。
起動のトレース
spring.flutter.splash.trace: true (デフォルトでは無効) は起動を計測します。
- 各ステージとその時刻。
- Spring の
ApplicationStartupを通じた、各 Bean の作成 (beanName付きのspring.beans.instantiate) とアプリケーション自身の手順 (spring.boot.application.*)。 appで、ステージと最も遅い五つの Bean を示すログの行:
INFO SplashTrace: The start: page 40 ms, engine 910 ms, splash 1420 ms, starting 1450 ms, ready 1730 ms, exit 2950 ms, app 3350 ms. 42 beans; the slowest: spring.beans.instantiate beanName=catalogRepository 96 ms, ...
Web では、同じ手順がブラウザーのパフォーマンスのタイムラインのマークとメジャー (spring:splash:<stage>、そして Bean ごとに一つのメジャー) になり、Performance タブでメインスレッドの処理の隣に表示されます。これにより、どの Bean がどのフレームを止めたかがわかります。
トレースは、Spring と同じく BufferingApplicationStartup です。別の記録係は SpringApplication(applicationStartup:) に渡します。
関連項目
- 背景:
splash.backgroundのキー - 画像:
splash.logoのキー - モーションとアニメーション:
animations.*とカーブ - スタイルと状態
- 設定:
spring.flutter.splash.*