在电视上同时处理多项任务

Android 14（API 级别 34）引入了对 画中画 (PiP) API 支持多任务处理。使用画中画功能 支持是在 Android 8.0（API 级别 26）中引入的， 在 Android TV 上受支持，在 Android 之前的 Google TV 上完全不受支持 13.适用于电视的多任务处理功能使用画中画模式，让两个单独的应用能够在屏幕上共存：一个应用以全屏模式运行，另一个应用以画中画模式运行。对这两种模式下运行的应用有不同的要求。

默认行为是画中画应用叠加在全屏应用上。这是 与标准的 Android 画中画行为大致相同。

请注意，在集成多任务处理时，您的应用必须声明其 使用类型 电视应用质量指南。

在画中画模式下运行应用

对于搭载 Android 14（API 级别 34）或更高版本的电视设备，请在画中画模式下运行应用 模式（通过调用 enterPictureInPictureMode()）。搭载较低 Android 版本的 TV 设备不支持 PiP 模式。

注意 ：对于 API 级别，有一个已废弃的 enterPictureInPictureMode() 方法 26 及更早版本，不使用 PictureInPictureParams.Builder。避免使用 因为它在电视设备上不受支持。

以下示例展示了如何实现用于进入 PIP 模式的按钮的逻辑：

Kotlin

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    pictureInPictureButton.visibility =
        if (requireActivity().packageManager.hasSystemFeature(FEATURE_PICTURE_IN_PICTURE)) {
            pictureInPictureButton.setOnClickListener {
                val aspectRatio = Rational(view.width, view.height)
                val params = PictureInPictureParams.Builder()
                    .setAspectRatio(aspectRatio)
                    .build()
                val result = requireActivity().enterPictureInPictureMode(params)
            }
            View.VISIBLE
        } else {
            View.GONE
        }
}

Java

@Override
public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);
    if (requireActivity().getPackageManager().hasSystemFeature(FEATURE_PICTURE_IN_PICTURE)) {
        pictureInPictureButton.setVisibility(View.VISIBLE);
        pictureInPictureButton.setOnClickListener(v -> {
            Rational aspectRatio = new Rational(view.getWidth(), view.getHeight());
            PictureInPictureParams params = new PictureInPictureParams.Builder()
                    .setAspectRatio(aspectRatio)
                    .setTitle("My Streaming App")
                    .setSubtitle("My On-Demand Content")
                    .build();
            Boolean result = requireActivity().enterPictureInPictureMode(params);
        });
    } else {
        pictureInPictureButton.setVisibility(View.GONE);
    }
}

仅当设备具有系统功能时，才会添加该操作 FEATURE_PICTURE_IN_PICTURE。此外，触发该操作时，画中画模式的宽高比会设置为与正在播放的视频的宽高比一致。

请务必添加标题和副标题，以便向用户提供信息 这个画中画通常的用途是什么

注意：进入画中画模式需要用户在应用中执行明确且有意的操作。如需了解详情，请参阅 TV 应用质量指南。

与在画中画模式下运行的应用共存

当您的应用以全屏应用运行时，可能需要适应以画中画模式运行的其他应用。

保持清晰 API

在某些情况下，PiP 应用可能会叠加在全屏应用内的重要界面组件上。为缓解此问题，系统提供了一些保持清晰 API，应用可以使用这些 API 来识别不应叠加的重要界面组件。系统 尝试遵循请求，以避免通过 重新放置画中画窗口

注意 ：如果界面组件过多，系统可能不会遵从这些请求 广告会被标记为不清晰，或者会占据大部分屏幕。 使用这些 API 时请注意这一点。

如需指定不应叠加视图，请在 XML 布局中使用 preferKeepClear，如以下示例所示：

<TextView
    android:id="@+id/important_text"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:preferKeepClear="true"
    android:text="@string/app_name"/>

您还可以使用 setPreferKeepClear() 通过编程方式执行此操作：

Kotlin

private lateinit var binding: MyLayoutBinding

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

    binding = MyLayoutBinding.inflate(layoutInflater)
    setContentView(binding.root)
    binding.importantText.isPreferKeepClear = true
}

Java

private MyLayoutBinding binding;

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    binding = MyLayoutBinding.inflate(getLayoutInflater());
    setContentView(binding.getRoot());
    binding.importantText.setPreferKeepClear(true);
}

有时，您可能只需要清除 View 的一部分，而不需要清除整个 View。setPreferKeepClearRects() 可用于 指定不应叠加的 View 区域。不使用 View（例如 Flutter、Jetpack Compose 和 WebView）可能具有 需要保留区域的子部分。此 API 可用于这些情况。

注意：如果您将 setPreferKeepClear() 设为 true，整个 View 将被标记为保持清晰，并且系统会忽略使用 setPreferKeepClearRects() 指定的所有区域。

使用类型

您的应用必须声明元数据值属性，即 与主要类型对应的 com.google.android.tv.pip.category 或 以及画中画模式的使用类型任何设置<activity> android:supportsPictureInPicture="true" 应使用 相关的值。

不属于上述任何类别的使用情况类型，尤其是任何 不得在电视上的画中画模式下播放媒体内容。

值	说明
“communication”	通信用例，例如视频通话或语音通话。
“smartHome”	智能家居集成，例如联网门铃或婴儿监视器。
“health”	健康类用例，例如健身追踪或健康监控。
“ticker”	滚动式用例，例如实时体育赛事比分或新闻和股票行情。

多个值之间用竖线 (|) 分隔。例如：

<meta-data android:name="com.google.android.tv.pip.category" android:value="smartHome|health" />