窗口边衬区简介

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

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

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

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

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

边衬区基础知识

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

系统界面的大小以及其放置位置的信息通过内边距指定。

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

您可以通过 WindowInsets 使用以下内置 Android 边衬区类型：

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
• 其他注意事项