在應用程式中新增播放控制項

播放媒體的應用程式需要使用者介面元件，用於顯示媒體和控制播放作業。Media3 程式庫包含 UI 模組，其中包含多個 UI 元件。如要依附 UI 模組，請新增下列依附元件：

Kotlin

implementation("androidx.media3:media3-ui:1.5.0")

Groovy

implementation "androidx.media3:media3-ui:1.5.0"

其中最重要的元件是 PlayerView，這是用於媒體播放的檢視畫面。PlayerView 會在播放期間顯示影片、圖片、字幕和專輯封面，以及播放控制項。

PlayerView 提供 setPlayer 方法，可用於附加和解除連結 (透過傳遞 null) 播放器例項。

PlayerView

PlayerView 可用於播放影片、圖片和音訊。在影片播放的情況下，它會算繪影片和字幕，在圖片播放的情況下則會算繪位圖，並可顯示音訊檔案中以中繼資料形式加入的圖片。您可以像其他 UI 元件一樣，將其納入版面配置檔案中。舉例來說，您可以透過以下 XML 加入 PlayerView：

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

以上程式碼片段說明 PlayerView 提供多個屬性。這些屬性可用於自訂檢視畫面的行為，以及外觀和風格。這些屬性大多都有對應的 setter 方法，可用於在執行階段自訂檢視畫面。PlayerView Javadoc 會更詳細列出這些屬性和 setter 方法。

在版面配置檔案中宣告檢視區塊後，即可在活動的 onCreate 方法中查詢：

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

當玩家已完成初始化時，您可以呼叫 setPlayer 將其附加至檢視區塊：

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

選擇表面類型

PlayerView 的 surface_type 屬性可讓您設定用於影片播放的途徑類型。除了 spherical_gl_surface_view (這是球面影片播放的特殊值) 和 video_decoder_gl_surface_view (用於使用擴充功能轉譯器進行影片轉譯) 之外，允許使用的值為 surface_view、texture_view 和 none。如果檢視畫面僅用於音訊播放，請使用 none，避免建立途徑，因為這項操作可能會耗費大量資源。

如果檢視畫面是用於一般影片播放，則應使用 surface_view 或 texture_view。SurfaceView 在影片播放方面比 TextureView 更具優勢：

• 在許多裝置上降低耗電量。
• 更準確的影格時間，可讓影片播放更流暢。
• 在支援的裝置上支援更高品質的 HDR 影片輸出。
• 播放受 DRM 保護的內容時，支援安全輸出功能。
• 在 Android TV 裝置上以 UI 層升級功能，以顯示器的完整解析度算繪影片內容。

因此，請盡可能使用 SurfaceView 而非 TextureView。只有在 SurfaceView 無法滿足需求時，才應使用 TextureView。舉例來說，如果您需要在 Android 7.0 (API 級別 24) 之前的版本中，為影片介面提供流暢的動畫或捲動效果，請參閱下列附註。在這種情況下，建議只在 SDK_INT 小於 24 (Android 7.0) 時使用 TextureView，否則使用 SurfaceView。

注意： 在 Android 7.0 (API 級別 24) 之前，SurfaceView 算繪並未與檢視畫面動畫正確同步。在先前版本中，如果將 SurfaceView 放入捲動容器，或是讓 SurfaceView 受到動畫影響，可能會產生不必要的效果。這些效果包括檢視畫面內容似乎略為落後於應顯示的位置，以及在動畫播放時檢視畫面會變黑。因此，如要在 Android 7.0 以下版本中獲得流暢的動畫或捲動影片，就必須使用 TextureView 而非 SurfaceView。

注意： SurfaceView 途徑的生命週期與檢視畫面可見度相關聯，而 TextureView 途徑的生命週期則與視窗附加和解除附加相關聯。因此，在使用 SurfaceView 的捲動 UI 中，由於輸出途徑會稍晚提供，因此啟動播放作業可能需要較長的時間。自 Android 14 起，PlayerView 會使用 SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) 避免發生這種行為。如果您的應用程式直接使用 SurfaceView (而非 PlayerView)，建議您啟用此模式。在 Android 14 之前，您可以透過在回收時將檢視區塊轉譯至螢幕外，解決途徑遭到銷毀的問題。

注意： 部分 Android TV 裝置會以低於螢幕完整解析度的解析度執行 UI 層，並將其向上調整以供使用者查看。舉例來說，在具備 4K 螢幕的 Android TV 上，UI 層可能會以 1080p 執行。在這種裝置上，必須使用 SurfaceView 以顯示器的完整解析度轉譯內容。您可以使用 Util.getCurrentDisplayModeSize 查詢螢幕的完整解析度 (在目前的顯示模式下)。您可以使用 Android 的 Display.getSize API 查詢 UI 層解析度。

Android TV 上的方向鍵導覽

Android TV 的遙控器設有 D-pad 控制項，可傳送指令，並以按鍵事件傳送至 Activity 的 dispatchKeyEvent(KeyEvent)。以下項目需要委派至播放器檢視畫面：

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

請求播放器檢視畫面的焦點，對於瀏覽播放控制項和略過廣告至關重要。建議您在 Activity 的 onCreate 中要求焦點：

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

如果您在 Android TV 上使用 Compose，就必須讓 AndroidView 可聚焦，並透過適當方式將修飾符參數傳遞至 AndroidView，以委派事件：

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

覆寫可繪項目

注意： 我們無法保證下列章節所述的客製化設定，會在程式庫的未來版本中繼續運作。資源 ID 可能會變更名稱，有些甚至可能會完全刪除。資源 ID 會標示為「private」，即可表示這項資訊。

PlayerView 會使用 PlayerControlView 顯示播放控制項和進度列。PlayerControlView 使用的可繪項目可由應用程式中定義的相同名稱可繪項目覆寫。如要查看可覆寫的控制項可繪項目清單，請參閱 PlayerControlView Javadoc。

進一步自訂

如果需要進行上述以外的客製化設定，我們建議應用程式開發人員實作自己的 UI 元件，而非使用 Media3 的 UI 模組提供的元件。