BuildContext、InheritedWidget 与数据向下传递

BuildContext 是什么？

很多初学者以为 BuildContext 是某种神秘对象。实际上，BuildContext 就是 Element。每个 Widget 的 build(BuildContext context) 中，context 就是自己对应的 Element，只是通过 BuildContext 接口暴露其能力。

// BuildContext 接口的关键方法
abstract class BuildContext {
  Widget get widget;                    // 对应的 Widget
  RenderObject? findRenderObject();     // 找到对应的 RenderObject
  T? dependOnInheritedWidgetOfExactType<T>(); // 订阅 InheritedWidget
  T? findAncestorWidgetOfExactType<T>(); // 查找祖先 Widget（不订阅）
  // ...
}

// Element 实现了 BuildContext
class StatelessElement extends ComponentElement implements BuildContext {
  // ...
}

context 的"作用域"

context 代表 Widget 在树中的位置。用 context 做查找时，是从该位置向上遍历（或向下），而不是全树搜索。

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // 向上查找最近的 Theme InheritedWidget
    final theme = Theme.of(context);
    return Text('hello', style: theme.textTheme.bodyMedium);
  }
}

常见错误：使用错误的 context

class WrongWidget extends StatefulWidget {
  @override
  State<WrongWidget> createState() => _WrongWidgetState();
}

class _WrongWidgetState extends State<WrongWidget> {
  @override
  void initState() {
    super.initState();
    // ❌ 错误：initState 阶段的 context 还没注册到树里
    // final theme = Theme.of(context);  // 可能崩溃

    // ✅ 正确：initState 后执行
    WidgetsBinding.instance.addPostFrameCallback((_) {
      final theme = Theme.of(context); // 此时已安全
    });
  }
}

InheritedWidget：Flutter 的数据向下流动

InheritedWidget 是 Flutter 跨层级传数据的核心机制，Theme、MediaQuery、Navigator 都基于它。

核心思想：把数据放在树的某个祖先节点，任何后代都能「订阅」到它，无需手动层层传参（避免 prop drilling）。

      ThemeWidget（InheritedWidget，持有 ThemeData）
           │
     ┌─────┴──────┐
 ChildA        ChildB
                  │
              GrandChild → Theme.of(context) 直接取到数据

实现一个 InheritedWidget

// 1. 定义 InheritedWidget
class AppConfig extends InheritedWidget {
  final String apiBaseUrl;
  final bool debugMode;

  const AppConfig({
    required this.apiBaseUrl,
    required this.debugMode,
    required super.child,
  });

  // 重要：判断数据是否变化，决定是否通知订阅者
  @override
  bool updateShouldNotify(AppConfig oldWidget) {
    return apiBaseUrl != oldWidget.apiBaseUrl ||
           debugMode != oldWidget.debugMode;
  }

  // 静态 of 方法：标准访问模式
  static AppConfig of(BuildContext context) {
    final config = context.dependOnInheritedWidgetOfExactType<AppConfig>();
    assert(config != null, 'No AppConfig found in the widget tree');
    return config!;
  }

  // 可选：不依赖（不订阅）的访问方式
  static AppConfig? maybeOf(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<AppConfig>();
  }
}

// 2. 放在树的顶部
void main() {
  runApp(
    AppConfig(
      apiBaseUrl: 'https://api.example.com',
      debugMode: false,
      child: MyApp(),
    ),
  );
}

// 3. 任意后代访问
class ApiClient extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final baseUrl = AppConfig.of(context).apiBaseUrl; // 订阅
    return Text('API: $baseUrl');
  }
}

dependOnInheritedWidgetOfExactType vs findAncestorWidgetOfExactType

// 只需要读一次，不关心后续变化（如在 initState）
final config = context.findAncestorWidgetOfExactType<AppConfig>();

// 需要响应变化（如在 build）
final config = context.dependOnInheritedWidgetOfExactType<AppConfig>();
// 等价于标准 of 方法：AppConfig.of(context)

updateShouldNotify 的精确控制

updateShouldNotify 决定了什么时候通知订阅者：

@override
bool updateShouldNotify(AppConfig oldWidget) {
  // 只有 apiBaseUrl 变化才重建（debugMode 变化不影响订阅者）
  return apiBaseUrl != oldWidget.apiBaseUrl;
}

如果 updateShouldNotify 总是返回 false，订阅者永远不会因这个 InheritedWidget 的变化而 rebuild（但 parent rebuild 仍然可能触发子节点 rebuild）。

实践：自定义 Theme 系统

// 用 InheritedWidget + Notifier 实现主题切换
class ThemeController extends ChangeNotifier {
  bool _isDark = false;
  bool get isDark => _isDark;
  void toggle() {
    _isDark = !_isDark;
    notifyListeners();
  }
}

class AppTheme extends InheritedNotifier<ThemeController> {
  const AppTheme({
    required ThemeController controller,
    required super.child,
  }) : super(notifier: controller);

  static ThemeController of(BuildContext context) {
    return context
        .dependOnInheritedWidgetOfExactType<AppTheme>()!
        .notifier!;
  }
}

// 用法
class DarkModeButton extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final controller = AppTheme.of(context);
    return Switch(
      value: controller.isDark,
      onChanged: (_) => controller.toggle(),
    );
  }
}

InheritedNotifier 是一个内置的 InheritedWidget 子类，自动监听 Listenable（如 ChangeNotifier）并在通知时触发 updateShouldNotify。这正是 Provider 包底层的实现原理。

BuildContext 的常见误用

误用 1：async gap 后使用 context

void _handleTap() async {
  await Future.delayed(Duration(seconds: 1));
  // ⚠️ 警告：async gap 后 context 可能已失效（Widget 已销毁）
  Navigator.of(context).push(...);
}

// ✅ 正确方式
void _handleTap() async {
  final nav = Navigator.of(context); // async 前保存引用
  await Future.delayed(Duration(seconds: 1));
  nav.push(...);
  // 或者判断 mounted
  if (!mounted) return;
  Navigator.of(context).push(...);
}

误用 2：在 initState 中用 context 查找祖先

// ❌
void initState() {
  super.initState();
  Theme.of(context); // 此时 context 还未完全注册，可能 null
}

// ✅ 方案一：PostFrameCallback
void initState() {
  super.initState();
  WidgetsBinding.instance.addPostFrameCallback((_) {
    Theme.of(context); // 第一帧之后安全
  });
}

// ✅ 方案二：在 didChangeDependencies
void didChangeDependencies() {
  super.didChangeDependencies();
  Theme.of(context); // ✅
}

误用 3：Dialog/SnackBar 使用错误 context

// Scaffold.of(context) 要求 context 在 Scaffold 之下
// ❌
class MyPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: ElevatedButton(
        onPressed: () {
          // 这个 context 是 MyPage 的，在 Scaffold 之上
          ScaffoldMessenger.of(context).showSnackBar(/* ... */); // 可能失败
        },
        child: Text('Show'),
      ),
    );
  }
}

// ✅ 方案：Builder 创建新的 context
Scaffold(
  body: Builder(
    builder: (scaffoldContext) => ElevatedButton(
      onPressed: () {
        ScaffoldMessenger.of(scaffoldContext).showSnackBar(/* ... */); // ✅
      },
      child: Text('Show'),
    ),
  ),
)

Builder 是一个专门用来「创建新 context」的 Widget，它的 builder 回调收到的 context 是 Builder 自身的，处于 Scaffold 之下，因此可以正确找到 ScaffoldMessenger。