כתיבה מהירה

הספרייה 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 מוצג הסדר שבו הוא מצייר את השכבות שלו.

נגן וידאו עם קווים מקווקווים שמסמנים את המיקומים שלו. מלמעלה למטה: topControls לאורך הקצה העליון, errorOverlay מעל המרכז, centerControls באמצע עם הכפתורים backSecondary,‏ back,‏ central,‏ forward ו-forwardSecondary,‏ subtitles ליד החלק התחתון ו-bottomControls לאורך הקצה התחתון עם המשבצות above,‏ left,‏ progressSlider,‏ right ו-below. ‫ContentFrame ממלא את האזור שמאחוריהם.
תרשים 1. המשבצות של הרכיב הקומפוזבילי Player. אמצעי הבקרה במרכז ובתחתית מציגים את המשבצות של PlayerDefaults.CenterControls ושל PlayerDefaults.BottomControls. המשבצות topControls,‏ above ו-below ריקות כברירת מחדל.
תצוגה מפורטת של שש שכבות מוערמות. מלמטה למעלה: 1, PlayerSurface;‏ 2, shutter;‏ 3, artwork;‏ 4, subtitles;‏ 5, errorOverlay;‏ ו-6, topControls,‏ centerControls ו-bottomControls. שכבות 1 עד 4 מרכיבות את ContentFrame, וכל שש השכבות מרכיבות את Player.
איור 2. השכבות של הרכיב הניתן לקומפוזיציה 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 עלול להוביל את ממשק המשתמש למצבים לא חוקיים.

יצירת מצבי ממשק משתמש בהתאמה אישית

אם המצבים הקיימים של ממשק המשתמש לא עונים על הצרכים שלכם, אתם יכולים להוסיף מצבים בהתאמה אישית. כדי להעתיק את התבנית, צריך לבדוק את קוד המקור של המצב הקיים. מחלקה אופיינית של מאחסן מצב של ממשק המשתמש מבצעת את הפעולות הבאות:

  1. מקבלת אובייקט Player.
  2. נרשם ל-Player באמצעות פונקציות קורוטין. פרטים נוספים מופיעים במאמר Player.listen.
  3. מגיבה לPlayer.Events מסוימים על ידי עדכון המצב הפנימי שלה.
  4. מקבל פקודות של לוגיקה עסקית שיומרו לעדכון מתאים של Player.
  5. אפשר ליצור אותו בכמה מקומות בעץ ממשק המשתמש, והוא תמיד ישמור על תצוגה עקבית של מצב הנגן.
  6. חושף שדות של Compose State שרכיב קומפוזבילי יכול לצרוך כדי להגיב באופן דינמי לשינויים.
  7. הוא כולל פונקציה של 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.