ローダーとスプラッシュ

テーマは、アプリのローダーと、アプリの起動中に表示されるスプラッシュ画面を記述できます。それらには三つの場所があり、見た目は一つです。

  1. コンポーネントのローダー loaders.<name>。アプリのどこでも ThemeLoader と ThemeSkeleton が表示します。
  2. スプラッシュ splash。アプリケーションコンテキストの起動中に SpringApplicationWidget が表示します。
  3. 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.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 は、プロパティが読まれた瞬間からコンテキストの準備ができるまで、アクティブなテーマのスプラッシュを表示します。

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 が作られてからのものです。

ステージは三つの方法で読みます。

@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 変数

推奨事項:

ブラウザーの 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      # 二つのフレームの間の処理

仕組み:

  1. Bean のファクトリーは、即時のシングルトンを一つずつ作ります。二つの Bean の間で、その StartupPacer に待つべきかを尋ねます。
  2. スターターのペーサー FramePacer は、前のフレームからの時間を計ります。frame-budget 未満なら続けるよう伝え、次の Bean が即座に作られます。超えれば Flutter にフレームを求め、その終わり (SchedulerBinding.endOfFrame) を待ちます。スプラッシュが描かれ、その後 Bean の作成が続きます。
  3. 予算が 8 ms でフレームが約 16 ms なら、起動が続く間、スプラッシュはフレームの約半分を保ちます。

制限:

別の 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       # タスクが占めるローダーの割合

アプリのテキストのためのフォント (Web)

Web では、Flutter はアプリのフォントにない文字 (日本語、中国語、アラビア語、絵文字) のためのフォントを持ちません。それらを初めてレイアウトするときに Noto フォントを断片ごとにダウンロードし、断片が届くたびにすべてのテキストを再びレイアウトします。そのため、言語を初めて変えると一秒ほどカクつきます。

スターターの textWarmUp タスクは、有効にすると、スプラッシュの表示中にアプリのテキストのすべての文字をレイアウトし、フォントがもう届かなくなるまで待ちます。テキストは次から来ます。

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 (デフォルトでは無効) は起動を計測します。

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:) に渡します。

関連項目