本頁面說明可搭配 Media3 播放影片的不同類型介面,以及如何根據用途選擇合適的類型。如要進一步瞭解 Android 中的 Surface 物件,請參閱這份圖形說明文件。
設定介面
Player 有四個進入點可將影片輸出連結至 Surface:
void setVideoSurface(@Nullable Surface surface)void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)void setVideoSurfaceView(@Nullable SurfaceView surfaceView)void setVideoTextureView(@Nullable TextureView textureView)
清除快取的方法也有幾種:
void clearVideoSurface()void clearVideoSurface(@Nullable Surface surface)void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)void clearVideoSurfaceView(@Nullable SurfaceView surfaceView)void clearVideoTextureView(@Nullable TextureView textureView)
選擇 PlayerView 的介面類型
PlayerView 的 surface_type 屬性可讓您設定用於影片播放的介面類型。允許的值包括:
surface_view(SurfaceView)texture_view(TextureView)spherical_gl_surface_view(SphericalGLSurfaceView) - 用於播放球形影片video_decoder_gl_surface_view(VideoDecoderGLSurfaceView) - 使用擴充功能轉譯器轉譯影片none:僅用於音訊播放,應避免建立介面,因為這樣做可能需要較高成本。
如果檢視畫面用於一般影片播放,則應使用 surface_view 或 texture_view。相較於 TextureView,SurfaceView 在影片播放方面有許多優點:
- 在許多裝置上,耗電量大幅降低。
- 影格時間更準確,影片播放更流暢。
- 在支援的裝置上,支援更高畫質的 HDR 影片輸出。
- 播放受 DRM 保護的內容時,支援安全輸出。
- 在 Android TV 裝置上,以螢幕完整解析度算繪影片內容,並放大 UI 圖層。
因此,建議盡可能使用 SurfaceView,而非 TextureView。只有在 SurfaceView 不符合需求時,才應使用 TextureView。舉例來說,在 Android 7.0 (API 級別 24) 之前,如果需要流暢的動畫或捲動影片介面,就必須使用 TextureView,詳情請參閱下列附註。在這種情況下,建議只有在 SDK_INT 小於 24 (Android 7.0) 時才使用 TextureView,否則請使用 SurfaceView。
在 Compose 中選擇介面類型
在 Compose 中,互通性解決方案會使用 AndroidView 可組合函式包裝 SurfaceView 和 TextureView。對應的兩個可組合函式是 androidx.compose.foundation 的 AndroidExternalSurface 和 AndroidEmbeddedExternalSurface。不過,這些 Proxy 類別提供的 API 介面會限制基礎檢視畫面的存取權。Player 需要這些檢視畫面,才能處理途徑的完整生命週期 (建立和大小更新)。
在 media3-ui-compose 模組中,您可以找到 ContentFrame 和 PlayerSurface 可組合函式,這些函式會以生命週期感知方式將 Player 連結至 Surface。本例中的途徑類型如下:
androidx.media3.ui.compose.SURFACE_TYPE_SURFACE_VIEWandroidx.media3.ui.compose.SURFACE_TYPE_TEXTURE_VIEW
沒有 none 類型,因為這相當於不將可組合項納入 Compose UI 樹狀結構。
如要瞭解如何在 Compose 中管理影片顯示比例、動態視窗大小和內容縮放,請參閱「跨板型規格縮放媒體內容」。