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

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

Kotlin

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

Groovy

implementation "androidx.media3:media3-ui:1.4.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。一 比如，需要流暢的動畫或捲動影片介面 請參閱以下說明。適用對象 在此情況下，建議您只在 SDK_INT 更低的情況下使用 TextureView 大於 24 (Android 7.0) 以及 SurfaceView。

注意： SurfaceView 算繪在動畫顯示至檢視畫面動畫前，無法與檢視畫面動畫正確同步 Android 7.0 (API 級別 24)。在先前的版本中，這可能會導致不必要的影響 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 裝置會以低於 螢幕的完整解析度，將螢幕放大，以便向使用者呈現。適用對象 例如，在搭載 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);
}

要求聚焦在播放器檢視畫面時，對於導覽播放作業相當重要 讓使用者控制及略過廣告建議提出 onCreate 的焦點要求： Activity:

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 模組提供資源