Android异形屏适配（官方方案）

最新推荐文章于 2025-01-15 15:15:39 发布

精装机械师

最新推荐文章于 2025-01-15 15:15:39 发布

阅读量1.1w

点赞数 9

分类专栏： Android开发 # Android设备兼容文章标签：异形屏安卓刘海屏水滴屏

本文链接：https://blog.csdn.net/yingaizhu/article/details/112894902

版权

Android开发同时被 2 个专栏收录

32 篇文章

订阅专栏

Android设备兼容

1 篇文章

订阅专栏

本文详细介绍Android异形屏（如刘海屏、水滴屏、挖孔屏）的官方适配要求与方法，包括如何处理不同场景下的系统状态栏显示问题，以及如何通过API获取并适配异形屏切口区域。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

一、前言

Android的异形屏，包括刘海屏，水滴屏、挖孔屏，起初是iOS设备上的杰作，有吐槽，也有赞美。刚出来不久，国内的各大厂商开始效仿，起初官方并没有API进行适配，一些厂商（例如小米、vivo）自己搞了刘海屏，只能用自己的API进行检测适配，这些就是蛋疼的事，通用的做法就是利用反射调用系统API进行判断，不过这篇文章不介绍这些设备的做法，毕竟从Android 9.0 （API Level 28）开始Android官方也出了刘海屏的适配支持，这里主要将官方的（因为现在国内各大厂商出的设备都是基于新系统，都支持官方API检测和适配）

二、异形屏适配详解

2.1 官方对带异形屏设备的要求

为了确保一致性和应用兼容性，官方对搭载 Android 9 的设备有以下要求：

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

2.2 处理异形屏

2.2.1 不隐藏系统状态栏的情形

如果应用所有界面均不隐藏状态栏，也就是应用不与系统状态栏重叠，那么就无需处理异形屏适配，系统状态栏会自动调整占据了异形切口的位置。如下图：

非全屏状态无需处理异形屏适配

2.2.2 隐藏系统状态栏的情形

如果应用有界面是隐藏系统状态栏的（比如启动页，全屏游戏等），那么就要针对异形屏进行适配。

2.2.2.1 配置应用如何处理异形切口区域

隐藏了系统状态栏，意味着应用的内容将扩充到系统状态栏原有的位置，但是系统提供了控制是否在异形切口区域显示内容的配置，该配置是Window（窗口）级别属性，属性名为 layoutInDisplayCutoutMode。该属性有三个可选值，分别是：

WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT - 这是默认行为。官方说明是在竖屏模式下，内容会呈现到刘海区域中；但在横屏模式下，内容会显示黑边。但是笔者才使用过程中，发现横屏和竖屏都是留黑边，不知道是不是跟系统有关（笔者使用官方模拟器和官方原生系统设备均是留黑边效果）
WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES - 在竖屏模式和横屏模式下，内容都会呈现到刘海区域中。
WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER - 内容从不呈现到刘海区域中。

可以通过了两种方法配置该属性：

在窗口主题样式文件中定义
在主题样式文件中通过 android:windowLayoutInDisplayCutoutMode 定义，示例代码如下：

<style name="Theme.DisplayCutoutDemo" parent="Theme.MaterialComponents.DayNight.DarkActionBar">
    <!-- 其他属性配置 -->
    <item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>
</style>

在窗口代码中定义
在代码中定义，需要在Window（窗口）级别属性中配置，示例代码如下：

window.attributes.apply {
    // Window级别的全屏（这里的代码可以）
    systemUiVisibility =
        View.SYSTEM_UI_FLAG_FULLSCREEN or
                View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN or
                View.SYSTEM_UI_FLAG_LAYOUT_STABLE or
    // 下面两个是隐藏虚拟导航栏
                View.SYSTEM_UI_FLAG_HIDE_NAVIGATION or
                View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION

    // 设置视图内容是否显示到异形切口区域
    if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        // 如果最低版本支持小于28，需要增加判断，防止在低版本系统运行时找不到系统API崩溃
        layoutInDisplayCutoutMode = WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
    }
}

效果

上面的效果中，发现异形切口区域没有黑边，但是也没有达到预想的内容显示在异形切口区域内，不仅如此，下面导航栏区域也是白边。这是因为 Android 系统不允许视图内容跟系状态栏和导航栏区域重叠，要让视图内容强制延伸至系统状态栏和导航栏区域，可以通过配置视图级别的显示属性参数 systemUiVisibility，代码如下所示：

window.decorView.apply {
    // 视图级全屏
    systemUiVisibility =
        View.SYSTEM_UI_FLAG_FULLSCREEN or
                // 视图内容延伸到状态栏区域
                View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN or
                View.SYSTEM_UI_FLAG_LAYOUT_STABLE or
                // 视图内容延伸到系统导航栏区域
                View.SYSTEM_UI_FLAG_HIDE_NAVIGATION or
                View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
}

