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

播放媒體的應用程式需要使用者介面元件，才能顯示媒體和控製播放作業。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 可同時播放影片和音訊。在影片播放時算繪影片和字幕，且可顯示包含在音訊檔案中做為中繼資料的圖片。如同任何其他 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 保護的內容時，可安全輸出。
• 能在進階 UI 層的 Android TV 裝置上，以螢幕的完整解析度轉譯影片內容。

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

注意： 在 Android 7.0 (API 級別 24) 之前，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 上的 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 }
)

覆寫可繪項目

注意： 我們無法保證下節所述的自訂功能將在日後的程式庫版本中繼續使用。資源 ID 可能會變更名稱，或有部分已完全刪除。畫面上會顯示標示為「private」的資源 ID。

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

進一步自訂

如果需要上述自訂項目以外的自訂功能，我們預期應用程式開發人員將實作自己的 UI 元件，而不是使用 Media3 的 UI 模組提供的元件。