窗口边衬区简介

Android 平台负责绘制系统界面，例如状态栏和导航栏。无论用户使用的是哪个应用，系统都会显示此系统界面。

WindowInsets 提供有关系统界面的信息，以确保您的应用在正确区域中绘制，并且您的界面不会被系统界面遮挡。

在 Android 14（API 级别 34）及更低版本中，默认情况下，应用的界面不会在系统栏和显示屏刘海下方绘制。

在 Android 15（API 级别 35）及更高版本中，当您的应用以 SDK 35 为目标平台时，应用会在系统栏和显示屏刘海下方绘制。这样可以带来更顺畅的用户体验，并让应用充分利用可用的窗口空间。

在系统界面后面显示内容称为“全屏显示”。 在本页中，您将了解不同类型的边衬区、如何全屏显示，以及如何使用边衬区 API 为界面添加动画效果，并确保应用的内容不会被系统界面元素遮挡。

边衬区基础知识

当应用全屏显示时，您需要确保重要内容和互动不会被系统界面遮挡。例如，如果某个按钮放置在导航栏后面，用户可能无法点击该按钮。

系统界面的大小以及放置位置的相关信息使用边衬区指定。

系统界面的每个部分都有一个对应的边衬区类型，用于描述其大小和放置位置。例如，状态栏边衬区提供状态栏的大小和位置，而导航栏边衬区提供导航栏的大小和位置。每种类型的边衬区都包含四个像素尺寸：上、左、右和下。这些尺寸指定系统界面从应用窗口的相应边框延伸的距离。因此，为了避免与该类型的系统界面重叠，应用界面必须按该量进行边衬。

这些内置的 Android 边衬区类型可通过 WindowInsets 获取：

WindowInsets.statusBars	描述状态栏的边衬区。这些是顶部系统界面栏，包含通知图标和其他指示器。
WindowInsets.statusBarsIgnoringVisibility	状态栏可见时的状态栏边衬区。如果状态栏被隐藏（由于进入沉浸式全屏模式），则主要状态栏边衬区将为空，但这些边衬区将不为空。
WindowInsets.navigationBars	描述导航栏的边衬区。这些是设备左侧、右侧或底部的系统界面栏，用于描述任务栏或导航图标。这些边衬区可以在运行时根据用户的首选导航方法以及与任务栏的互动而发生变化。
WindowInsets.navigationBarsIgnoringVisibility	导航栏可见时的导航栏边衬区。如果导航栏被隐藏（由于进入沉浸式全屏模式），则主要导航栏边衬区将为空，但这些边衬区将不为空。
WindowInsets.captionBar	描述系统界面窗口装饰的边衬区（如果位于自由窗口中），例如顶部标题栏。
WindowInsets.captionBarIgnoringVisibility	标题栏可见时的标题栏边衬区。如果标题栏被隐藏，则主要标题栏边衬区将为空，但这些边衬区将不为空。
WindowInsets.systemBars	系统栏边衬区的并集，包括状态栏、导航栏和标题栏。
WindowInsets.systemBarsIgnoringVisibility	系统栏可见时的系统栏边衬区。如果系统栏被隐藏（由于进入沉浸式全屏模式），则主要系统栏边衬区将为空，但这些边衬区将不为空。
WindowInsets.ime	描述软件键盘占用的底部空间量的边衬区。
WindowInsets.imeAnimationSource	描述软件键盘在当前键盘动画之前占用的空间量的边衬区。
WindowInsets.imeAnimationTarget	描述软件键盘在当前键盘动画之后将占用的空间量的边衬区。
WindowInsets.tappableElement	一种边衬区，用于描述有关导航界面的更详细信息，给出系统（而不是应用）将处理“点按”操作的空间量。对于使用手势导航的透明导航栏，某些应用元素可以通过系统导航界面点按。
WindowInsets.tappableElementIgnoringVisibility	可点按元素可见时的可点按元素边衬区。如果可点按元素被隐藏（由于进入沉浸式全屏模式），则主要可点按元素边衬区将为空，但这些边衬区将不为空。
WindowInsets.systemGestures	表示系统将拦截手势以进行导航的边衬区量的边衬区。应用可以使用 Modifier.systemGestureExclusion 手动指定处理有限数量的这些手势。
WindowInsets.mandatorySystemGestures	系统手势的子集，这些手势将始终由系统处理，并且无法使用 Modifier.systemGestureExclusion 停用。
WindowInsets.displayCutout	表示避免与刘海屏（凹口或针孔）重叠所需的间距量的边衬区。
WindowInsets.waterfall	表示瀑布式显示屏的弯曲区域的边衬区。瀑布式显示屏在屏幕边缘具有弯曲区域，屏幕开始沿设备侧面环绕。

这些类型由三种“安全”边衬区类型进行汇总，以确保内容不会被遮挡：

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

这些“安全”边衬区类型根据底层平台边衬区以不同的方式保护内容：

• 使用 WindowInsets.safeDrawing 保护不应在任何系统界面下方绘制的内容 。这是边衬区最常见的用法：防止绘制被系统界面（部分或完全）遮挡的内容。
• 使用 WindowInsets.safeGestures 保护具有手势的内容。这样可以避免系统手势与应用手势（例如底部工作表、轮播界面或游戏中的手势）冲突。
• 将 WindowInsets.safeContent 用作 WindowInsets.safeDrawing 和 WindowInsets.safeGestures 的组合，以确保 内容没有视觉重叠，也没有手势重叠。

为你推荐

• 注意：当 JavaScript 处于关闭状态时，系统会显示链接文字
• Material 组件和布局
• 将 CoordinatorLayout 迁移到 Compose
• 其他注意事项