效果

2.2.2.2 异形切口区域的视图适配

如果你想将内容扩展到异形切口，如果只是遮挡部分的内容不影响体验（例如启动页图片），可不做处理，但是如果有用户可交互的操作或者文字，必须进行适配。这时，你需要知道异形切口所在的位置和大小，在 Android 9 开始，系统提供了 WindowInsets.getDisplayCutout() 接口获取 DisplayCutout 对象，这时一个描述屏幕中所有切口位置和大小的对象。

如何获取 DisplayCutout 对象
获取 DisplayCutout 对象，首先要获取 WindowInsets 对象。 WindowInsets 对象并没有直接获取方法，只能通过监听或者回调方法获取，下面介绍获取 WindowInsets 对象的两种方法。

在自定义View内部重写 View.onApplyWindowInsets(WindowInsets)方法获取

class CView(context: Context?) : LinearLayout(context) {
    override fun onApplyWindowInsets(insets: WindowInsets?): WindowInsets {
        return super.onApplyWindowInsets(insets)
    }
}

注意事项：如果是重写View.onApplyWindowInsets(WindowInsets)方法获取，请确保 WindowInsets 在之前没有被消耗，没有给 View 的父级或者 View 设置 View.OnApplyWindowInsetsListener 监听。这个大家可以去了解下 WindowInsets 分发相关知识。

通过给 View 设置 View.OnApplyWindowInsetsListener 监听获取

window.decorView.apply {
    if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT_WATCH) {
        // 该方法在 API 20 开始加入，需要做好版本适配
        setOnApplyWindowInsetsListener { v, insets ->
            insets
        }
    }
}

如何获取屏幕切口区域
上面已经介绍了 WindowInsets 对象的获取方法，有了 WindowInsets 对象，我们可以通过 WindowInsets.getDisplayCutout() 获取切口相关信息。在 API Level 28 中，该对象只能支持获取屏幕的安全区域，分别通过 WindowInsets.getSafeInsetBottom()、WindowInsets.getSafeInsetLeft()、WindowInsets.getSafeInsetRight()、WindowInsets.getSafeInsetTop() 获取各边安全间距。在 API Level 29 开始，还支持获取具体的切口位置和大小信息，分别通过 WindowInsets.getBoundingRectBottom()、WindowInsets.getBoundingRectLeft()、WindowInsets.getBoundingRectRight()、WindowInsets.getBoundingRectTop() 获取各边的切口信息，知道切口信息，可以更加精准地控制显示。

实用小知识：这里介绍到了 WindowInsets 对象，从 API 21开始，可以通过这个对象获取状态栏和导航栏的高度，这些接口分别是 WindowInsets.getStableInsetBottom() 、WindowInsets.getStableInsetLeft()、WindowInsets.getStableInsetRight()、WindowInsets.getStableInsetTop()，在API Level 30 开始这几个接口被废弃，使用 WindowInsets.getInsetsIgnoringVisibility (int typeMask) 替代。用这种方法获取的时候，即使状态栏和导航栏处于隐藏状态，也不影响获取。

在这里，我们演示下比较简单的安全区域的适配方法。

if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT_WATCH) {
// 如果最低版本支持小于20，需要增加判断，防止在低版本系统运行时找不到系统API崩溃
setOnApplyWindowInsetsListener { v, insets ->
    if(Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
        insets.displayCutout?.apply {
            textView.apply {
                // 设置padding，防止内容显示到非安全区域
                setPadding(safeInsetLeft, safeInsetTop, safeInsetRight, safeInsetBottom)
            }
        }
    }
    // 不消费，直接返回原始对象
    insets
}

适配前后对比

2.2.3 异形屏适配的最佳做法与注意事项

不要让异形切口区域遮盖任何重要的文本、控件或其他信息。
不要将任何需要精细轻触识别的交互式元素放置或延伸到异形切口区域，异形切口区域中的轻触灵敏度可能要比其他区域低一些。
避免对状态栏高度进行硬编码，否则可能会导致内容重叠或被切断。
如果的应用需要进入全屏模式，使用shortEdges 模式，退出全屏是，使用 never 模式。
在全屏模式下，在使用窗口坐标与屏幕坐标时需要注意，因为在显示黑边的情况下，窗口不会占据整个屏幕。因此根据屏幕原点（屏幕左上角）得到的坐标与根据窗口原点（窗口左上角）得到的坐标不再相同。不过以根据需要使用 View.getLocationOnScreen() 接口将屏幕坐标转换为视图坐标。在处理 MotionEvent 时，应当使用 MotionEvent.getX() 和 MotionEvent.getY() 来避免类似的坐标问题。不要使用 MotionEvent.getRawX() 或 MotionEvent.getRawY()。