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

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

默认行为是画中画应用叠加在全屏应用上。这与标准的 Android 画中画行为非常相似。

请注意，集成多任务功能时，您的应用必须根据 TV 应用质量指南声明其使用情形。

在画中画模式下运行应用

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

注意 ：API 级别 26 及更低级别有一个已废弃的 enterPictureInPictureMode() 方法，该方法不使用 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 时，才会添加该操作。此外，触发该操作时，画中画模式的宽高比会设置为与正在播放的视频的宽高比一致。

请务必添加标题和副标题，以便向用户说明此 PIP 的常用用途。

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

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

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

保持清晰 API

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

注意 ：如果有太多的界面组件被标记为“保持清晰”，或者这些组件占据了屏幕的大部分区域，系统可能不会执行这些请求。使用这些 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 的元数据值属性，该属性应与画中画模式的主要用途类型或用途类型相对应。任何设置了 android:supportsPictureInPicture="true" 的 <activity> 都应使用下表中的相关值声明此属性。

电视上的画中画模式不允许使用不属于上述任何类别的使用情形，尤其是任何媒体内容的播放。

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

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

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