開始使用以 View 為基礎的 UI

新增依附元件

Kotlin

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

Groovy

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

PlayerView

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

PlayerView 具有 setPlayer() 方法，可附加及卸離 (透過傳遞 null) Player 例項。

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 說明文件會更詳細地列出這些屬性和設定器方法。

如要提供更舒適的使用者體驗，請考慮新增 keepScreenOn Android 屬性或設定喚醒鎖定 (如果您使用 ExoPlayer)。您可以在背景工作頁面中，調查其他導致裝置保持喚醒狀態的動作。

android:keepScreenOn="true"

在版面配置檔案中宣告檢視區塊後，即可在活動的 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();

PlayerControlView

PlayerControlView 是 PlayerView 子檢視區塊之一，內含進度列和控制播放的按鈕。請注意，PlayerControlView 不得做為 PlayerView 以外的獨立元件使用。您可以透過在 PlayerView 上設定屬性 (會傳遞至 PlayerControlView)，或使用 android:id="@id/exo_controller 提供自訂控制器，來自訂此項目。

選擇平台類型

PlayerView 的 surface_type 屬性可讓你設定用於播放影片的介面類型。允許的值為 surface_view、texture_view、spherical_gl_surface_view (球形影片播放的特殊值)、video_decoder_gl_surface_view (使用擴充轉譯器轉譯影片) 和 none (僅限音訊播放)。如要進一步瞭解要選擇哪種介面類型，請參閱「介面」頁面。