הספרייה media3-ui-compose מספקת את הרכיבים הבסיסיים ליצירת ממשק משתמש של מדיה ב-Jetpack Compose. הוא מיועד למפתחים שצריכים יותר אפשרויות להתאמה אישית מאלה שמוצעות בספרייה media3-ui-compose-material3. בדף הזה מוסבר איך להשתמש ברכיבי הליבה ובמאחסני המצב כדי ליצור ממשק משתמש מותאם אישית של נגן מדיה.
שילוב של רכיבי Material3 ורכיבי פיתוח נייטיב בהתאמה אישית
הספרייה media3-ui-compose-material3 נועדה להיות גמישה. אתם יכולים להשתמש ברכיבים המובנים ברוב ממשק המשתמש, אבל להחליף רכיב אחד בהטמעה בהתאמה אישית כשאתם צריכים יותר שליטה. כאן נכנסת לתמונה הספרייה 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 מספקת קבוצה של רכיבים מובנים שניתנים לשילוב בשביל כפתורי הנגן הנפוצים. הנה כמה מהרכיבים שאפשר להשתמש בהם ישירות באפליקציה:
| רכיב | תיאור |
|---|---|
PlayPauseButton |
מאגר מצבים של כפתור שמאפשר לעבור בין הפעלה להשהיה. |
SeekBackButton |
מאגר מצב של כפתור שמריץ אחורה במרווח זמן מוגדר. |
SeekForwardButton |
קונטיינר מצב של כפתור שמריץ קדימה במרווח זמן מוגדר. |
NextButton |
מאגר מצב של כפתור שמעביר לקובץ המדיה הבא. |
PreviousButton |
מאגר מצבים של כפתור שמעביר לקובץ המדיה הקודם. |
RepeatButton |
מאגר מצבים של כפתור שמעביר בין מצבי הפעלה חוזרת. |
ShuffleButton |
מאגר מצבים של כפתור שמפעיל או משבית את מצב ההפעלה האקראית. |
MuteButton |
מאגר מצבים של כפתור להשתקה ולביטול ההשתקה של הנגן. |
TimeText |
מאגר מצב של תוכן קומפוזבילי שמציג את התקדמות הנגן. |
ContentFrame |
משטח לתוכן מדיה שמטפל בניהול יחס הגובה-רוחב, בשינוי הגודל, בתריס, בגרפיקה ובמשבצת לכתוביות. |
PlayerSurface |
משטח גולמי שעוטף את SurfaceView ואת TextureView ב-AndroidView. |
Artwork |
רכיב Composable שמציג את הגרפיקה של קובץ המדיה הנוכחי, כמו עטיפת אלבום. |
התאמה אישית של הרכיב הקומפוזבילי Player
כשמשתמשים בספרייה media3-ui-compose-material3, הפונקציה הקומפוזבילית Player מספקת חוויית הפעלה מלאה של מדיה. אפשר להתאים אישית את הפריסה שלו על ידי הוספת פונקציות קומפוזביליות משלכם למשבצות התוכן שלו, או להשתמש באובייקט PlayerDefaults כדי להתאים אישית חלקים ספציפיים בממשק המשתמש, כמו TopControls, CenterControls, BottomControls ו-ErrorOverlay.
באיור 1 מוצג המיקום של המשבצות ברכיב הקומפוזבילי Player. באיור 2 מוצג הסדר שבו הוא מצייר את השכבות שלו.
Player.
אמצעי הבקרה במרכז ובתחתית מציגים את המשבצות של PlayerDefaults.CenterControls ושל PlayerDefaults.BottomControls. המשבצות topControls, above ו-below ריקות כברירת מחדל.Player,
ממוספרות לפי הסדר שבו הן משורטטות.לדוגמה, אפשר להשתמש ב-PlayerDefaults.CenterControls כדי לשנות רק את לחצן ההפעלה/השהיה המרכזי, ולהשאיר את שאר אמצעי הבקרה המרכזיים ללא שינוי.
אפשר גם להעביר פונקציה קומפוזבילית בהתאמה אישית מלאה לפרמטר כמו 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 מציג גם כתוביות, וכשאין סרטון להצגה, את הגרפיקה של קובץ המדיה הנוכחי. כדי להתאים אישית את המראה שלהם, מעבירים את הפונקציות הניתנות לשילוב למשבצות subtitles ו-artwork. כדי להסתיר אותם, מעבירים רכיב Composable ריק אל subtitles ואת null אל artwork.
מאחסני מצבים לממשקי משתמש
אם אף אחד מרכיבי הפיגומים לא עונה על הצרכים שלכם, אתם יכולים גם להשתמש באובייקטים של המצב ישירות. בדרך כלל מומלץ להשתמש בשיטות remember המתאימות כדי לשמור על מראה ממשק המשתמש בין הרכבות מחדש.
כדי להבין טוב יותר איך אתם יכולים להשתמש בגמישות של מאחסני המצב של ממשק המשתמש לעומת פונקציות ה-Composable, קראו איך Compose מנהל את המצב.
מאחסני מצב של כפתורים
במצבים מסוימים של ממשק המשתמש, הספרייה מניחה שסביר להניח שהם יצרכו על ידי רכיבים קומפוזביליים דמויי לחצנים.
| מדינה | remember*State | סוג |
|---|---|---|
PlayPauseButtonState |
rememberPlayPauseButtonState |
מתג דו-מצבי או מתג רב-מצבי |
PreviousButtonState |
rememberPreviousButtonState |
קבוע |
NextButtonState |
rememberNextButtonState |
קבוע |
RepeatButtonState |
rememberRepeatButtonState |
מתג תלת-מצבי |
ShuffleButtonState |
rememberShuffleButtonState |
2 מתגים |
PlaybackSpeedState |
rememberPlaybackSpeedState |
תפריט או החלפת מצב N |
בנוסף למצבי ההפעלה וההשהיה, PlayPauseButtonState חושף את showBuffering, showReplay ו-showRetry. אפשר להשתמש בהם כדי להציג אינדיקטור של אגירת נתונים בזמן שהנגן אוגר נתונים, סמל של הפעלה מחדש אחרי שההפעלה מסתיימת וסמל של ניסיון חוזר אחרי שגיאת הפעלה. showReplay ו-showRetry משכללים את showPlay: בכל פעם שאחד מהם הוא true, גם showPlay הוא true, אז צריך לבדוק אותם לפני showPlay. ה-method 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, ומציג את שלושת המצבים, ומצב הטעינה מופיע גם כשההפעלה מושהית.
דוגמה לשימוש ב-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 שמוגדר בנגן. הם שימושיים להצגת מידע על מטא-נתונים בממשק המשתמש המותאם אישית.
ErrorState מספק מידע על מצב השגיאה הנוכחי של הנגן, שבו אפשר להשתמש כדי להציג שכבת-על של שגיאה.
PlaybackState חושף את מצב ההפעלה העיקרי של הנגן, כמו playbackState, isPlaying ו-playerError, בלי קשר לרכיב ספציפי של ממשק המשתמש. אפשר להשתמש בו כדי להפעיל שכבות-על או פריסות בהתאמה אישית, למשל כדי להציג אינדיקטור טעינה בזמן שהנגן מבצע אגירת נתונים. כדי להשתמש באינדיקטור מובנה של Material3, משתמשים ב-BufferingIndicator.
PresentationState מכיל מידע על המקרים שבהם אפשר להציג את פלט הווידאו ב-PlayerSurface, או על המקרים שבהם צריך להסתיר אותו באמצעות רכיב פלייסהולדר בממשק המשתמש.
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 מציג את התוכן הקומפוזבילי Artwork, שמציג את הגרפיקה מ-MediaMetadata של הפריט. כדי להתאים אישית או להסתיר את הגרפיקה, צריך להעביר את ה-composable או את null למשבצת artwork של ContentFrame.
כברירת מחדל, Artwork טוען רק נתוני גרפיקה שמוטמעים במטא-נתונים, או מ-URI מסוג content, file או android.resource. כדי לטעון גרפיקה מכתובות URI מרוחקות או ממקורות אחרים, אתם יכולים להשתמש באחת מהאפשרויות הבאות:
- מעבירים
BitmapLoader, כמוDataSourceBitmapLoader, אלArtwork. - משתמשים בעומס היתר של
Artworkשמקבלpainterכדי לטעון תמונות באמצעות הספרייה שבחרתם.
בניגוד לרכיב ה-Composable Player, שמעבד כתוביות כברירת מחדל,
ContentFrame משאיר את המשבצת subtitles שלו ריקה. כדי לעבד כתוביות ב-ContentFrame, או כדי להתאים אישית את עיבוד הכתוביות ב-Player, צריך לבחון את האותות הנוכחיים של הנגן באמצעות CuesState ולעבד אותם במשבצת subtitles. ContentFrame מציב את המשבצת הזו בתוך גבולות הסרטון המוקטן ומציג אותה מעל התריס והתמונה, כדי שהכתוביות יישארו גלויות כשאין סרטון.
מאחסני מצב של בחירת טראקים
TrackSelectionState עוזר לכם ליצור תפריט לסוג טראק אחד, כמו שפת אודיו או תפריט כתוביות. יוצרים אותו באמצעות rememberTrackSelectionState, ומעבירים את סוג הטראק ושילוב של מסננים, כמו TRACK_FILTER_LANGUAGE או TRACK_FILTER_RESOLUTION, שקובעים אילו מאפייני טראק מבדילים בין האפשרויות. מגדירים את hasOffOption או את hasAutoOption לערך true כדי להוסיף אפשרות שמשביתה את סוג הטראק או אפשרות שמאפשרת לנגן לבחור טראקים באופן אוטומטי.
הסטטוס חושף את selectionOptions ו-selectedOption הזמינים.
כל TrackSelectionOption מציין אם המכשיר תומך בו ואם הוא נבחר. העברת אפשרות אל selectOption מעדכנת את הפרמטרים לבחירת טראקים של הנגן בהתאם. לפני שאתם מציגים את התפריט, בדקו את canSetTrackSelectionParameters ואם יש מספיק אפשרויות לבחירה. לדוגמה, בתפריט הכתוביות הבא יש אפשרות אחת לכל שפת כתוביות ואפשרות להשבית את הכתוביות:
@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 מכירים את השימוש באובייקטים של Kotlin Flow כדי לאסוף נתונים של ממשק המשתמש שמשתנים כל הזמן. לדוגמה, יכול להיות שאתם מחפשים
Player.isPlaying flow שאתם יכולים collect באופן שמותאם למחזור החיים. או משהו כמו Player.eventsFlow כדי לספק לכם Flow<Player.Events> שתוכלו filter איך שתרצו.
עם זאת, לשימוש בתהליכים למצב ממשק המשתמש של Player יש כמה חסרונות. אחד החששות העיקריים הוא האופי האסינכרוני של העברת הנתונים. אנחנו רוצים להשיג זמן אחזור קצר ככל האפשר בין Player.Event לבין הצריכה שלו בצד של ממשק המשתמש, כדי להימנע מהצגת רכיבים בממשק המשתמש שלא מסונכרנים עם Player.
נקודות נוספות:
- תהליך עם כל ה-
Player.Eventsלא יתאים לעיקרון של אחריות אחת, וכל צרכן יצטרך לסנן את האירועים הרלוונטיים. - כדי ליצור תהליך לכל
Player.Event, צריך לשלב אותם (באמצעותcombine) לכל רכיב בממשק המשתמש. יש מיפוי של רבים לרבים בין Player.Event לבין שינוי ברכיב בממשק המשתמש. שימוש ב-combineעלול להוביל את ממשק המשתמש למצבים לא חוקיים.
יצירת מצבי ממשק משתמש בהתאמה אישית
אם המצבים הקיימים של ממשק המשתמש לא עונים על הצרכים שלכם, אתם יכולים להוסיף מצבים בהתאמה אישית. כדי להעתיק את התבנית, צריך לבדוק את קוד המקור של המצב הקיים. מחלקה אופיינית של מאחסן מצב של ממשק המשתמש מבצעת את הפעולות הבאות:
- מקבלת אובייקט
Player. - נרשם ל-
Playerבאמצעות פונקציות קורוטין. פרטים נוספים מופיעים במאמרPlayer.listen. - מגיבה ל
Player.Eventsמסוימים על ידי עדכון המצב הפנימי שלה. - מקבל פקודות של לוגיקה עסקית שיומרו לעדכון מתאים של
Player. - אפשר ליצור אותו בכמה מקומות בעץ ממשק המשתמש, והוא תמיד ישמור על תצוגה עקבית של מצב הנגן.
- חושף שדות של Compose
Stateשרכיב קומפוזבילי יכול לצרוך כדי להגיב באופן דינמי לשינויים. - הוא כולל פונקציה של
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 שמאפשר לכם להיכנס לעולם של coroutine ולהאזין ל-Player.Events ללא הגבלת זמן. ההטמעה של Media3 במצבים שונים של ממשק המשתמש עוזרת למפתח הקצה לא לדאוג לגבי למידה על Player.Events.