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

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

KotlinGroovy

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

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

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

PlayerView 具有用於附加和卸離的 setPlayer 方法 ( 最後傳遞 null) 播放器例項。

播放器檢視

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 方法：

KotlinJava

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

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

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

KotlinJava

// 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()

// 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 保護的內容時，可安全輸出。
• 能夠以螢幕的完整解析度，顯示影片內容 提供高階 UI 層的 Android TV 裝置。

因此，請盡可能使用 SurfaceView 而非 TextureView。只有在 SurfaceView 無法滿足需求時，才應使用 TextureView。舉例來說，如果您需要在 Android 7.0 (API 級別 24) 以下版本中，以流暢的動畫或捲動方式顯示影片介面，請參閱以下附註。適用對象 在此情況下，建議您只在 SDK_INT 更低的情況下使用 TextureView 大於 24 (Android 7.0) 以及 SurfaceView。

注意： SurfaceView 算繪在動畫顯示至檢視畫面動畫前，無法與檢視畫面動畫正確同步 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 裝置會以低於 螢幕的完整解析度，將螢幕放大，以便向使用者呈現。舉例來說，在具備 4K 螢幕的 Android TV 上，UI 層可能會以 1080p 執行。在這些裝置上，您必須使用 SurfaceView 以顯示器的完整解析度轉譯內容。螢幕的完整解析度 ( 目前的顯示模式)，則可使用 Util.getCurrentDisplayModeSize 查詢。 您可以使用 Android 的 Display.getSize API，查詢 UI 層解析度。

Android TV 上的 D-Pad 導覽

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

KotlinJava

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

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

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

KotlinJava

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

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