Compose 中的刘海屏

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

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

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

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

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

默认情况

默认情况下，窗口内边信息中包含显示屏缺口。 因此，当您按照有关如何设置应用无边框的指南时，您的应用不会在刘海屏区域绘制。

例如，当您使用 Modifier.windowInsetsPadding(WindowInsets.safeContent) 或 Modifier.windowInsetsPadding(WindowInsets.safeDrawing) 时，应用不会自动在放置剪裁区域的区域中绘制。WindowInsets.safeContent 和 WindowInsets.safeDrawing 都包含显示屏刘海屏信息，并且不会在设备刘海屏所在的位置绘制内容。

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    WindowCompat.setDecorFitsSystemWindows(window, false)

    setContent {
        Box(Modifier.windowInsetsPadding(WindowInsets.safeContent)) {
            // Any composable inside here will avoid drawing behind cutouts
        }
    }
}
CutoutSnippets.kt

如需进一步自定义此行为，您需要自行处理刘海屏信息。

手动处理剪裁信息

您可以通过以下任一方式处理剪裁内容：

• 使用 WindowInsets.displayCutout

• 使用 android:windowLayoutInDisplayCutoutMode 在主题清单中进行设置

• 使用 window.attributes.layoutInDisplayCutoutMode 在 Window 上以编程方式设置选项

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

对于 Compose，建议在整体主题中将 windowLayoutInDisplayCutoutMode 设置为 default，然后利用 WindowInsets.displayCutout 处理可组合项中的边衬区：

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

这种方法可让您根据需要遵循 displayCutout 内边距，或忽略不需要的内边距。

或者，您也可以应用 Views 剪裁文档中所述的相同设置，方法是将 activity 主题 android:windowLayoutInDisplayCutoutMode 设置为其他选项，或使用 window.attributes.layoutInDisplayCutoutMode = LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT 设置窗口属性。不过，剪裁模式会应用于整个 activity，而无法按各个可组合项进行控制。

如需在某些可组合项（而非其他可组合项）中采用刘海屏，请使用 WindowInset.displayCutout。您可以通过此 API 在需要时访问剪裁信息。

最佳做法

使用刘海屏时，请考虑以下事项：

• 请注意界面中关键元素的放置位置。不要让剪裁区域遮盖任何重要的文本、控件或其他信息。
• 请勿将任何需要精细轻触识别的交互式元素放置或延伸到刘海区域。刘海区域中的触控灵敏度可能较低。
• 遵循边到边指南时，切口信息包含在 safeDrawing / safeContent 内嵌中。
• 如有可能，请使用 Modifier.windowInsetsPadding(WindowInsets.safeDrawing) 确定要对您的内容应用的适当内边距。避免对状态栏高度进行硬编码，因为这样做可能会导致内容重叠或被切断。

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

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

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

   

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