
# スプラッシュと起動

アプリケーションコンテキストの起動中、`SpringApplicationWidget` はスプラッシュを表示します。独自の `splash:` ビルダー、またはアクティブなテーマの `splash` (背景、ロゴ、タイトル、起動の進行に従うローダー) です。その背後で設定が読まれ、Bean が作られ、`SplashTask` Bean が実行されます。すべての準備ができると、スプラッシュは退場を演じ、アプリが表示されます。

このページでは、起動の振る舞い、つまりステージ、タスク、`spring.flutter.splash` の下のプロパティを扱います。スプラッシュの見た目 (そのローダー、ロゴ、退場) はテーマのものです。[ローダーとスプラッシュ](themes/loaders.md) を参照してください。

## 使う理由

止まってしまうスプラッシュや、アプリが最初の画面を描く準備ができる前に消えてしまうスプラッシュは、壊れているように見えます。起動は自分の進行 (作られた Bean、呼ばれたランナー、終わったタスク) を知っているため、スプラッシュは本当の進行を示し、Bean が作られる間も動き続け、途切れなくアプリに引き継げます。最初の画面が必要とする処理 (キャッシュの充填、別の文字体系のフォントのダウンロード、ユーザーが選んだテーマ) は、アプリの表示後ではなく表示前に実行されます。

## 例

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      splash:
        background: { color: $colors.surface-container-lowest }
        logo: { source: assets/images/logo.png, size: 96 }
        title: NEON Books
        loader: dots
        min-duration: 1.2s
        exit: { transition: 400ms ease-out }
      loaders:
        dots: { kind: dots, color: $colors.primary, size: 10, count: 3 }
    splash:
      tasks:
        timeout: 5s
```

```dart
// アプリが表示される前に、最新の記事のキャッシュを満たす。
@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); // ローダーがこれに従う
    }
  }
}
```

## 起動のステージ

起動は、次のステージを順に通ります (`SplashStage`)。

| ステージ | 起きること |
|---|---|
| `page` | Web のみ: ブラウザーがページを開き、アプリのコードをダウンロードする。`web/index.html` のページのローダーが表示される |
| `engine` | Web のみ: Flutter のエンジンが起動する。ページのローダーはまだ表示されている |
| `splash` | Flutter が最初のフレームを描いた: スプラッシュが画面に出る (Web ではページのローダーが取り除かれる) |
| `starting` | アプリケーションが起動する: 設定が読まれ、Bean が作られる。ローダーが進行を表示する |
| `tasks` | `SplashTask` Bean が実行される。アプリが一つも持たなければ省略される |
| `ready` | コンテキストの準備ができた: ローダーが最後のフェーズを演じ、スプラッシュは `min-duration` まで待つ |
| `exit` | スプラッシュが退場を演じる |
| `app` | スプラッシュが消え、アプリが表示される |

Android と iOS では、`splash` の前にシステムの起動画面が表示されます。デスクトップでは、サイズとタイトルが設定されるまでウィンドウは表示されません。ステージを読むには:

- ローダーの中で、`frame.stage` とステージに従うトラックで ([ローダー](themes/loaders.md#トラック) を参照)。
- Bean として: `SplashStages`。`reached` (各ステージとその時刻)、`at(stage)`、`now` を持つ `ValueListenable<SplashStage>` です。
- イベントとして: ステージごとの `SplashStageEvent` (`stage`、`at`)。コンテキストが存在する前に到達したステージは、準備ができたときに順に発行されます。

```dart
// 各ステージの時刻をアプリの分析に送る。
@Component()
class StartMetrics {
  StartMetrics(this.analytics);

  final Analytics analytics;

  @EventListener()
  void onStage(SplashStageEvent event) =>
      analytics.record('start.${event.stage.name}', event.at);
}
```

時刻は、Web ではページの読み込みが始まってからの、それ以外では `SpringApplicationWidget` が作られてからのミリ秒です。

## スプラッシュのタスク

`SplashTask` Bean は、Bean が存在するようになってから、`ready` の前の `tasks` ステージで一度実行されます。すべてが同時に実行され、ローダーの最後の割合がその進行に従います。

- 進行を報告しないタスクは、終わったときに数えられます。
- 失敗したタスクは警告としてログに出ます。起動は続きます。
- `timeout` の後もまだ実行中のタスクは、アプリの背後で続きます。アプリは表示されます。
- `@Order` (または `Ordered`) が開始の順序を決めます。
- `SplashTaskContext.applicationContext` は起動したコンテキストです。

スターターには独自のタスクが二つあります。`themeChoiceRestore` はユーザーが前回選んだテーマを表示し ([テーマ](themes/index.md) を参照)、`textWarmUp` は有効にすると Web でフォントをダウンロードします (後述)。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.splash.tasks.enabled` | bool | `true` | アプリが表示される前に `SplashTask` Bean を実行する。`false`: 何も実行されず、Bean がローダー全体を占める |
| `spring.flutter.splash.tasks.timeout` | 期間 | `5s` | スプラッシュがタスクを待つ時間。まだ実行中のものはアプリの背後で続く |
| `spring.flutter.splash.tasks.share` | 0 から 1 の数値 | `0.2` | アプリにタスクがある場合に、タスクが占めるローダーの割合 |

## 起動中のフレーム

