電視上的多工處理功能

Android 14 (API 級別 34) 針對子母畫面 (PiP) API 推出了一些強化功能，以便執行多工處理。雖然 Android 8.0 (API 級別 26) 推出了 PiP 支援功能，但 Android TV 並未廣泛支援這項功能，在 Android 13 之前，Google TV 也完全不支援這項功能。電視多工處理功能會使用子母畫面模式，讓兩個不同的應用程式在畫面上並存：一個以全螢幕模式執行，另一個則以子母畫面模式執行。針對在上述任一模式下執行的應用程式，我們有不同的規定。

預設行為是子母畫面應用程式會疊加全螢幕應用程式。這與標準 Android 子母畫面行為非常相似。

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

在 PiP 模式下執行應用程式

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

注意： API 級別 26 以下有一個已淘汰的 enterPictureInPictureMode() 方法，該方法不使用 PictureInPictureParams.Builder。避免使用這項功能，因為電視裝置不支援。

以下範例說明如何實作按鈕的邏輯，以便進入 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 系統功能時，系統才會新增這項操作。此外，當觸發動作時，子母畫面模式的顯示比例會設為與播放的影片顯示比例相符。

請務必加入標題和副標題，向使用者說明這個 PIP 的一般用途。

注意： 使用者必須在應用程式中明確且有意地採取動作，才能進入子母畫面模式。詳情請參閱TV 應用程式品質指南。

與在 PiP 模式下執行的應用程式共存

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

Keep-clear API

在某些情況下，PiP 應用程式可能會在全螢幕應用程式中疊加重要 UI 元件。為避免這種情況發生，應用程式可使用 keep-clear API，識別不應疊加的重要 UI 元件。系統會嘗試回應這類要求，藉由重新調整 PiP 視窗來避免遮蓋這些元件。

注意： 如果太多 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 中不應重疊的區域。不直接使用 View 的 UI (例如 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" />