窗口边衬区简介

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

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

图 1. 采用无边框显示，在系统栏后面绘制内容。

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

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

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

重要提示： 在 Android 15 及更高版本上，一旦应用以 SDK 35 为目标平台，系统就会强制采用无边框画面。如果您的应用尚未采用边到边设计，则应用的部分内容可能会被隐藏，您必须处理边衬区。根据应用的不同，这项工作可能重要，也可能不重要。Material 3 Scaffold 组件可以减少为兼容 Android 15 边到边强制执行而需要完成的工作。请参阅创建 Scaffold 组件以将界面组合在一起。

边衬区基础知识

当应用进入全面屏模式时，您需要确保重要内容和互动不会被系统界面遮挡。例如，如果按钮位于导航栏后面，用户可能无法点击它。

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

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

这些内置 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 的组合，以确保内容没有视觉重叠和手势重叠。