Flutter横屏模式下如何实现内容延伸绘制到Android刘海区域

核心问题原因 #

Android 原生系统对横屏下刘海区域的显示策略默认和竖屏不一致，仅配置 Flutter 端的 UI 延伸参数无法覆盖系统层面的刘海布局限制。

分步解决配置 #

1. 新增 Android 原生层面刘海适配配置 #

在 android/app/src/main/res/values/styles.xml 的 App 主题样式中添加刘海适配属性：

<item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>

如果需要适配 Android P 及以上版本，额外在 values-v28/styles.xml 中添加相同配置。该属性指定内容可以延伸到屏幕短边的刘海区域，横屏时刘海刚好位于短边位置，从系统层面放开刘海区域的占用限制。

2. 调整 Flutter 端系统 UI 配置 #

保留已配置的竖屏适配代码，补充横竖屏切换时的统一沉浸模式设置逻辑：

import 'package:flutter/services.dart';

// 在页面初始化、或屏幕方向变化回调中执行以下代码
SystemChrome.setEnabledSystemUIMode(SystemUiMode.edgeToEdge);
SystemChrome.setSystemUIOverlayStyle(
  const SystemUiOverlayStyle(
    statusBarColor: Colors.transparent,
    systemNavigationBarColor: Colors.transparent,
  ),
);

3. 调整 Scaffold 相关参数 #

确保 Scaffold 的两个延伸参数都处于开启状态：

Scaffold(
  extendBody: true,
  extendBodyBehindAppBar: true,
  // 若不需要使用默认AppBar可省略该参数
  appBar: AppBar(
    backgroundColor: Colors.transparent,
    elevation: 0,
  ),
  body: YourContentWidget(),
)

4. 内容避让适配 #

内容区域使用 SafeArea 按需避让系统操作区域，避免关键内容被刘海、状态栏或导航栏遮挡：

body: SafeArea(
  // 可根据业务需求自定义各方向是否需要避让
  left: true,
  top: true,
  right: true,
  bottom: true,
  child: YourContentWidget(),
),

验证注意事项 #

• 先卸载设备上已安装的旧版应用，避免缓存配置未生效
• 重新编译运行应用，横竖屏切换时确认刘海区域都可正常显示内容
• 若仍有黑边，检查是否有第三方全屏插件修改了系统UI配置，优先使用原生配置实现沉浸效果

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