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

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

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

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

在画中画模式下运行应用

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

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

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

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 时，请注意这一点。

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

<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 或 以及画中画模式的使用类型任何设置<activity> android:supportsPictureInPicture="true" 应使用 相关的值。

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

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

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

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