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

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

以下示例展示了如何实现用于进入 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。此外,触发该操作时,画中画模式的宽高比会设置为与正在播放的视频的宽高比一致。

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

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

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

保持清晰 API

在某些情况下,PiP 应用可能会叠加在全屏应用内的重要界面组件上。为缓解此问题,系统提供了一些保持清晰 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 的一部分,而不需要清除整个 ViewsetPreferKeepClearRects() 可用于 指定不应叠加的 View 区域。不使用 View(例如 Flutter、Jetpack Compose 和 WebView)可能具有 需要保留区域的子部分。此 API 可用于这些情况。

使用类型

您的应用必须声明元数据值属性,即 与主要类型对应的 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" />