播放媒體的應用程式需要使用者介面元件,才能顯示媒體及控製播放。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 模組提供的元件。