在应用中全屏显示内容

试用 Compose 方式

Jetpack Compose 是推荐在 Android 设备上使用的界面工具包。了解如何在 Compose 中使用全屏。

Compose 中的全屏功能 →

您可以在系统栏后面绘制内容，让应用“无边框”显示（使用屏幕的整个宽度和高度）。系统栏是状态栏和导航栏。

如需实现无边框布局，您的应用必须执行以下操作：

• 在导航栏后面绘制内容，以实现更具吸引力的现代用户体验。
• 如果对内容和布局有意义（例如在全宽图像的情况下），请在状态栏后绘制。为此，请使用 AppBarLayout 等 API，这些 API 定义了一个固定到屏幕顶部的应用栏。

图 1.无边框布局中的系统栏。

如需在应用中实现无边框布局，请执行以下步骤：

1. 启用无边框显示屏。
2. 处理任何视觉重叠。

图 2.在状态栏后面显示图像的应用示例。

启用无边框显示屏。

您可以通过在 Activity 的 onCreate 中调用 enableEdgeToEdge，在应用中启用全屏显示屏。应在 setContentView 之前调用它。

Kotlin

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

Java

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
    EdgeToEdge.enable(this);
    super.onCreate(savedInstanceState);
    ...
  }

默认情况下，enableEdgeToEdge 会使系统栏处于透明状态，但在“三按钮”导航模式下除外，在该模式下，状态栏会使用半透明的纱罩。系统图标和纱罩的颜色会根据系统的浅色或深色主题进行调整。

enableEdgeToEdge 方法会自动声明应用应无边框布局，并调整系统栏的颜色。如果出于任何原因需要这样做，请参阅“手动设置无边框显示屏”。

使用边衬区处理重叠

启用全屏显示后，应用的某些视图可能会在系统栏后面绘制，如图 3 所示。

您可以通过回应边衬区来解决重叠问题，边衬区指定屏幕的哪些部分与系统界面（例如导航栏或状态栏）相交。相交可能意味着在内容上方显示，但也可以将系统手势告知您的应用。

适用于全屏显示应用的边衬区类型包括：

• 系统栏边衬区：最适合可点按且不得被系统栏遮挡的视图。

• 系统手势边衬区：适用于系统使用的手势导航区域，这些区域的优先级高于应用。

系统栏边衬区

系统栏边衬区是最常用的边衬区类型。它们代表系统界面在应用上方的 Z 轴中显示的区域。它们最适合用于移动或填充应用中可点按且不得被系统栏遮挡的视图。

例如，图 3 中的悬浮操作按钮 (FAB) 会被导航栏部分遮挡：

图 3. 在无边框布局中，导航栏与 FAB 重叠。

为避免在手势模式或按钮模式下出现这种视觉重叠，您可以使用 getInsets(int) 和 WindowInsetsCompat.Type.systemBars() 来增加视图的外边距。

以下代码示例展示了如何实现系统栏边衬区：

Kotlin

ViewCompat.setOnApplyWindowInsetsListener(fab) { v, windowInsets ->
  val insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemBars())
  // Apply the insets as a margin to the view. This solution sets
  // only the bottom, left, and right dimensions, but you can apply whichever
  // insets are appropriate to your layout. You can also update the view padding
  // if that's more appropriate.
  v.updateLayoutParams<MarginLayoutParams> {
      leftMargin = insets.left,
      bottomMargin = insets.bottom,
      rightMargin = insets.right,
  }

  // Return CONSUMED if you don't want want the window insets to keep passing
  // down to descendant views.
  WindowInsetsCompat.CONSUMED
}

Java

ViewCompat.setOnApplyWindowInsetsListener(fab, (v, windowInsets) -> {
  Insets insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemBars());
  // Apply the insets as a margin to the view. This solution sets only the
  // bottom, left, and right dimensions, but you can apply whichever insets are
  // appropriate to your layout. You can also update the view padding if that's
  // more appropriate.
  MarginLayoutParams mlp = (MarginLayoutParams) v.getLayoutParams();
  mlp.leftMargin = insets.left;
  mlp.bottomMargin = insets.bottom;
  mlp.rightMargin = insets.right;
  v.setLayoutParams(mlp);

  // Return CONSUMED if you don't want want the window insets to keep passing
  // down to descendant views.
    return WindowInsetsCompat.CONSUMED;
});

如果将此解决方案应用于图 3 中所示的示例，将导致按钮模式下没有视觉重叠，如图 4 所示：

图 4. 解决了按钮模式下的视觉重叠问题。

这同样适用于手势导航模式，如图 5 所示：

图 5. 解决了手势导航模式下的视觉重叠问题。

系统手势边衬区

系统手势边衬区表示窗口区域，在这些区域中，系统手势优先于应用。在图 6 中，这些区域显示为橙色：

图 6. 系统手势边衬区。

与系统栏边衬区一样，您可以将 getInsets(int) 与 WindowInsetsCompat.Type.systemGestures() 结合使用，避免系统手势边衬区重叠。

使用这些边衬区可将可滑动视图移出边缘或向边缘移动。常见用例包括底部动作条、游戏中滑动，以及使用 ViewPager2 实现的轮播界面。

在 Android 10 或更高版本中，系统手势边衬区包含主屏幕手势的底部边衬区，以及用于返回手势的左侧和右侧边衬区：

图 7. 系统手势边衬区测量结果。

以下代码示例展示了如何实现系统手势边衬区：

Kotlin

ViewCompat.setOnApplyWindowInsetsListener(view) { view, windowInsets ->
    val insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemGestures())
    // Apply the insets as padding to the view. Here, set all the dimensions
    // as appropriate to your layout. You can also update the view's margin if
    // more appropriate.
    view.updatePadding(insets.left, insets.top, insets.right, insets.bottom)

    // Return CONSUMED if you don't want the window insets to keep passing down
    // to descendant views.
    WindowInsetsCompat.CONSUMED
}

Java

ViewCompat.setOnApplyWindowInsetsListener(view, (v, windowInsets) -> {
    Insets insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemGestures());
    // Apply the insets as padding to the view. Here, set all the dimensions
    // as appropriate to your layout. You can also update the view's margin if
    // more appropriate.
    view.setPadding(insets.left, insets.top, insets.right, insets.bottom);

    // Return CONSUMED if you don't want the window insets to keep passing down
    // to descendant views.
    return WindowInsetsCompat.CONSUMED;
});

沉浸模式

有些内容在全屏模式下效果最佳，可以为用户带来更身临其境的体验。您可以使用 WindowInsetsController 和 WindowInsetsControllerCompat 库在沉浸模式下隐藏系统栏：

Kotlin

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

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

// Show the system bars.
windowInsetsController.show(Type.systemBars())

Java

Window window = getWindow();
WindowInsetsControllerCompat windowInsetsController =
      WindowCompat.getInsetsController(window, window.getDecorView());
if (windowInsetsController == null) {
    return;
  }
// Hide the system bars.
windowInsetsController.hide(WindowInsetsCompat.Type.systemBars());

// Show the system bars.
windowInsetsController.show(WindowInsetsCompat.Type.systemBars());

如需详细了解如何实现此功能，请参阅隐藏系统栏以实现沉浸模式。

其他资源

如需详细了解 WindowInsets、手势导航以及边衬区的工作原理，请参阅以下参考文档：

• WindowInsets - 布局的监听器
• 手势导航：边衬区
• 边衬区在 Android 上的工作原理