Compose 中的刘海屏

刘海屏是指某些设备显示屏上的一个区域延伸到显示面。这样既能为用户提供全面屏体验，又能为设备正面的重要传感器留出空间。

图 1. 人像模式下的剪裁示例

图 2。横屏模式下的刘海区域示例

Android 在搭载 Android 9（API 级别 28）及更高版本的设备上支持刘海屏。不过，设备制造商也可以在搭载 Android 8.1 或更低版本的设备上支持刘海屏。

本页介绍了如何在 Compose 中实现对带刘海屏的设备的支持，包括如何处理“刘海区域”，即显示面上包含刘海的无边框矩形。

默认情况

默认情况下，以 API 级别 34 或更低级别为目标平台的应用或未调用 enableEdgeToEdge 的 activity 不会绘制到刘海屏区域，除非应用绘制到包含刘海屏的系统栏中。

在搭载 Android 15 或更高版本的设备上以 API 级别 35 或更高级别为目标平台的应用，或调用 enableEdgeToEdge 的 activity，会绘制到缺口区域。

换句话说，在搭载 Android 15 或更高版本的设备上，如果应用以 API 级别 35 或更高级别为目标平台，则 LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT、LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES 和 LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER 会被解读为 LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS，适用于非浮动窗口。

手动处理剪裁信息

您必须处理刘海区域信息，以防止刘海区域遮盖重要文本、控件或需要精细触摸识别的互动元素（刘海区域中的轻触灵敏度可能要比其他区域低一些）。处理剪裁时，请勿对状态栏高度进行硬编码，因为这样做可能会导致内容重叠或被切断。请改为通过以下任一方式处理缺口：

• 使用 WindowInsets.displayCutout、WindowInsets.safeContent 或 WindowInsets.safeDrawing

• 使用 LocalView.current.rootWindowInsets.displayCutout 访问剪裁 Path 对象

对于 Compose，我们建议您使用 displayCutout、safeContent 或 safeDrawing 处理可组合项中的切口内边距。通过这种方法，您可以在需要时遵循显示屏切口内边距，或在不需要时忽略它。

Canvas(modifier = Modifier.fillMaxSize().windowInsetsPadding(WindowInsets.displayCutout)) {
    drawRect(Color.Red, style = Stroke(2.dp.toPx()))
}
CutoutSnippets.kt

测试您的内容在使用剪裁功能时的呈现方式

请务必测试应用的所有屏幕和体验。如有可能，在具有不同类型刘海屏的设备上进行测试。如果您没有带刘海屏的设备，可以在搭载 Android 9 或更高版本的任意设备或模拟器上模拟常见的刘海配置，具体操作步骤如下：

1. 启用开发者选项。
2. 在开发者选项界面中，向下滚动到绘制部分，然后选择模拟刘海屏。
3. 选择刘海类型。

   

   图 3. 使用开发者选项测试内容的呈现方式。