電視上的多工處理功能

Android 14 (API 級別 34) 為子母畫面 (PiP) API 導入了一些強化功能，以實現多工處理。雖然 Android 8.0 (API 級別 26) 已導入子母畫面功能，但 Android TV 並未廣泛支援該功能，且在 Android 13 之前的 Google TV 也完全不支援。電視的多工處理功能會使用子母畫面模式，讓兩個不同的應用程式在畫面上同時運作：一個應用程式以全螢幕執行，而另一個在子母畫面模式下執行。以這兩種模式執行的應用程式各有不同的要求。

預設行為是子母畫面應用程式會重疊在全螢幕應用程式上。這與標準的 Android 子母畫面行為相同。

請注意，整合多工處理功能時，應用程式必須根據 TV 應用程式品質指南宣告使用類型。

在子母畫面模式下執行應用程式

如果是搭載 Android 14 (API 級別 34) 以上版本的電視裝置，請呼叫 enterPictureInPictureMode()，以子母畫面模式執行應用程式。搭載舊版 Android 的電視裝置不支援子母畫面模式。

注意： 我們已針對 API 級別 26 及以下級別淘汰一個已淘汰的 enterPictureInPictureMode() 方法，不使用 PictureInPictureParams.Builder。請避免使用，因為 TV 裝置不支援這項功能。

以下範例說明如何實作進入 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 時，才能新增這項操作。此外，動作觸發時，子母畫面模式的顯示比例會設為符合所播放影片的長寬比。

請務必新增標題和子標題，為使用者提供這個子母畫面的一般用途資訊。

注意： 進入子母畫面模式時，需要由使用者在應用程式內明確執行操作。詳情請參閱 TV 應用程式品質指南。

與在子母畫面模式下執行的應用程式並存

當應用程式以全螢幕應用程式執行時，可能需要調整其他在子母畫面模式下執行的應用程式。

安全無虞的 API

在某些情況下，子母畫面應用程式可能會在全螢幕應用程式中重疊重要 UI 元件。為緩解這種情況，應用程式可以使用清楚明確的 API 來識別不應重疊的重要 UI 元件。系統會嘗試重新調整子母畫面視窗的位置，嘗試按照要求，避免遮住這些元件。

注意： 如果有太多 UI 元件標示為保持清晰，或占用畫面較大範圍，系統可能無法處理這些要求。使用這些 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 區域。如果 UI 未原生使用 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" />