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

播放媒體的應用程式需要使用者介面元件，才能顯示媒體及控製播放。Media3 程式庫包含 UI 模組，內含多種 UI 元件。如要依附 UI 模組，請新增下列依附元件：

Kotlin

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

Groovy

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

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

PlayerView 的 setPlayer 方法可附加和卸離 (透過傳遞 null) 玩家執行個體。

PlayerView

PlayerView 可用於播放影片和音訊。它會在播放影片時轉譯影片和字幕，並能在音訊檔案中顯示作為中繼資料的圖片。您可以在版面配置檔案中加入這個模組，就像任何其他 UI 元件一樣。舉例來說，PlayerView 可包含在以下 XML 中：

<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。與 TextureView 相比，SurfaceView 影片播放有許多好處：

  • 許多裝置上的耗電量都會大幅降低。
  • 更準確的影格時間，讓影片播放更順暢。
  • 支援在支援的裝置上產生更高畫質的 HDR 視訊輸出效果。
  • 播放受 DRM 保護的內容時，支援安全輸出。
  • 能夠在 Android TV 裝置 (擁有 UI 層) 上，以完整解析度顯示影片內容。

因此，請盡可能優先使用 SurfaceView，而非 TextureView。只有在 SurfaceView 不符合需求時，才應使用 TextureView。例如，在 Android 7.0 (API 級別 24) 以下版本之前，必須使用流暢的動畫或捲動影片介面的情況，如以下附註所述。在這種情況下，建議只有在 SDK_INT 低於 24 (Android 7.0) 和 SurfaceView 時使用 TextureView。

Android TV 的 D-Pad 導覽

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 }
)

覆寫可繪項目

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

進一步自訂

如果需要進行上述自訂操作以外的自訂功能，應用程式開發人員應會實作自己的 UI 元件，而非使用 Media3 UI 模組提供的元件。