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

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

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

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

在画中画模式下运行应用

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

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

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

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 清晰明确

在某些情况下，画中画应用可能会在全屏应用中叠加重要的界面组件。为了缓解这种情况，应用可以使用一些始终清晰的 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，而只需要保留其中的一部分。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" />