支持刘海屏

刘海屏是指某些设备显示屏上的一个区域延伸到显示面，这样既能为用户提供全面屏体验，又能为设备正面的重要传感器留出空间。Android 在搭载 Android 9（API 级别 28）及更高版本的设备上正式支持刘海屏。请注意，设备制造商也可以选择在搭载 Android 8.1 或更低版本的设备上支持刘海屏。

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

在带刘海屏的设备上有什么要求

为了确保一致性和应用兼容性，搭载 Android 9 的设备必须确保以下刘海行为：

一条边缘最多只能包含一个刘海。
一台设备不能有两个以上的刘海。
设备的两条较长边缘上不能有刘海。
在未设置特殊标志的竖屏模式下，状态栏的高度必须至少与刘海的高度持平。
默认情况下，在全屏模式或横屏模式下，整个刘海区域必须显示黑边。

选择您的应用如何处理刘海区域

如果不希望您的内容与刘海区域重叠，请确保您的内容不与状态栏和导航栏重叠，这样做一般就足够了。如果您要将内容呈现到刘海区域中，则可以使用 WindowInsets.getDisplayCutout() 来检索 DisplayCutout 对象，该对象包含每个刘海区域的安全边衬区和边界框。您可以使用这些 API 来检查您的内容是否与刘海区域重叠，以便根据需要重新放置。

注意：要在多个 API 级别管理刘海实现，您还可以使用 AndroidX 库（可通过 SDK 管理器获得）中的 DisplayCutoutCompat。

Android 还允许您控制是否在刘海区域内显示内容。窗口布局属性 layoutInDisplayCutoutMode 控制您的内容如何呈现在刘海区域中。您可以将 layoutInDisplayCutoutMode 设为以下某个值：

LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT - 这是默认行为，如上所述。在竖屏模式下，内容会呈现到刘海区域中；但在横屏模式下，内容会显示黑边。
LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES - 在竖屏模式和横屏模式下，内容都会呈现到刘海区域中。
LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER - 内容从不呈现到刘海区域中。

您可以通过编程或在 Activity 中设置样式来设置刘海模式。以下示例定义了一种样式，您可以使用它将 LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES 属性应用到 Activity。

    <style name="ActivityTheme">
      <item name="android:windowLayoutInDisplayCutoutMode">
        shortEdges <!-- default, shortEdges, never -->
      </item>
    </style>

下面几部分更详细地介绍了不同的刘海模式。

默认行为

默认情况下，在未设置特殊标志的竖屏模式下，在带刘海屏的设备上，状态栏的大小会调整为至少与刘海一样高，而您的内容会显示在下方区域。在横屏模式或全屏模式下，您的应用窗口会显示黑边，因此您的任何内容都不会显示在刘海区域中。

将内容呈现在短边刘海区域中

对于某些内容（如视频、照片、地图和游戏），呈现在刘海区域中是一种很好的方法，这样能够为用户提供沉浸感更强的全面屏体验。如果设置了 LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES，则在竖屏模式和横屏模式下，内容都会延伸到显示屏的短边上的刘海区域，而不管系统栏处于隐藏还是可见状态。请注意，窗口无法延伸到屏幕的长边上的刘海区域。使用此模式时，请确保没有重要内容与刘海区域重叠。

请注意，Android 可能不允许内容视图与系统栏重叠。要替换此行为并强制内容延伸到刘海区域，请通过 View.setSystemUiVisibility(int) 方法将以下任一标志应用于视图可见性：

SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
SYSTEM_UI_FLAG_LAYOUT_STABLE

下面是一些 LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES 示例：

请注意，边角处的刘海可等同于在短边上，因此适用同样的行为：

从不将内容呈现在刘海区域中

如果设置了 LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER，则不允许窗口与刘海区域重叠。

此模式应该用于暂时设置 View.SYSTEM_UI_FLAG_FULLSCREEN 或 View.SYSTEM_UI_FLAG_HIDE_NAVIGATION 的窗口，以避免在设置或清除了该标志时执行另一种窗口布局。

请查看下面的 LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER 示例：

特殊模式

某些搭载 Android 8.1（API 级别 27）或更低版本的设备支持一种特殊模式，可让用户将显示黑边的全屏或横屏应用延伸到刘海区域。此模式通常使用导航栏中的切换开关来控制，在延伸屏幕之前会显示一个对话框，要求用户进行确认。