BuildContext — 概要、主要概念、動作原理

BuildContextとは？

BuildContextは、Elementクラスによって実装されるインターフェースであり、UI階層内でのウィジェットの位置に関する情報を提供します。BuildContextの各インスタンスはツリー内の特定の位置に固有であり、別の場所に移動することはできません。ウィジェットが親を変更した場合（たとえば別のコンテナに移動した場合）、新しいBuildContextを受け取ります。

BuildContextの主な目的は、InheritedWidgetへのアクセスを提供することです。コンテキストを通じて、ウィジェットはツリーを上方向に辿り、最も近いTheme、MediaQuery、Navigator、またはDirectionalityインスタンスを見つけます。このメカニズムは、Flutterにおけるテーマ設定、ナビゲーション、アダプティブレイアウトのシステム全体の基盤となっています。BuildContextがなければ、どのウィジェットもこれらのデータにアクセスできません。

Flutterアーキテクチャドキュメント（Google、2026）によると、BuildContextはサイズ測定と配置のためにウィジェットに関連付けられたRenderObjectを見つけるためにも使用されます。findRenderObject()やsizeなどのメソッドはコンテキストを通じて利用可能です。コンテキストはLocalizations.of(context)を介してローカライゼーションへのアクセスも提供します。

BuildContextはElementであり、Widgetではない

重要なアーキテクチャ上の理解：BuildContextはElementが実装するインターフェースであり、Widgetではありません。ElementはWidget（設定）とRenderObject（実際の表示）の間の“接着剤”です。ドキュメントが“ウィジェットコンテキスト”と言うとき、それはそのウィジェットを管理する要素を指します。buildメソッドはまさにこの種類のコンテキストを受け取ります — 作成中のウィジェットのコンテキストであり、返される子ウィジェットのコンテキストではありません。

BuildContextの仕組み

BuildContextのメカニズムは、要素ツリーを下から上に走査することに基づいています。ウィジェットがTheme.of(context)を呼び出すと、コンテキストは現在の要素から検索を開始し、ルートに向かって上方向に移動し、各要素をThemeタイプのInheritedWidgetについてチェックします。見つかった最初のInheritedWidgetが返されます — これにより、ウィジェットが最も近い定義からテーマを受け取ることが保証されます。

各BuildContextは親コンテキスト（parent）と子コンテキストへの参照を保存します。これは双方向の接続であり、ツリーを上方向（親へ）と下方向（子へ）の両方に移動できます。Flutterでは、InheritedWidgetの検索は上方向の走査のみを使用します — ウィジェットは祖先からのみデータを取得でき、子孫からは取得できません。これは基本的なアーキテクチャ上の制約です。

Flutterソースコード（Flutter SDK、2026）によると、BuildContextにはvisitAncestorElements、visitChildElements、findAncestorWidgetOfExactType、dependOnInheritedWidgetOfExactType、getRenderObjectのメソッドが含まれています。最後の2つが最もよく使用されます。dependOnInheritedWidgetOfExactTypeはInheritedWidgetを見つけるだけでなく、その変更にもサブスクライブします（InheritedWidgetが変更されるとウィジェットは再構築されます）。

コンテキストを通じたサブスクリプション

dependOnInheritedWidgetOfExactTypeは、リアクティビティを提供するBuildContextの主要なメソッドです。ウィジェットがTheme.of(context)を呼び出すとき、テーマを取得するだけでなく、その変更にもサブスクライブします。Themeが変更された場合（たとえばダーク/ライトモードの切り替え時）、サブスクライブしているすべてのウィジェットが自動的に再構築されます。これがFlutterにおけるリアクティビティのメカニズムです。

BuildContext vs Element

BuildContextはインターフェースであり、Elementはその実装です。Flutterコードでは、特定の要素タイプ（StatelessElement、StatefulElement、ProxyElementなど）を知らなくても、常にBuildContextインターフェースを通じて作業します。これは意図的なものです。開発者は要素の実装の詳細を知る必要はありません — 環境にアクセスするためのインターフェースで十分です。

異なる要素タイプはBuildContextを異なる方法で実装します。StatelessElementはbuild呼び出しを単に通過させ、StatefulElementはStateを管理し、InheritedElementはdependOnInheritedWidgetOfExactTypeを介してサブスクリプションを追跡します。ただし、開発者の観点からは、これらはすべて統一されたAPIを持つBuildContextです。

Dartコード例

テーマとメディアクエリにアクセスするためのBuildContextの基本的な使用法：

