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 的电视设备不支持画中画模式。
以下示例展示了如何实现用于进入画中画模式的按钮的逻辑:
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 清晰明确
在某些情况下,画中画应用可能会在全屏应用中叠加重要的界面组件。为了缓解这种情况,应用可以使用一些始终清晰的 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 可用于这些情况。
使用类型
您的应用必须声明 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" />