ไลบรารี media3-ui-compose มีคอมโพเนนต์พื้นฐานสำหรับการสร้าง UI ของสื่อใน Jetpack Compose ซึ่งออกแบบมาสำหรับนักพัฒนาซอฟต์แวร์ที่ต้องการการปรับแต่งมากกว่าที่ไลบรารี media3-ui-compose-material3 มีให้ หน้านี้อธิบายวิธีใช้คอมโพเนนต์หลักและตัวเก็บสถานะเพื่อสร้าง UI ของมีเดียเพลเยอร์ที่กำหนดเอง
การผสมผสาน Material3 และคอมโพเนนต์ Compose ที่กำหนดเอง
ไลบรารี media3-ui-compose-material3 ออกแบบมาให้มีความยืดหยุ่น คุณสามารถใช้คอมโพเนนต์ที่สร้างไว้ล่วงหน้าสำหรับ UI ส่วนใหญ่ แต่สลับคอมโพเนนต์เดียวสำหรับการติดตั้งใช้งานที่กำหนดเองเมื่อต้องการการควบคุมเพิ่มเติม นี่คือช่วงที่ไลบรารี media3-ui-compose เข้ามามีบทบาท
ตัวอย่างเช่น สมมติว่าคุณต้องการใช้ PreviousButton และ NextButton มาตรฐานจากไลบรารี Material3 แต่คุณต้องการ PlayPauseButton ที่กำหนดเองทั้งหมด คุณทำได้โดยใช้ PlayPauseButton จากไลบรารี media3-ui-compose หลักและวางไว้ข้างคอมโพเนนต์ที่สร้างไว้ล่วงหน้า
Row { // Use prebuilt component from the Media3 UI Compose Material3 library PreviousButton(player) // Use the scaffold component from Media3 UI Compose library PlayPauseButton(player) { // `this` is PlayPauseButtonState FilledTonalButton( onClick = { Log.d("PlayPauseButton", "Clicking on play-pause button") this.onClick() }, enabled = this.isEnabled, ) { Icon( imageVector = if (showPlay) Icons.Default.PlayArrow else Icons.Default.Pause, contentDescription = if (showPlay) "Play" else "Pause", ) } } // Use prebuilt component from the Media3 UI Compose Material3 library NextButton(player) }
คอมโพเนนต์ที่ใช้ได้
ไลบรารี media3-ui-compose มีชุด Composable ที่สร้างไว้ล่วงหน้าสำหรับตัวควบคุมวิดีโอเพลเยอร์ทั่วไป ตัวอย่างคอมโพเนนต์ที่คุณใช้ในแอปได้โดยตรงมีดังนี้
| ส่วนประกอบ | คำอธิบาย |
|---|---|
PlayPauseButton |
คอนเทนเนอร์สถานะสำหรับปุ่มที่สลับระหว่างเล่นและหยุดชั่วคราว |
SeekBackButton |
คอนเทนเนอร์สถานะสำหรับปุ่มที่กรอกลับตามการเพิ่มที่กำหนด |
SeekForwardButton |
คอนเทนเนอร์สถานะสำหรับปุ่มที่กรอไปข้างหน้าตามการเพิ่มที่กำหนด |
NextButton |
คอนเทนเนอร์สถานะสำหรับปุ่มที่กรอไปยังรายการสื่อถัดไป |
PreviousButton |
คอนเทนเนอร์สถานะสำหรับปุ่มที่กรอไปยังรายการสื่อก่อนหน้า |
RepeatButton |
คอนเทนเนอร์สถานะสำหรับปุ่มที่วนรอบโหมดเล่นซ้ำ |
ShuffleButton |
คอนเทนเนอร์สถานะสำหรับปุ่มที่เปิด/ปิดโหมดสุ่มเพลง |
MuteButton |
คอนเทนเนอร์สถานะสำหรับปุ่มที่ปิดเสียงและเปิดเสียงโปรแกรมเล่น |
TimeText |
คอนเทนเนอร์สถานะสำหรับ Composable ที่แสดงความคืบหน้าของโปรแกรมเล่น |
ContentFrame |
แพลตฟอร์มสำหรับเนื้อหาสื่อที่จัดการการจัดการสัดส่วนภาพ การปรับขนาด ชัตเตอร์ อาร์ตเวิร์ก และช่องคำบรรยาย |
PlayerSurface |
พื้นผิวแบบ Raw ซึ่งรวม SurfaceView และ TextureView ไว้ใน AndroidView |
Artwork |
Composable ที่แสดงอาร์ตเวิร์กของรายการสื่อปัจจุบัน เช่น ปกอัลบั้ม |
ปรับแต่ง Composable Player
เมื่อใช้ไลบรารี media3-ui-compose-material3 คอมโพสิเบิล Player จะมอบประสบการณ์การเล่นสื่อที่สมบูรณ์แบบ คุณสามารถปรับแต่งเลย์เอาต์ได้โดยระบุ Composable ของคุณเองให้กับช่องเนื้อหา หรือจะใช้ออบเจ็กต์ PlayerDefaults เพื่อปรับแต่งส่วนที่เฉพาะเจาะจงของ UI เช่น TopControls, CenterControls, BottomControls และ ErrorOverlay ก็ได้
รูปที่ 1 แสดงตำแหน่งที่คอมโพสิเบิล Player วางช่องของตนเอง รูปที่ 2 แสดงลำดับการวาดเลเยอร์
Player
ตัวควบคุมตรงกลางและด้านล่างแสดงช่องของ PlayerDefaults.CenterControls และ PlayerDefaults.BottomControls ช่อง topControls, above และ below จะว่างเปล่าโดยค่าเริ่มต้นPlayer
ซึ่งมีหมายเลขกำกับตามลำดับที่วาดเช่น คุณสามารถใช้ PlayerDefaults.CenterControls เพื่อลบล้างเฉพาะปุ่มเล่น/หยุดชั่วคราวตรงกลางได้ โดยปล่อยให้การควบคุมตรงกลางที่เหลือเหมือนเดิม
นอกจากนี้ คุณยังส่ง Composable ที่กำหนดเองทั้งหมดสำหรับพารามิเตอร์ เช่น topControls และละเว้นพารามิเตอร์อื่นๆ เช่น bottomControls เพื่อปล่อยให้เป็นค่าเริ่มต้นได้ด้วย
@Composable fun CustomPlayerSlots(player: Player, showControls: Boolean, modifier: Modifier = Modifier) { Player( player = player, modifier = modifier, showControls = showControls, topControls = { // Fully custom top controls Text("My custom title") }, centerControls = { // Use default CenterControls but override the central button PlayerDefaults.CenterControls( player = player, central = { // A custom play/pause button Material3PlayPauseButton(player, modifier = Modifier.size(64.dp)) }, ) }, // bottomControls are left as default ) }
คอมโพสิเบิล Player ยังแสดงคำบรรยายและอาร์ตเวิร์กของรายการสื่อปัจจุบันเมื่อไม่มีวิดีโอให้แสดงด้วย หากต้องการปรับแต่งลักษณะที่ปรากฏ ให้ส่ง Composable ของคุณเองไปยังช่อง subtitles และ artwork หากต้องการซ่อน ให้ส่ง Composable ที่ว่างเปล่าไปยัง subtitles และ null ไปยัง artwork
ตัวเก็บสถานะ UI
หากไม่มีคอมโพเนนต์โครงสร้างใดที่ตรงกับความต้องการ คุณก็ใช้ออบเจ็กต์สถานะโดยตรงได้เช่นกัน โดยทั่วไป เราขอแนะนำให้ใช้เมธอด remember ที่เกี่ยวข้องเพื่อรักษารูปลักษณ์ของ UI ระหว่างการจัดองค์ประกอบใหม่
หากต้องการทำความเข้าใจให้ดียิ่งขึ้นเกี่ยวกับวิธีใช้ความยืดหยุ่นของตัวเก็บสถานะ UI เทียบกับ Composable โปรดอ่านวิธีที่ Compose จัดการสถานะ
ตัวเก็บสถานะของปุ่ม
สำหรับสถานะ UI บางสถานะ ไลบรารีจะถือว่าสถานะเหล่านั้นมีแนวโน้มที่จะใช้โดยคอมโพสิเบิลที่คล้ายปุ่มมากที่สุด
| รัฐ | remember*State | ประเภท |
|---|---|---|
PlayPauseButtonState |
rememberPlayPauseButtonState |
2-Toggle หรือ N-Toggle |
PreviousButtonState |
rememberPreviousButtonState |
ค่าคงที่ |
NextButtonState |
rememberNextButtonState |
ค่าคงที่ |
RepeatButtonState |
rememberRepeatButtonState |
3-Toggle |
ShuffleButtonState |
rememberShuffleButtonState |
2-Toggle |
PlaybackSpeedState |
rememberPlaybackSpeedState |
เมนูหรือปุ่มสลับ N |
นอกเหนือจากสถานะเล่นและหยุดชั่วคราวแล้ว PlayPauseButtonState ยังแสดง showBuffering, showReplay และ showRetry ด้วย ใช้เพื่อแสดงสัญญาณบอกสถานะการบัฟเฟอร์ขณะที่โปรแกรมเล่นกำลังบัฟเฟอร์ ไอคอนเล่นซ้ำหลังจากที่การเล่นสิ้นสุดลง และไอคอนลองอีกครั้งหลังจากเกิดข้อผิดพลาดในการเล่น showReplay และ showRetry จะปรับแต่ง showPlay: เมื่อใดก็ตามที่หนึ่งในนั้นเป็น true, showPlay ก็จะเป็น true ด้วย ดังนั้นให้ตรวจสอบก่อน showPlay เมธอด onClick จะจัดการสถานะเหล่านี้ด้วย เช่น โดยการเตรียมเพลเยอร์อีกครั้งหลังจากเกิดข้อผิดพลาด
หากต้องการเลือกสถานะที่จะแสดง ให้ส่งชุดค่าผสมของ SHOW_BUFFERING_WHEN_PLAYING, SHOW_BUFFERING_ALWAYS, SHOW_REPLAY_ON_ENDED และ SHOW_RETRY_ON_ERROR ไปยังพารามิเตอร์ displayMode ของ rememberPlayPauseButtonState โดยค่าเริ่มต้น displayMode จะรวม SHOW_BUFFERING_ALWAYS, SHOW_REPLAY_ON_ENDED และ SHOW_RETRY_ON_ERROR ซึ่งจะแสดงทั้ง 3 สถานะ และสถานะการบัฟเฟอร์จะปรากฏขึ้นแม้ในขณะที่หยุดเล่นชั่วคราว
ตัวอย่างการใช้ PlayPauseButtonState
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), ) }
ตัวเก็บสถานะเอาต์พุตภาพ
CurrentMediaItemState ให้ข้อมูลเกี่ยวกับMediaItemที่กำลังเล่นอยู่ ส่วน PlaylistState แสดงข้อมูลเกี่ยวกับMediaItemsที่ตั้งค่าไว้ในเพลเยอร์ ซึ่งมีประโยชน์สำหรับการแสดงข้อมูลเมตาที่แสดงผลใน UI ที่กำหนดเอง
ErrorState ให้ข้อมูลเกี่ยวกับสถานะข้อผิดพลาดปัจจุบันของเพลเยอร์ ซึ่งสามารถใช้เพื่อแสดงการวางซ้อนข้อผิดพลาดได้
PlaybackState แสดงสถานะการเล่นหลักของเพลเยอร์ เช่น playbackState, isPlaying และ playerError โดยไม่ขึ้นอยู่กับคอมโพเนนต์ UI ที่เฉพาะเจาะจง ใช้เพื่อขับเคลื่อนการวางซ้อนหรือเลย์เอาต์ที่กำหนดเอง เช่น เพื่อแสดงตัวบ่งชี้การโหลดขณะที่โปรแกรมเล่นกำลังบัฟเฟอร์ สำหรับตัวบ่งชี้ Material3 ที่สร้างไว้ล่วงหน้า ให้ใช้ BufferingIndicator
PresentationState จะเก็บข้อมูลเกี่ยวกับเวลาที่เอาต์พุตวิดีโอใน PlayerSurface สามารถแสดงหรือควรถูกปิดทับด้วยองค์ประกอบ UI ตัวยึดตำแหน่ง
ContentFrame Composable จะรวมการจัดการสัดส่วนภาพเข้ากับการดูแลการแสดงชัตเตอร์บนพื้นผิวที่ยังไม่พร้อม
@Composable fun ContentFrame( player: Player?, modifier: Modifier = Modifier, surfaceType: @SurfaceType Int = SURFACE_TYPE_SURFACE_VIEW, contentScale: ContentScale = ContentScale.Fit, keepContentOnReset: Boolean = false, shutter: @Composable () -> Unit = { Box(Modifier.fillMaxSize().background(Color.Black)) }, ) { val presentationState = rememberPresentationState(player, keepContentOnReset) val scaledModifier = modifier.resizeWithContentScale(contentScale, presentationState.videoAspectRatio) // Always leave PlayerSurface to be part of the Compose tree because it will be initialized 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, scaledModifier, surfaceType) if (presentationState.coverSurface) { // Cover the surface that is being prepared with a shutter shutter() } }
ในกรณีนี้ เราสามารถใช้ทั้ง presentationState.videoAspectRatio เพื่อปรับขนาด Surface ให้เป็นสัดส่วนภาพที่เลือก (ดูประเภทเพิ่มเติมได้ที่การปรับขนาดเนื้อหา) และ presentationState.coverSurface เพื่อให้ทราบว่าเมื่อใดที่ไม่เหมาะสมที่จะแสดง Surface ในกรณีนี้ คุณสามารถวางชัตเตอร์ทึบแสงไว้ด้านบนของพื้นผิว ซึ่งจะหายไปเมื่อพื้นผิวพร้อมใช้งาน
ContentFrame ให้คุณปรับแต่งชัตเตอร์เป็นแลมบ์ดาต่อท้ายได้ แต่โดยค่าเริ่มต้นจะเป็น @Composable Box สีดำที่เติมขนาดของคอนเทนเนอร์หลัก
PresentationState ยังแสดง showArtwork ซึ่งเป็น true เมื่อรายการสื่อปัจจุบันเล่นโดยไม่มีแทร็กวิดีโอ เช่น เนื้อหาแบบเสียงเท่านั้น ในกรณีนี้ ContentFrame จะแสดง Composable Artwork ซึ่งแสดงอาร์ตเวิร์กจาก MediaMetadata ของรายการ หากต้องการปรับแต่งหรือซ่อนอาร์ตเวิร์ก ให้ส่ง Composable ของคุณเองหรือ null ไปยังช่อง artwork ของ ContentFrame
โดยค่าเริ่มต้น Artwork จะโหลดเฉพาะข้อมูลอาร์ตเวิร์กที่ฝังอยู่ในข้อมูลเมตา หรือจาก URI content, file หรือ android.resource หากต้องการโหลดอาร์ตเวิร์กจาก URI ระยะไกลหรือแหล่งที่มาอื่นๆ ให้ใช้ตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้
- ส่ง
BitmapLoaderเช่นDataSourceBitmapLoaderไปยังArtwork - ใช้โอเวอร์โหลด
Artworkที่ใช้painterเพื่อโหลดรูปภาพด้วยไลบรารีที่คุณเลือก
ContentFrame จะปล่อยให้ช่อง subtitles ว่างไว้ ซึ่งต่างจาก Composable Player ที่แสดงผลคำบรรยายโดยค่าเริ่มต้น หากต้องการแสดงผลคำบรรยายใน ContentFrame หรือปรับแต่งการแสดงผลคำบรรยายใน Player ให้สังเกตคิวปัจจุบันของเพลเยอร์ด้วย CuesState และแสดงผลในช่อง subtitles ContentFrame จะจัดวางช่องนี้ภายในขอบเขตของวิดีโอที่ปรับขนาดแล้ว และวาดช่องนี้ไว้เหนือชัตเตอร์และอาร์ตเวิร์ก เพื่อให้คำบรรยายยังคงมองเห็นได้เมื่อไม่มีวิดีโอ
ตัวเก็บสถานะการเลือกแทร็ก
TrackSelectionState ช่วยให้คุณสร้างเมนูสำหรับแทร็กประเภทเดียว เช่น เมนูภาษาของเสียงหรือคำบรรยาย สร้างด้วย rememberTrackSelectionState โดยส่งประเภทแทร็กและชุดค่าผสมของตัวกรอง เช่น TRACK_FILTER_LANGUAGE หรือ TRACK_FILTER_RESOLUTION ซึ่งจะกำหนดว่าพร็อพเพอร์ตี้แทร็กใดที่แยกความแตกต่างของตัวเลือก ตั้งค่า hasOffOption หรือ hasAutoOption เป็น true เพื่อเพิ่มตัวเลือกที่ปิดใช้ประเภทแทร็กหรือตัวเลือกที่ช่วยให้โปรแกรมเล่นเลือกแทร็กโดยอัตโนมัติ
รัฐจะเปิดเผย selectionOptions และ selectedOption ที่มีอยู่
TrackSelectionOption แต่ละรายการจะระบุว่าอุปกรณ์รองรับหรือไม่ และมีการเลือกไว้หรือไม่ การส่งตัวเลือกไปยัง selectOption จะอัปเดตพารามิเตอร์การเลือกแทร็กของโปรแกรมเล่นตามนั้น ก่อนแสดงเมนู ให้ตรวจสอบ canSetTrackSelectionParameters และดูว่ามีตัวเลือกให้เลือกเพียงพอหรือไม่ ตัวอย่างเช่น เมนูคำบรรยายต่อไปนี้มีตัวเลือก 1 รายการสำหรับคำบรรยายแต่ละภาษา และตัวเลือกในการปิดคำบรรยาย
@Composable fun SubtitleMenu(player: Player, modifier: Modifier = Modifier) { val state = rememberTrackSelectionState( player, trackType = C.TRACK_TYPE_TEXT, trackFilters = TRACK_FILTER_LANGUAGE, hasOffOption = true, ) // Hide the menu if the player can't change tracks or has no subtitles to choose from if (!state.canSetTrackSelectionParameters || state.selectionOptions.size < 2) return Column(modifier.selectableGroup()) { for (option in state.selectionOptions) { Row( Modifier.fillMaxWidth() .heightIn(min = 48.dp) .selectable( selected = option.isSelected, enabled = option.isSupported, role = Role.RadioButton, onClick = { state.selectOption(option) }, ) .padding(horizontal = 16.dp), horizontalArrangement = Arrangement.spacedBy(16.dp), verticalAlignment = Alignment.CenterVertically, ) { RadioButton(selected = option.isSelected, onClick = null, enabled = option.isSupported) Text( text = if (option.onOffState == TRACK_SELECTION_OFF) "Off" else option.language?.let { Locale.forLanguageTag(it).displayName } ?: "Unknown", color = if (option.isSupported) Color.Unspecified else LocalContentColor.current.copy(alpha = 0.38f), ) } } } }
หากต้องการเข้าถึง Tracks และ TrackSelectionParameters ของผู้เล่นโดยตรง ให้ใช้ TrackSelectionParametersState แทน ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีที่เพลเยอร์เลือกแทร็กได้ที่การเลือกแทร็ก
Flows อยู่ที่ไหน
นักพัฒนาแอป Android หลายคนคุ้นเคยกับการใช้ออบเจ็กต์ Flow ของ Kotlin เพื่อรวบรวมข้อมูล UI ที่เปลี่ยนแปลงตลอดเวลา เช่น คุณอาจมองหาขั้นตอน Player.isPlaying ที่สามารถcollectในลักษณะที่คำนึงถึงวงจร หรืออะไรทำนองนั้น Player.eventsFlow เพื่อให้คุณมี Flow<Player.Events> ที่คุณสามารถ filter ได้ตามต้องการ
อย่างไรก็ตาม การใช้โฟลว์สำหรับสถานะ UI ของ Player มีข้อเสียบางประการ ข้อกังวลหลักประการหนึ่งคือลักษณะแบบอะซิงโครนัสของการโอนข้อมูล เราต้องการให้มีเวลาในการตอบสนองน้อยที่สุดระหว่าง Player.Event และการใช้งานในฝั่ง UI โดยหลีกเลี่ยงการแสดงองค์ประกอบ UI ที่ไม่สอดคล้องกับ Player
ประเด็นอื่นๆ มีดังนี้
- โฟลว์ที่มี
Player.Eventsทั้งหมดจะไม่เป็นไปตามหลักการความรับผิดชอบเดียว ผู้บริโภคแต่ละรายจะต้องกรองเหตุการณ์ที่เกี่ยวข้องออก - การสร้างโฟลว์สำหรับ
Player.Eventแต่ละรายการจะกำหนดให้คุณต้องรวมโฟลว์เหล่านั้น (ด้วยcombine) สำหรับองค์ประกอบ UI แต่ละรายการ มีการแมปแบบหลายต่อหลายระหว่าง Player.Event กับการเปลี่ยนแปลงองค์ประกอบ UI การต้องใช้combineอาจทำให้ UI อยู่ในสถานะที่อาจผิดกฎหมาย
สร้างสถานะ UI ที่กำหนดเอง
คุณเพิ่มสถานะ UI ที่กำหนดเองได้หากสถานะที่มีอยู่ไม่ตรงกับความต้องการ ดูซอร์สโค้ดของสถานะที่มีอยู่เพื่อคัดลอกรูปแบบ คลาสตัวเก็บสถานะ UI ทั่วไปจะทำสิ่งต่อไปนี้
- รับออบเจ็กต์
Player - สมัครรับข้อมูล
Playerโดยใช้โครูทีน ดูรายละเอียดเพิ่มเติมได้ที่Player.listen - ตอบสนองต่อ
Player.Eventsที่เฉพาะเจาะจงโดยการอัปเดตสถานะภายใน - ยอมรับคำสั่งตรรกะทางธุรกิจที่จะเปลี่ยนเป็นการอัปเดต
Playerที่เหมาะสม - สามารถสร้างได้ในหลายตำแหน่งในโครงสร้าง UI และจะรักษามุมมองที่สอดคล้องกันของสถานะ Player เสมอ
- แสดงช่อง
Stateของ Compose ที่ Composable สามารถใช้เพื่อตอบสนองต่อการเปลี่ยนแปลงแบบไดนามิก - มาพร้อมกับฟังก์ชัน
remember*Stateสำหรับจดจำอินสแตนซ์ระหว่างองค์ประกอบต่างๆ
สิ่งที่จะเกิดขึ้นเบื้องหลังมีดังนี้
class SomeButtonState(private val player: Player) { var isEnabled by mutableStateOf(player.isCommandAvailable(COMMAND_ACTION_A)) private set var someFieldValue by mutableStateOf(someFieldDefault) private set fun onClick() { player.actionA() } suspend fun observe(): Nothing = player.listen { events -> if (events.containsAny(EVENT_B_CHANGED, EVENT_C_CHANGED, EVENT_AVAILABLE_COMMANDS_CHANGED)) { someFieldValue = this.someField isEnabled = this.isCommandAvailable(COMMAND_ACTION_A) } } }
หากต้องการตอบสนองต่อ Player.Events ของคุณเอง คุณสามารถจับ เหล่านั้นได้โดยใช้ Player.listen
ซึ่งเป็น suspend fun ที่ช่วยให้คุณเข้าสู่โลกของโครูทีนและ
ฟัง Player.Events ได้อย่างไม่มีกำหนด การใช้งาน Media3 ของสถานะ UI ต่างๆ ช่วยให้นักพัฒนาแอปปลายทางไม่ต้องกังวลเกี่ยวกับการเรียนรู้เกี่ยวกับ Player.Events