如何让Composable在带Display Cutout的设备上实现边缘到边缘全屏显示？

问题核心原因 #

挖孔设备的Display Cutout（刘海/挖孔）区域属于系统默认的「安全区域」Insets，即使隐藏状态栏，系统仍会默认保留这部分区域的Insets约束，限制Composable的布局范围。仅设置WindowCompat.setDecorFitsSystemWindows(window, false)只能取消系统栏的Insets约束，无法自动忽略Cutout的Insets限制。

解决方案步骤 #

1. 配置Window允许布局延伸到Cutout区域
   在Activity的onCreate方法（或Compose的SideEffect代码块）中添加以下配置，让布局可以覆盖挖孔区域：

   window.attributes.layoutInDisplayCutoutMode = WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
   

   可选的模式说明：

   • LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT：默认规则，仅全屏非沉浸式时允许延伸到Cutout
   • LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER：完全禁止布局覆盖Cutout区域
   • LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES：允许布局延伸到屏幕短边（顶部/底部）的Cutout区域

2. 在Compose中正确处理Insets
   即使配置了Window，仍需手动处理Insets，避免默认Padding限制布局范围：

   Box(
       modifier = Modifier
           .fillMaxSize()
           .systemBarsPadding(false) // 关闭系统栏自动添加的Padding
           .consumeWindowInsets(WindowInsets.displayCutout) // 完全消费Cutout的Insets，让布局覆盖该区域
   ) {
       Canvas(modifier = Modifier.fillMaxSize()) {
           drawRect(Color.Red, style = Stroke(width = 10f))
       }
   }
   

3. 使用正确的状态栏隐藏方式
   确保采用沉浸式全屏模式隐藏状态栏，让系统真正释放状态栏区域（包括Cutout部分）：

   val window = requireActivity().window
   val insetsController = WindowCompat.getInsetsController(window, window.decorView)
   insetsController.hide(WindowInsetsCompat.Type.statusBars())
   // 设置滑动显示状态栏的行为，可选
   insetsController.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
   

补充说明 #

• Android 12及以上系统对Cutout区域的布局限制更严格，必须显式设置layoutInDisplayCutoutMode才能让布局覆盖挖孔区域
• 若依赖androidx.compose.foundation:foundation，默认的systemBarsPadding会自动包含Cutout区域的Padding，需显式关闭或手动处理

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