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

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 模式。

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

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
        }
}

@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 通常用途的信息。

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

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

保持清晰 API

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

如需指定不应叠加视图，请在 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() 通过编程方式执行此操作：

private lateinit var binding: MyLayoutBinding

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

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

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 可用于这些情况。

使用类型

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

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

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

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