Compose 中的刘海屏

刘海屏是某些设备上延伸至显示屏的一个区域 。这样既能实现无边框体验，又能为所有人 重要传感器。

图 1. 竖屏模式下的刘海屏示例

<ph type="x-smartling-placeholder">

</ph>

图 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 内边距， 也可以在不需要时忽略它

或者，您可以采用与视图剪贴画相同的设置 请参阅文档中的说明， 将 activity 主题 android:windowLayoutInDisplayCutoutMode 关联到另一个 activity 主题 选项，或使用 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. 使用开发者选项测试内容的呈现方式。