Flutter中与TextFormField交互时OverlayEntry重复重建问题求助

问题分析 #

你遇到的OverlayEntry builder重复重建，主要有这几个原因：

1. 每次获取焦点时都重新创建OverlayEntry实例，频繁的创建和插入加剧了重建次数；
2. OverlayEntry的builder本身会在Flutter渲染周期中被多次触发（比如输入框文字变化、焦点切换时，UI会触发更新），这是框架的正常行为，但如果builder里依赖了外部静态值，就会导致不必要的重复计算；
3. 你在创建OverlayEntry时一次性获取输入框的位置和尺寸，不仅无法响应输入框位置变化（比如软键盘弹出后输入框上移），还会让builder每次重建都使用旧值，引发位置偏移问题。

修复方案 #

下面是调整后的完整代码，解决了重复重建和位置更新的问题：

class SearchOverlayDemo extends StatefulWidget {
  const SearchOverlayDemo({super.key});

  @override
  State<SearchOverlayDemo> createState() => _SearchOverlayDemoState();
}

class _SearchOverlayDemoState extends State<SearchOverlayDemo> {
  final FocusNode _focusNode = FocusNode();
  final GlobalKey globalKey = LabeledGlobalKey('OverlayEntry');
  late OverlayEntry _overlayEntry;

  @override
  void initState() {
    super.initState();
    // 只创建一次OverlayEntry，复用实例
    _overlayEntry = _createOverlayEntry();
    _focusNode.addListener(() {
      if (_focusNode.hasFocus) {
        print('Overlay showed');
        // 先检查是否已挂载，避免重复插入报错
        if (!_overlayEntry.mounted) {
          Overlay.of(context)!.insert(_overlayEntry);
        }
      } else {
        if (_overlayEntry.mounted) {
          _overlayEntry.remove();
        }
      }
    });
  }

  OverlayEntry _createOverlayEntry() {
    return OverlayEntry(
      maintainState: true, // 保留Overlay内部状态，比如列表滚动位置
      builder: (context) {
        // 这里必须实时获取输入框的位置和尺寸，避免位置偏移
        if (globalKey.currentContext == null) return const SizedBox.shrink();
        RenderBox renderBox = globalKey.currentContext!.findRenderObject() as RenderBox;
        final size = renderBox.size;
        final offset = renderBox.localToGlobal(Offset.zero);

        print('Overlay builder triggered');
        // 用RepaintBoundary隔离重绘区域，减少不必要的重绘开销
        return RepaintBoundary(
          child: Positioned(
            left: offset.dx,
            top: offset.dy + size.height + 5.0,
            width: size.width,
            child: Material(
              elevation: 4.0,
              child: ListView(
                padding: EdgeInsets.zero,
                shrinkWrap: true,
                children: const [
                  ListTile(title: Text('Syria')),
                  ListTile(title: Text('Lebanon')),
                  ListTile(title: Text('Jordan')),
                  ListTile(title: Text('Iraq')),
                ],
              ),
            ),
          ),
        );
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        widthFactor: 0.8, // 原widthFactor设为50会导致输入框异常宽，改为0.8适配屏幕
        child: TextFormField(
          key: globalKey,
          focusNode: _focusNode,
          decoration: const InputDecoration(labelText: 'Country'),
        ),
      ),
    );
  }

  @override
  void dispose() {
    _focusNode.dispose();
    // 组件销毁时记得移除Overlay，避免内存泄漏
    if (_overlayEntry.mounted) {
      _overlayEntry.remove();
    }
    super.dispose();
  }
}

额外优化建议 #

如果你的搜索列表需要根据输入文本动态过滤，可以用ValueNotifier来传递输入值，避免整个Overlay builder频繁重建：

// 新增一个ValueNotifier存储搜索文本
final ValueNotifier<String> _searchText = ValueNotifier('');

// 在TextFormField的onChanged中更新值
TextFormField(
  // ...其他属性
  onChanged: (text) => _searchText.value = text,
)

// 在Overlay的builder中用ValueListenableBuilder监听变化
ValueListenableBuilder<String>(
  valueListenable: _searchText,
  builder: (context, text, child) {
    // 根据text过滤列表数据
    final filteredCountries = countries.where((c) => c.contains(text)).toList();
    return ListView(
      shrinkWrap: true,
      children: filteredCountries.map((c) => ListTile(title: Text(c))).toList(),
    );
  },
)

内容的提问来源于stack exchange，提问作者Ahmed Jihad