הוספה של רכיבי ה-UI להפעלה לאפליקציה

אפליקציה שמפעילה מדיה זקוקה לרכיבי ממשק משתמש להצגת המדיה ולשליטה בהפעלה. ספריית Media3 כוללת מודול של ממשק משתמש שמכיל מספר רכיבים של ממשק המשתמש. כדי להיות תלויים במודול ממשק המשתמש, צריך להוסיף את התלות הבאה:

Kotlin

implementation("androidx.media3:media3-ui:1.4.1")

Groovy

implementation "androidx.media3:media3-ui:1.4.1"

הרכיב החשוב ביותר הוא PlayerView, תצוגה של הפעלות מדיה. PlayerView מציג סרטונים, תמונות, כתוביות ותמונות שער של אלבומים במהלך ההפעלה, וגם את פקדי ההפעלה.

ל-PlayerView יש שיטה setPlayer להצמדה ולניתוק (על ידי העברת null) של מכשירי הנגן.

PlayerView

אפשר להשתמש ב-PlayerView גם להפעלת סרטונים, תמונות ואודיו. הוא מעבד סרטונים וכתוביות במקרה של הפעלת סרטון, ותמונות בפורמט בייטמאפ במקרה של הפעלת תמונה, ויכול להציג גרפיקה שכלולה כמטא-נתונים בקובצי אודיו. אפשר לכלול אותו בקובצי הפריסה כמו כל רכיב אחר בממשק המשתמש. לדוגמה, אפשר לכלול את ה-PlayerView ב-XML הבא:

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

קטע הקוד שלמעלה ממחיש ש-PlayerView מספק מספר מאפיינים. ניתן להשתמש במאפיינים האלה כדי להתאים אישית את התנהגות התצוגה, וגם את המראה והסגנון שלה. לרוב המאפיינים האלה יש שיטות setter תואמות, שאפשר להשתמש בהן כדי להתאים אישית את התצוגה בזמן הריצה. המאפיינים ושיטות ההגדרה (setter) האלה מפורטים בפירוט רב יותר ב-Javadoc של PlayerView.

אחרי שמצהירים על התצוגה בקובץ הפריסה, אפשר לחפש אותה ב-method‏ onCreate של הפעילות:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

אחרי שמפעילים את הנגן, אפשר לצרף אותו לתצוגה באמצעות קריאה ל-setPlayer:

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

בחירת סוג פלטפורמה

המאפיין surface_type של PlayerView מאפשר להגדיר את סוג המשטח שמשמש להפעלת הסרטון. בנוסף לערכים spherical_gl_surface_view (שזהו ערך מיוחד להפעלת סרטונים גולמיים) ו-video_decoder_gl_surface_view (שזהו ערך לעיבוד וידאו באמצעות מעבדי וידאו של תוספים), הערכים המותרים הם surface_view, ‏ texture_view ו-none. אם התצוגה מיועדת להפעלת אודיו בלבד, כדאי להשתמש ב-none כדי להימנע מהצורך ליצור משטח, כי הפעולה הזו עשויה להיות יקרה.

אם התצוגה מיועדת להפעלת סרטון רגילה, צריך להשתמש ב-surface_view או ב-texture_view. ל-SurfaceView יש כמה יתרונות על פני TextureView להפעלת סרטונים:

  • צריכת אנרגיה נמוכה יותר במכשירים רבים.
  • תזמון מדויק יותר של הפריימים, וכתוצאה מכך הפעלה חלקה יותר של הסרטון.
  • תמיכה בפלט וידאו HDR באיכות גבוהה יותר במכשירים מתאימים.
  • תמיכה בפלט מאובטח כשמפעילים תוכן מוגן DRM.
  • היכולת ליצור עיבוד (רינדור) של תוכן וידאו ברזולוציה המלאה של המסך במכשירי Android TV שמגדילים את הרזולוציה של שכבת ממשק המשתמש.

לכן, כשהדבר אפשרי, עדיף להשתמש ב-SurfaceView במקום ב-TextureView. צריך להשתמש ב-TextureView רק אם SurfaceView לא עונה על הצרכים שלכם. דוגמה אחת לכך היא שבהן נדרשות אנימציות או גלילה חלקה בפני השטח של הסרטון לפני Android 7.0 (רמת API 24), כפי שמתואר בהערות הבאות. במקרה כזה, עדיף להשתמש ב-TextureView רק כאשר הערך של SDK_INT קטן מ-24 (Android 7.0), וב-SurfaceView במקרים אחרים.

ניווט באמצעות לחצן ה-D ב-Android TV

לשלט הרחוק של Android TV יש לחצן D-pad ששולח פקודות שמגיעות כאירוע מפתח ב-dispatchKeyEvent(KeyEvent) של ה-Activity. יש להעניק את ההרשאות הבאות לתצוגת הנגן:

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

חשוב לבקש להעביר את המיקוד לתצוגת הנגן כדי לנווט בלחצני ההפעלה ולדלג על מודעות. כדאי לבקש להתמקד ב-onCreate של ה-Activity:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

אם אתם משתמשים ב-Compose ב-Android TV, תצטרכו להפוך את AndroidView לניתנת לבחירה ולהעביר את האירוע על ידי העברת פרמטר המשתנה ל-AndroidView בהתאם:

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

שינוי של רכיבי drawable

PlayerView משתמש ב-PlayerControlView כדי להציג את פקדי ההפעלה ואת סרגל ההתקדמות. אפשר לשנות את הגדרות ה-drawables שבהם PlayerControlView משתמש באמצעות drawables עם אותם שמות שהוגדרו באפליקציה. ב-Javadoc של PlayerControlView מופיעה רשימה של רכיבי 'control drawable' שאפשר לשנות.

התאמה אישית נוספת

במקרים שבהם נדרשת התאמה אישית מעבר למה שמתואר למעלה, אנחנו מצפים שמפתחי האפליקציות יטמיעו רכיבי ממשק משתמש משלהם במקום להשתמש ברכיבים שסופקו על ידי מודול ממשק המשתמש של Media3.