Flutter中iOS/Android端收起键盘后屏幕残留半屏空白占位问题

iOS和Android端偶现的键盘收起后屏幕下半部分被空白占位的问题，本质是Flutter布局计算与键盘状态更新不同步导致的视口尺寸异常，常见触发原因如下：

• Scaffold的键盘适配逻辑与ListView视口缓存冲突：键盘弹出时系统会向渲染树传递与键盘高度一致的底部安全边距，Scaffold默认会压缩内部布局的可用高度，ListView会基于该高度计算滚动范围；键盘收起瞬间如果边距更新和布局重绘时序不匹配，ListView会保留之前键盘高度对应的底部占位，渲染出与键盘等高的空白区域。
• 部分Flutter稳定版本（3.0~3.10区间版本）存在框架层已知bug：文本输入焦点解绑时机早于窗口边距重置时机，导致框架收到的布局约束没有及时更新为全屏高度，偶发布局计算错误。
• 页面嵌套多个可滚动组件、或手动添加键盘监听修改布局padding时，会打断Scaffold默认的边距适配流程，提升问题出现概率。

根据问题触发场景，可以按优先级选择以下方案修复：

基础适配：显式配置布局参数，强制视口随边距变化重算 #

这是适配成本最低的通用方案，给Scaffold和ListView显式配置对应参数，避免隐式默认值在不同场景下失效，修改后的完整页面代码如下：

TestPage.dart

class TestPage extends StatefulWidget {
  const TestPage({Key? key}) : super(key: key);

  @override
  State<TestPage> createState() => _TestPageState();
}

class _TestPageState extends State<TestPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      // 显式声明布局随键盘高度调整，避免嵌套场景下默认值失效
      resizeToAvoidBottomInset: true,
      body: ListView(
        // 给ListView设置唯一PageStorageKey，强制边距变化时重建视口
        key: const PageStorageKey('test_page_list_view'),
        // 使用ClampingScrollPhysics避免iOS回弹效果下的布局计算偏移
        physics: const ClampingScrollPhysics(),
        children: [
          const SizedBox(height: 50.0,),
          const TextField(),
          const SizedBox(height: 50.0,),
          const TextField()
        ],
      ),
    );
  }
}

问题现象参考截图：

偶现场景兜底：监听键盘状态主动触发重绘 #

如果基础适配后仍存在偶现问题，可以通过窗口监听感知键盘状态，在键盘完全收起时主动触发页面重绘，清空ListView缓存的错误占位尺寸。
首先自定义一个窗口变化监听器，重写didChangeMetrics回调感知边距变化：

class _WindowObserver extends WidgetsBindingObserver {
  final Function onMetricsChanged;
  _WindowObserver({required this.onMetricsChanged});

  @override
  void didChangeMetrics() {
    onMetricsChanged.call();
  }
}

在对应State中注册监听器，键盘收起时主动刷新布局：

@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addObserver(_WindowObserver(onMetricsChanged: () {
    // 获取当前系统传递的底部边距，边距为0代表键盘完全收起
    final bottomInset = WidgetsBinding.instance.window.viewInsets.bottom;
    if (bottomInset == 0 && mounted) {
      setState(() {});
    }
  }));
}

@override
void dispose() {
  // 页面销毁时移除监听器，避免内存泄漏
  WidgetsBinding.instance.removeObserver(_WindowObserver(onMetricsChanged: (){}));
  super.dispose();
}

框架bug根治 #

如果当前使用的Flutter版本在3.10及以下，可以直接升级到3.13及以上的稳定版本，官方已经在该版本线修复了多起键盘收起时边距更新不同步的框架问题；如果暂时无法升级SDK版本，可以在Scaffold外层包裹SafeArea组件，强制布局基于实际可见视口计算尺寸，从约束层面避免错误空白占位。

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