Flutterの画面状態を覆うEasyLoadingの設計

Contextを渡さない表示API

flutter_easyloadingはiOS、Android、Webを対象にした軽量なloadingとtoastのウィジェットです。READMEの中心的な特徴はBuildContextを各呼び出しへ渡さず、アプリ全体からEasyLoadingを呼べることです。処理中のloading、完了率を持つdeterminate progress、成功や失敗のresult、短いtoastを同じ仕組みで表示できます。これは画面階層をまたぐ通知を簡単にしますが、どの画面にも自動で適切な文脈が生まれるという意味ではありません。表示が残る場合の解除責任を呼び出し側で設計してください。

Hostはアプリのrootに配置する

Quick StartではMaterialAppまたはCupertinoAppのrootにEasyLoading Hostを一つインストールします。MaterialとCupertinoのどちらにも対応するため、アプリの入口に置けば下位画面から同じAPIを利用できます。複数のHostを置くと表示層や設定の所在が分かりにくくなるので、まずmainのwidget treeで一箇所に限定します。初期化が済む前に非同期処理が始まらないこと、ルートを差し替えるテストでもHostが維持されることを確認してから、実際のAPI呼び出しへ進むのが安全です。

グローバル初期値と個別指定

ライブラリは組み込みindicator、custom widget、custom transitionを持ち、グローバルな既定値を設定できます。個別の呼び出しではimmutable per-call overridesとして、その表示だけを上書きできます。全画面で同じ半径やindicatorを使いたい場合は既定値に寄せ、決済やアップロードなど意味の違う処理だけ個別値を渡す形が読みやすくなります。READMEのAPI表にはtextAlignの既定値center、contentPadding、indicatorSize 40、radius 5、fontSize 15などが記載されています。見た目を変える前に、この既定値が対象画面で収まるかを確認してください。

表示、解除、遷移を分けて扱う

表示とdismissには専用APIがあり、表示状態の変更にはstatus callback、解除にはdismiss callbackを登録できます。APIの責務を、処理の開始、進捗値の更新、成功または失敗の結果、最後のdismissに分けると、通信例外でもローディングが残りにくくなります。transitionの長さやdismissOnTap、userInteractionsは、下のアプリへの入力を通すかという別の設定です。処理中に背後のボタンを押せる構成を許すなら、二重送信が起きないかを対象画面で確認し、必要な場合は入力を閉じてください。

SDK条件と採用前の確認

READMEの要求環境はDart 3.6.0以上4.0.0未満、Flutter 3.27.0以上です。まずpubspecの制約を合わせ、アプリのMaterialAppとCupertinoAppの両方でHostを起動します。Webを対象にする場合は、ブラウザのサイズでindicatorとstatus textが欠けないことも確認します。提供された情報はUI部品の機能とAPI例が中心で、性能測定やアクセシビリティの完全な保証は示していません。status callbackが解除後に期待した回数だけ呼ばれるか、ページ遷移中の非同期処理が古い画面へ表示しないかをテストして採否を決めてください。

非同期処理で残留表示を防ぐ

EasyLoadingを実際の画面へ入れるときは、HTTP呼び出しやファイル処理の開始前にshowを呼び、成功と失敗の両方でresultまたはdismissへ到達する構造にします。例外、タイムアウト、画面破棄が重なったときに、古い処理のstatus callbackが新しい画面を覆わないかを確認します。determinate progressは入力値の範囲と更新頻度を固定し、0から完了までが飛ばないことを試します。dismissOnTapを有効にした場合、表示を閉じても背後の送信ボタンが二度押しされないよう、処理中の状態を別途管理します。Webでは小さいviewport、Materialではテーマ変更、Cupertinoではsafe areaを試し、indicatorSize 40と既定paddingがstatus textを欠かせないかを確認します。

Hostとcallbackを画面遷移で確認する

Flutter EasyLoadingのHostをMaterialAppのrootに置いた場合とCupertinoAppのrootに置いた場合で、同じshow、progress、dismissが動くかを試します。HTTP処理を開始してすぐにrouteを破棄し、status callbackとdismiss callbackが古いcontextを参照しないことを確認します。built-in indicatorとcustom widgetを同じ既定値で表示し、contentPadding、textPadding、radius、fontSizeが長いstatus textを欠かせないかを比較します。userInteractionsを許可した場合の二重操作、dismissOnTapでの途中解除、timeout後の残留表示をテストします。Dart 3.6.0以上4.0.0未満とFlutter 3.27.0以上の組み合わせを固定し、Webの小さい画面も含めて結果を記録します。

表示の終了を例外でも確認する

MaterialAppとCupertinoAppのrootにHostを一つ置き、show、progress、result、dismissを順に呼びます。route破棄、timeout、dismissOnTap、userInteractionsを試し、status callbackが古い画面へ残らないか確認します。Dart 3.6.0以上4.0.0未満、Flutter 3.27.0以上でWebの小画面も実行します。 callbackの登録と解除を対にし、removeCallbackとremoveDismissCallbackが対象関数だけを外すか確認します。長い文言、カスタムindicator、テーマ変更を同じHostで試し、画面ごとに初期値を再設定しない構成を保ちます。 loadingが表示されない初期化順序と、dismiss後もoverlayが残る例外経路をwidget testにし、MaterialとCupertinoの両方で実行します。 progressの完了、resultの表示、dismissのcallbackを一つの非同期テストで確認し、例外時に必ず表示が閉じることを記録します。 Hostを一つに保ち、表示と解除の順序をwidget testで固定します。 例外時のdismissとroute破棄後のcallbackをwidget testで確認します。 MaterialAppとCupertinoAppのrootで同じ表示を試し、route破棄後にoverlayとcallbackが残らないことを記録します。

編集部の結論

非同期処理の状態をアプリ全体で簡潔に表示したいFlutter開発者に向いています。導入時はMaterialAppまたはCupertinoAppのrootにHostを一つだけ置き、表示解除をtryとfinallyで対応させ、DartとFlutterの対応版を固定して実機の画面遷移を検証してください。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes