设置全屏显示

全屏显示功能可让应用在系统栏（状态栏、标题栏和导航栏）后方绘制界面，从而实现更具沉浸感的用户体验。如果您以搭载 Android 15（API 级别 35）或更高版本的设备为目标平台，则默认情况下强制执行无边框模式。

如需在所有 Android 版本上正确显示从边缘到边缘的内容，请按以下设置步骤操作。如果不执行这些步骤，您的应用可能会在系统栏后面绘制纯色，或者无法使内容与屏幕键盘 (IME) 过渡同步动画。

1. 启用无边框显示

如需在旧版 Android 上启用无边框模式，请在 Activity.onCreate() 方法中调用 enableEdgeToEdge()：

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    ...
}

默认情况下，enableEdgeToEdge() 会使系统栏透明，但在三按钮导航模式下，它会为导航栏应用半透明的遮罩，以提高对比度。系统图标和幕帘的颜色会根据系统的浅色或深色主题进行调整。

2. 配置 windowSoftInputMode

在 activity 的 AndroidManifest.xml 条目中设置 android:windowSoftInputMode="adjustResize"。启用此设置后，您的应用能够接收 IME 边衬区，从而在屏幕键盘显示或隐藏时，您可以使用内边距调整布局。

<!-- In your AndroidManifest.xml file: -->
<activity
  android:name=".ui.MainActivity"
  android:label="@string/app_name"
  android:windowSoftInputMode="adjustResize"
  android:theme="@style/Theme.MyApplication"
  android:exported="true">
  ...
</activity>

3. 使用边衬区处理重叠

启用全面屏模式后，应用的部分内容和界面元素可能会绘制在系统栏后面。为防止关键元素或互动元素被系统栏遮挡或与系统手势重叠，您需要处理边衬区。

边衬区描述了与系统界面或系统手势相交的屏幕部分。对于全屏显示，需要考虑的主要边衬区类型包括：

  • 系统栏边衬区：表示显示系统栏的区域。使用这些常量可避免界面被系统栏遮挡。
  • 刘海屏边衬区：表示设备屏幕上存在物理刘海屏（例如摄像头刘海屏）的区域。

在 Compose 中，您可以使用标尺、内边距修饰符或边衬区尺寸修饰符来处理边衬区。如需详细指导，请参阅窗口边衬区简介。

高级主题

对于更高级的边到边使用情形，请考虑以下事项。

沉浸模式

有些内容（例如视频或地图）适合采用完全沉浸式体验，即隐藏系统栏。您可以使用 WindowInsetsControllerCompat 隐藏系统栏：

val windowInsetsController =
    WindowCompat.getInsetsController(window, window.decorView)

// Hide the system bars.
windowInsetsController.hide(WindowInsetsCompat.Type.systemBars())

// Show the system bars.
windowInsetsController.show(WindowInsetsCompat.Type.systemBars()) For example, use either `Scaffold`,

系统栏颜色和图标

在无边框模式下，应用的背景可能会显示在系统栏后面，因此您可能需要调整系统栏图标颜色，以获得更好的对比度。

如需将状态栏图标更改为浅色或深色，请使用 WindowInsetsControllerCompat：

// Set status bar icons to dark
WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = true

// Set status bar icons to light
WindowCompat.getInsetsController(window, window.decorView)
    .isAppearanceLightStatusBars = false

系统栏保护

虽然 enableEdgeToEdge() 提供了默认的透明或半透明系统栏，但您可能需要自定义此设置。请参阅 Android 系统栏设计指南和全面屏设计指南，以确定何时使用透明栏，何时使用半透明栏。

如需使三按钮导航栏完全透明而非半透明，您可以停用对比度强制执行：

window.isNavigationBarContrastEnforced = false

如需了解详情，请参阅关于系统栏保护。

对话框

如需显示从边缘到边缘的全屏对话框，请在对话框的 onStart() 方法中调用 WindowCompat.enableEdgeToEdge：

class MyAlertDialogFragment : DialogFragment() {
    override fun onStart(){
        super.onStart()
        dialog?.window?.let { WindowCompat.enableEdgeToEdge(it) }
    }
    ...
}
下一页
关于 WindowInsetsRulers