class ThemedText extends StatelessWidget {
  const ThemedText({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    final media = MediaQuery.of(context);

    return Container(
      padding: EdgeInsets.all(media.size.width * 0.02),
      child: Text(
        'スタイル付きテキスト',
        style: theme.textTheme.headlineMedium,
      ),
    );
  }
}

BuildContextを通じたナビゲーションの例。Navigator.of(context)はコンテキストを使用してツリー上方で最も近いNavigatorを見つけます：

class _NavigateButtonState extends State<NavigateButton> {
  void _navigate() {
    Navigator.of(context).push(
      MaterialPageRoute(
        builder: (_) => const DetailsScreen(),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _navigate,
      child: const Text('詳細へ移動'),
    );
  }
}

BuildContextを通じてウィジェットのサイズを見つける例。findRenderObject()メソッドは、サイズを取得できるRenderObjectを返します：

void _printSize(BuildContext context) {
  final renderBox = context.findRenderObject() as RenderBox?;
  if (renderBox != null) {
    print('ウィジェットサイズ: ${renderBox.size}');
  }
}

重要：findRenderObject()は、ウィジェットがまだマウントされていないか、すでにアンマウントされている場合にnullを返します。使用する前に必ず結果がnullでないことを確認してください。buildの完了前にbuild内でこのメソッドを呼び出した場合もnullを返す可能性があります。

InheritedWidgetとBuildContext

InheritedWidgetは、BuildContextを通じてツリー下方に効率的にデータを伝播する特別なウィジェットです。子ウィジェットがMyInheritedWidget.of(context)を呼び出すと、BuildContextはツリーを上方向に辿り、一致するタイプの最も近いInheritedWidgetを見つけてそのデータを返します。同時に、コンテキストは変更にサブスクライブします。InheritedWidgetが変更されると、サブスクライブしているすべてのウィジェットが自動的に再構築されます。

BuildContext + InheritedWidgetの組み合わせは、グローバル変数とプロップドリリング（コンストラクタの連鎖を通じてデータを渡すこと）を置き換えます。10レベルのウィジェットを通じてテーマを渡す代わりに、各ウィジェットはTheme.of(context)を介して直接アクセスできます。これによりコードがよりクリーンになり、渡されるパラメータの数が減ります。

Flutterチーム（Google、2026年4月）によると、InheritedWidgetは非常に効率的なメカニズムであるため、すべての公式状態管理ソリューションがこれに基づいて構築されています。ProviderはInheritedWidgetをラップし、Riverpodはそれをレイヤーの1つとして使用し、Flutter SDK自体（Theme、MediaQuery、Navigator、Localizations）は完全にこのアーキテクチャに基づいています。

独自のInheritedWidgetを作成する

独自のInheritedWidgetを作成すると、外部依存関係なしでデータを伝播できます。クラスはInheritedWidgetを拡張し、静的メソッドof(BuildContext context)を提供します。これは単純なシナリオにおけるProviderのミニマルな代替手段です：

class AppConfig extends InheritedWidget {
  final String apiUrl;
  final bool useDarkMode;

  const AppConfig({
    super.key,
    required this.apiUrl,
    required this.useDarkMode,
    required super.child,
  });

  static AppConfig of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<AppConfig>()!;
  }

  @override
  bool updateShouldNotify(AppConfig oldWidget) {
    return apiUrl != oldWidget.apiUrl || useDarkMode != oldWidget.useDarkMode;
  }
}

これで、ツリー下方の任意のウィジェットが設定にアクセスできます：final config = AppConfig.of(context);。設定が変更されると、サブスクライブしているすべてのウィジェットが自動的に再構築されます。

よくある間違い

最初のよくある間違いは、dispose後にBuildContextを保持するか、mountedを確認せずに非同期コールバックで使用することです。BuildContextは要素に結びついており、要素は破棄される可能性があります（ウィジェットがツリーから削除された場合）。要素が破棄された後にコンテキストを使用すると例外が発生します。解決策はcontext.mounted（新しいFlutterバージョンで利用可能）を使用するか、Stateでmountedを確認することです。

2番目の間違いは、initStateでTheme.of(context)を呼び出すことです。initStateの段階では、コンテキストはまだツリーに完全にマウントされていません。initStateでInheritedWidgetを検索すると、nullが返されるか例外がスローされる可能性があります。すべてのof(context)呼び出しは、コンテキストがツリー内にあることが保証されているbuildまたはdidChangeDependenciesで行う必要があります。

3番目の間違いは、あるウィジェットのBuildContextを使用して別のウィジェットを操作することです。BuildContextは親子階層外でのウィジェット間相互作用のために設計されていません。別のウィジェットの状態を管理する必要がある場合は、コールバック、コントローラ、または状態管理ツールを使用してください。

4番目の間違いは、BuildContextをウィジェットのdisposeよりも長く生きる非同期関数に渡すことです。典型的なシナリオ：Navigator.of(context)が変数に保存され、ユーザーが画面を離れた後に使用される。解決策は、静的または長寿命のオブジェクトにコンテキストを保持しないことです。

非同期操作におけるコンテキスト

非同期操作でBuildContextを扱うための安全パターン：コンテキストを使用する前に必ずmountedを確認し、ウィジェットより長く生きる可能性のあるクロージャにコンテキストを保持しないでください：

Future<void> _safeNavigation(BuildContext context) async {
  await Future.delayed(const Duration(seconds: 2));
  if (!context.mounted) return;
  Navigator.of(context).push(MaterialPageRoute(...));
}

ベストプラクティス

BuildContextを扱うには、そのライフサイクルと制限を理解する必要があります。最初のルール：コンテキストは、それをパラメータとして受け取るメソッド（build、didChangeDependencies）内でのみ使用してください。クラスフィールドや静的変数にコンテキストを保持しないでください — これはほとんどの場合バグにつながります。

2番目のルール：InheritedWidgetからデータにアクセスするには、buildよりもdidChangeDependenciesを優先してください。データがレンダリングではなく初期化にのみ必要な場合、didChangeDependenciesが適切な場所です。これにより、初期化ロジックをUI構築から分離でき、更新のたびに繰り返し呼び出されるのを防げます。

3番目のルール：非同期操作を扱う場合は、コンテキストに依存しないコールバックを使用するか、mountedを確認してください。非同期操作にナビゲーションやテーマへのアクセスが必要な場合は、これらのデータを事前に（同期的なbuildまたはinitStateコンテキストで）取得し、コンテキストではなくローカル変数に保存してください。

コンテキストが必要な場合と不要な場合

• 必要： Theme、MediaQuery、Navigator、Localizations、ScaffoldMessengerへのアクセス
• 必要： サイズ測定のためのRenderObjectの検索
• 必要： SnackBar、BottomSheet、Dialogの作成
• 不要： ビジネスロジックメソッドの呼び出し、HTTPリクエスト、DB操作
• 不要： build外部でのウィジェット構築（ファクトリ、コンストラクタ内）