Bean の作成は UI スレッドでの処理です。Bean が作られる間、Flutter はフレームを描かず、スプラッシュは止まります。Web ではスプラッシュのすべてのフレームを同じスレッドが描くため、数百ミリ秒の起動は目に見える停止になります。

`yield-frames` を有効にすると、Bean のファクトリーは二つの Bean の間でペーサーに待つべきかを尋ねます。処理が `frame-budget` 未満なら続け、超えれば次のフレームを待ち、スプラッシュが描かれ、その後 Bean の作成が続きます。予算が 8 ms でフレームが約 16 ms なら、スプラッシュはフレームの約半分を保ちます。

```yaml
spring:
  flutter:
    splash:
      yield-frames: true   # デフォルト: Web では true、それ以外では false
      frame-budget: 8ms
```

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.splash.yield-frames` | bool | Web では `true`、それ以外では `false` | Bean の作成中に、Bean の間で Flutter にフレームを描かせ、スプラッシュが動き続けるようにする。`false` はペーサーを完全に無効にする |
| `spring.flutter.splash.frame-budget` | 期間 | `8ms` | `yield-frames` が有効なときの、二つのフレームの間の処理 |

制限: ペーサーは Bean の間でしか待たないため、200 ms かかる一つの Bean は、依然として 200 ms スレッドを占有します。そうした処理はコンストラクターの外に移してください。起動は、譲ったフレームの分だけ少し長くなります。

## アプリのテキストのためのフォント

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

`textWarmUp` タスクは、スプラッシュの表示中にアプリのテキストのすべての文字をレイアウトし、フォントがもう届かなくなるまで待ちます。テキストは `resources` のファイルと、各 `TextWarmUpSource` Bean から来ます。数えるのは文字だけで、それぞれ一度だけです。大きなファイルは読み込みのコストはかかりますが、レイアウトのコストはかかりません。 各ファミリーは、アプリのテキストと同じく、テーマの `font-family-fallback` を後ろに置いてレイアウトされます。言語のために宣言したフォント (`spring.flutter.fonts.families`) が持つ文字は、ダウンロードを必要としません。

```yaml
# lib/resources/application-web.yml
spring:
  flutter:
    splash:
      warm-up:
        text:
          enabled: true
          resources:
            - resources:messages*.properties
            - resources:content/**/*.ja.md
```

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.splash.warm-up.text.enabled` | bool | `false` | スプラッシュの表示中にアプリのテキストの文字をレイアウトし、必要なフォントがアプリの表示前にダウンロードされるようにする。Web で効果がある |
| `spring.flutter.splash.warm-up.text.resources` | 場所のパターンのリスト | `resources:messages*.properties` | その文字をレイアウトするファイル |
| `spring.flutter.splash.warm-up.text.first-font` | 期間 | `400ms` | この時間内にフォントがダウンロードされなければ、何も必要ないとみなしてウォームアップを終える |
| `spring.flutter.splash.warm-up.text.settle` | 期間 | `250ms` | フォントが届いた後、次が届かないままウォームアップを終えるまでの時間 |
| `spring.flutter.splash.warm-up.text.chunk` | 数値 | `200` | 一フレームでレイアウトする文字数。スマートフォンでスプラッシュが動き続けるように |

## 起動のトレース

どのアプリも Spring の `ApplicationStartup` を通じて起動を計測します。`splashTrace` Bean がステージごとのステップ (`spring.flutter.splash.<stage>`) と、すべてのアプリケーションイベントのステップ (`spring.event`、`eventName` で) を記録します。各 Bean の作成も、ビルドに[タイムライン](timeline.md)があるとき、または起動のログも出す `spring.flutter.splash.trace: true` のときにステップになります。`app` で、ステージと最も遅い五つの Bean を一行のログで示します。

```text
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 タブでメインスレッドの処理の隣に表示されます。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.splash.trace` | bool | `false` | 起動を計測する: 各ステージと各 Bean の作成を、最後にログに出す。Web では Performance タブのマークとしても |

[デバッグパネル](debug-panel.md) は、その Start タブで実行中のアプリのステージを表示します。

## スプラッシュの終わり方

- ローダーは起動の進行を受け取ります。作られた Bean 定義と呼ばれたランナーの割合、次にタスクの割合です。
- コンテキストの準備ができると、ローダーの最後のフェーズが演じられ、その後スプラッシュが `exit.transition` にわたってフェードアウトします。`min-duration` より前には終わりません。その間、アプリはその下で組み立てられます。
- ウィジェット自身の `splash:` ビルダーは、テーマのスプラッシュより優先されます。どちらもなければ、空のボックスが表示されます。
- システムが動きを減らすよう求めている場合、各フェーズは終わりの状態になり、何もちらつかず、スプラッシュはフェードなしで消えます。

## Web のページのローダー

ブラウザーが Flutter をダウンロードする間、ページは、ジェネレーターが同じテーマのスプラッシュから `web/index.html` に書き出すローダーを表示します。そのため、ページのローダーと Flutter のスプラッシュは同じ見た目で、途切れなく引き継がれます。[ページのローダー](../spring-core-dart-generator/flutter/page-loader.md) と [ローダーとスプラッシュ](themes/loaders.md) を参照してください。

## 関連項目

- [ローダーとスプラッシュ](themes/loaders.md)
- [SpringApplicationWidget](application-widget.md)
- [デバッグパネル](debug-panel.md)
- [すべてのプロパティ](properties.md)
