Flutter插入Overlay时条目已存在异常的解决求助

问题原因 #

你遇到的异常是因为同一个OverlayEntry实例被多次插入到Overlay中。当前代码在didChangeDependencies触发时（比如键盘高度变化、组件树更新）都会调用_showOverlay，即便_overlayEntry已经存在且已插入，仍会执行insert操作，而Overlay不允许重复添加同一个entry。

修复方案 #

方案1：快速修复——检查entry是否已挂载 #

修改_showOverlay方法，只有当entry未挂载时才插入：

void _showOverlay(double keyboardHeight) {
  _overlayEntry ??= OverlayEntry(
    builder: (context) => Positioned(
      bottom: keyboardHeight,
      left: 0,
      right: 0,
      child: Material(
        elevation: 8.0,
        child: widget.keyboardWidget ?? Container(),
      ),
    ),
  );

  // 仅当entry未在Overlay中时才插入
  if (!_overlayEntry!.mounted) {
    Overlay.of(context).insert(_overlayEntry!);
  }
}

方案2：更可靠的实现——监听键盘状态变化 #

didChangeDependencies会在多种场景下触发，不是监听键盘的最佳方式。改用WidgetsBindingObserver监听窗口Insets变化，精准响应键盘状态：

更新_KeyboardAwareWidgetState类：

class _KeyboardAwareWidgetState extends State<KeyboardAwareWidget> with WidgetsBindingObserver {
  OverlayEntry? _overlayEntry;
  double _lastKeyboardHeight = 0;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void didChangeMetrics() {
    super.didChangeMetrics();
    WidgetsBinding.instance.addPostFrameCallback((_) {
      final keyboardHeight = MediaQuery.of(context).viewInsets.bottom;

      if (keyboardHeight > 0 && keyboardHeight != _lastKeyboardHeight) {
        _updateOverlay(keyboardHeight);
        _lastKeyboardHeight = keyboardHeight;
      } else if (keyboardHeight == 0 && _lastKeyboardHeight > 0) {
        _hideOverlay();
        _lastKeyboardHeight = 0;
      }
    });
  }

  void _updateOverlay(double keyboardHeight) {
    if (_overlayEntry != null) {
      // 键盘高度变化时，更新overlay位置
      _overlayEntry!.markNeedsBuild();
      return;
    }

    _overlayEntry = OverlayEntry(
      builder: (context) => Positioned(
        bottom: keyboardHeight,
        left: 0,
        right: 0,
        child: Material(
          elevation: 8.0,
          child: widget.keyboardWidget ?? Container(),
        ),
      ),
    );

    Overlay.of(context).insert(_overlayEntry!);
  }

  void _hideOverlay() {
    _overlayEntry?.remove();
    _overlayEntry = null;
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    _hideOverlay();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return widget.child;
  }
}

这个方案不仅解决了重复插入的问题，还能在键盘高度变化（比如切换输入法）时自动更新overlay的位置，确保始终贴合键盘顶部。

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