新增依附元件
Media3 程式庫包含以 Jetpack Compose 為基礎的 UI 模組。如要使用,請新增下列依附元件:
Kotlin
implementation("androidx.media3:media3-ui-compose:1.7.1")
Groovy
implementation "androidx.media3:media3-ui-compose:1.7.1"
強烈建議您以 Compose 為優先開發應用程式,或從使用 Views 遷移。
完整的 Compose 示範應用程式
雖然 media3-ui-compose
程式庫不包含現成的 Composable (例如按鈕、指標、圖片或對話方塊),但您可以找到完全以 Compose 編寫的示範應用程式,避免使用任何互通性解決方案,例如將 PlayerView
包裝在 AndroidView
中。這個範例應用程式會使用 media3-ui-compose
模組中的 UI 狀態持有者類別,並採用 Compose Material3 程式庫。
UI 狀態容器
如要進一步瞭解如何運用 UI 狀態持有者和可組合函式的彈性,請參閱「Compose 如何管理狀態」。
按鈕狀態容器
對於某些 UI 狀態,我們假設這些狀態最有可能由類似按鈕的可組合函式取用。
狀態 | remember*State | 類型 |
---|---|---|
PlayPauseButtonState |
rememberPlayPauseButtonState |
2-Toggle |
PreviousButtonState |
rememberPreviousButtonState |
常數 |
NextButtonState |
rememberNextButtonState |
常數 |
RepeatButtonState |
rememberRepeatButtonState |
3-Toggle |
ShuffleButtonState |
rememberShuffleButtonState |
2-Toggle |
PlaybackSpeedState |
rememberPlaybackSpeedState |
選單或 N 切換 |
PlayPauseButtonState
的使用範例:
@Composable
fun PlayPauseButton(player: Player, modifier: Modifier = Modifier) {
val state = rememberPlayPauseButtonState(player)
IconButton(onClick = state::onClick, modifier = modifier, enabled = state.isEnabled) {
Icon(
imageVector = if (state.showPlay) Icons.Default.PlayArrow else Icons.Default.Pause,
contentDescription =
if (state.showPlay) stringResource(R.string.playpause_button_play)
else stringResource(R.string.playpause_button_pause),
)
}
}
請注意,state
沒有主題資訊,例如用於播放或暫停的圖示。其唯一責任是將 Player
轉換為 UI 狀態。
接著,您可以在偏好的版面配置中混搭按鈕:
Row(
modifier = modifier.fillMaxWidth(),
horizontalArrangement = Arrangement.SpaceEvenly,
verticalAlignment = Alignment.CenterVertically,
) {
PreviousButton(player)
PlayPauseButton(player)
NextButton(player)
}
視覺輸出狀態容器
PresentationState
包含影片輸出內容何時可顯示,或應由預留位置 UI 元素遮蓋的資訊。PlayerSurface
val presentationState = rememberPresentationState(player)
val scaledModifier = Modifier.resize(ContentScale.Fit, presentationState.videoSizeDp)
Box(modifier) {
// Always leave PlayerSurface to be part of the Compose tree because it will be initialised in
// the process. If this composable is guarded by some condition, it might never become visible
// because the Player won't emit the relevant event, e.g. the first frame being ready.
PlayerSurface(
player = player,
surfaceType = SURFACE_TYPE_SURFACE_VIEW,
modifier = scaledModifier,
)
if (presentationState.coverSurface) {
// Cover the surface that is being prepared with a shutter
Box(Modifier.background(Color.Black))
}
在這裡,我們可以使用 presentationState.videoSizeDp
將 Surface 縮放至所需長寬比 (如需更多類型,請參閱 ContentScale 文件),並使用 presentationState.coverSurface
瞭解顯示 Surface 的時機是否不適當。在這種情況下,您可以在表面上放置不透明的快門,表面準備就緒時,快門就會消失。
Flows 在哪裡?
許多 Android 開發人員都熟悉使用 Kotlin Flow
物件收集不斷變動的 UI 資料。舉例來說,您可能會尋找可以Player.isPlaying
以生命週期感知方式collect
的資料流。或是 Player.eventsFlow
,為你提供可Flow<Player.Events>
的filter
。
不過,使用 Flow 處理 Player
UI 狀態有一些缺點。主要疑慮之一是資料傳輸的非同步性質。我們希望盡可能縮短 Player.Event
與 UI 端耗用之間的延遲時間,避免顯示與 Player
不同步的 UI 元素。
其他重點包括:
- 如果流程包含所有
Player.Events
,就不會遵守單一責任原則,每個消費者都必須篩除相關事件。 - 如要為每個
Player.Event
建立流程,您必須為每個 UI 元素合併這些流程 (使用combine
)。Player.Event 與 UI 元素變更之間存在多對多對應關係。必須使用combine
可能會導致 UI 進入潛在的非法狀態。
建立自訂 UI 狀態
如果現有 UI 狀態不符合需求,可以新增自訂 UI 狀態。查看現有狀態的原始碼,複製模式。典型的 UI 狀態容器類別會執行下列操作:
- 以
Player
為單位。 - 使用協同程式訂閱
Player
。詳情請參閱Player.listen
。 - 更新內部狀態,以回應特定
Player.Events
。 - 接受將轉換為適當
Player
更新的業務邏輯指令。 - 可在 UI 樹狀結構中的多個位置建立,且一律會維持 Player 狀態的一致檢視畫面。
- 公開可組合函式可使用的 Compose
State
欄位,以動態回應變更。 - 隨附
remember*State
函式,可在組合之間記住執行個體。
幕後到底發生了什麼事?
class SomeButtonState(private val player: Player) {
var isEnabled by mutableStateOf(player.isCommandAvailable(Player.COMMAND_ACTION_A))
private set
var someField by mutableStateOf(someFieldDefault)
private set
fun onClick() {
player.actionA()
}
suspend fun observe() =
player.listen { events ->
if (
events.containsAny(
Player.EVENT_B_CHANGED,
Player.EVENT_C_CHANGED,
Player.EVENT_AVAILABLE_COMMANDS_CHANGED,
)
) {
someField = this.someField
isEnabled = this.isCommandAvailable(Player.COMMAND_ACTION_A)
}
}
}
如要對自己的 Player.Events
做出反應,可以使用 Player.listen
擷取這些項目,這是 suspend fun
,可讓您進入協同程式世界,並無限期監聽 Player.Events
。Media3 實作各種 UI 狀態,可協助開發人員不必學習 Player.Events
。