画中画

画中画 (PiP) 是一种多窗口模式，适用于播放全屏视频的 activity。它允许用户在主屏幕上在应用之间切换或浏览内容时，在一个固定在屏幕角落的小窗口中观看视频。

图 1：即使不在您的应用中，用户也能继续观看视频

要点

  • 确保当 activity 处于画中画模式时，UI 元素会被隐藏，并且视频播放会继续。
  • 对非视频内容禁用无缝大小调整。
  • 界面最小化的视频播放 activity 可提供最佳用户体验。
  • 除了视频内容，避免显示任何其他内容。

为您的应用添加画中画支持

默认情况下，系统不会自动为应用提供画中画支持，需要声明才能支持此功能。

画中画窗口会出现在屏幕的最顶层，并位于系统选择的某个角落。

控件

默认情况下，Android 提供用于关闭窗口、将其展开回全屏、设置和媒体播放的画中画控件。您的应用可以添加自定义操作和适当的图标资源，以便用户与画中画内容进行互动。

用户可以通过在移动设备上轻触画中画窗口或从电视遥控器中选择菜单来显示这些控件。如果应用具有活跃的媒体会话，还会显示播放、暂停、下一首和上一首的控件。请阅读有关如何添加这些控件的信息。

在画中画模式下，您的 activity 会显示在一个小窗口中。在此模式下，用户无法与您应用的其他 UI 元素互动，并且画中画窗口中较小的 UI 元素的细节可能难以看清。

Default PiP controls

默认画中画控件。

Example of custom PiP controls

自定义画中画控件示例。

用法

允许用户不仅在您的应用内继续观看视频，还能在他们的设备上继续观看。您的应用可以控制当前 activity 何时进入画中画模式——这可以是离开当前视图或向上滑动以返回主屏幕等交互。

以下是可能的操作示例

  • 当用户轻触主页按钮或向上滑动以返回主屏幕时，activity 可以进入画中画模式。Google 地图就是这样在用户同时运行另一个 activity 时继续显示路线的。

    图 4：画中画用于继续导航体验

  • 当用户从视频导航回来浏览其他内容时，您的应用可以将视频移入画中画模式。

  • 当用户观看内容剧集的结尾时，您的应用可以将视频切换到画中画模式。主屏幕会显示有关该系列下一集的宣传或摘要信息。

  • 您的应用可以提供一种方式，让用户在观看视频的同时排队等待额外内容。视频在画中画模式下继续播放，而主屏幕则显示内容选择 activity。

使用一种补充观看体验而不会造成中断的交互模式。例如，如果视频处于内容剧集的末尾，则在离开主屏幕时进入画中画模式将需要额外的用户操作才能返回并停止播放或操作小控件。

在您的应用中，用户在主屏幕上浏览内容时，可能会选择新的视频，而视频播放 activity 处于画中画模式。请在现有的播放 activity 中以全屏模式播放新视频，而不是启动可能让用户感到困惑的新 activity。

交互模式

用户可以将画中画窗口拖动到其他位置。

轻触窗口以显示全屏切换、关闭按钮、设置按钮以及您的应用提供的自定义操作（例如播放控件）。

图 5：默认画中画控件

双击窗口可在当前画中画尺寸与最大或最小画中画尺寸之间切换，例如，双击最大化的窗口会将其最小化，反之亦然。

图 6：通过双击在画中画最小和最大尺寸之间切换

通过将窗口拖动到左边缘或右边缘来隐藏窗口。要取消隐藏窗口，可以轻触隐藏窗口的可见部分或将其拖出。

图 7：画中画隐藏

使用双指张合手势调整画中画窗口的大小。

向下滑动画中画以移除窗口。

图 8：向下滑动

过渡

平滑进入画中画动画

用户触发画中画模式会导致当前 activity 从全屏缩小到一个小窗口，该窗口会继续显示内容而不会覆盖任何 UI。

Android 12 为全屏和画中画窗口之间的动画过渡添加了显著的视觉改进。我们强烈建议您实施所有适用的更改；一旦完成，这些更改将自动适配折叠屏和平板电脑等大屏幕，无需任何额外工作。

如果您的应用未包含这些适用的更新，画中画过渡仍然可用，但动画效果会欠佳。例如，从全屏模式过渡到画中画模式时，画中画窗口可能会在过渡期间消失，然后在过渡完成后再次出现。

从 Android 12 开始，PictureInPictureParams.Builder.setAutoEnterEnabled(true) 标志提供了更平滑的动画，用于通过手势导航过渡到画中画模式中的视频内容——例如，从全屏模式向上滑动以返回主屏幕时。如果您的应用属于 ENTERTAINMENT、COMMUNICATION 或 VIDEO_PLAYER 应用类别，我们建议您使用此功能。

如果您的应用未包含此更改，则使用手势导航的画中画过渡仍然可用，但动画效果会欠佳。视频 1 显示了一个示例：窗口缩小到应用图标并消失，然后在过渡完成后再次出现。

当画中画未正确实现 setAutoEnterEnabled 时，过渡体验欠佳

在应用中添加 setAutoEnterEnabled 后，过渡体验更流畅。

我们在 Android 8.0 中引入画中画时，sourceRectHint 指示了进入画中画后 activity 的可见区域，例如视频播放器中的视频视图边界。从 Android 12 开始，操作系统使用 sourceRectHint 来实现进入和退出画中画模式时更平滑的动画。

如果您的应用未提供正确的 sourceRectHint，画中画过渡仍然可用，但动画效果会欠佳。例如，视频 3 显示了从全屏模式过渡到画中画模式的一个欠佳示例：全屏窗口缩小到画中画窗口后，它会被黑色叠加层覆盖，然后才再次显示视频。

视频 3：当画中画未正确实现 sourceRectHint 时，过渡体验欠佳

要查看当 sourceRectHint 正确实现时画中画动画外观的示例，请参阅上一节中的视频 2。

请参阅 Android Kotlin 画中画示例，作为实现流畅过渡体验的参考。

如需了解更多关于实现画中画的信息，请参阅画中画开发者文档。

此页面上的内容和代码示例受内容许可中所述的许可条款约束。Java 和 OpenJDK 是 Oracle 和/或其关联公司的商标或注册商标。