התאמת תוכן מדיה לגורמי צורה שונים

מערכת Android מפעילה מגוון רחב של גורמי צורה מעבר לסמארטפונים רגילים לאורך, כולל מכשירים מתקפלים, טאבלטים, סביבות של ממשק מחשב ומסכים חיצוניים. אם מניחים שהגיאומטריה של המסך סטטית, תוכן המדיה עלול להימתח, להיחתך או להופיע עם פסים שחורים בצדדים באופן לא מכוון. האפליקציה צריכה להתאים את עצמה באופן דינמי ליחסי גובה-רוחב שונים של מדיה (מ-4:3 הקלאסי ועד למסך רחב במיוחד) במצבי תצוגה שונים.

רוב הכשלים בפריסת המדיה ב-Jetpack Compose נובעים משלוש בעיות נפוצות בארכיטקטורה:

  • טיפול לא עקבי ב-window inset והתנגשויות מקצה לקצה.
  • עדכוני פריסה לא עקביים בגלל חישוב שגוי של גודל החלון.
  • הגדרה שגויה של אפשרויות התאמת התוכן.

במדריך הזה נסביר על אסטרטגיות ושיטות מומלצות לטיפול בכל אחד מהתחומים האלה באמצעות Media3 ו-Jetpack Compose.

איך מטפלים בהתנגשויות בין הוספות לחלונות לבין פריסה מקצה לקצה

במכשירים עם Android 15 (רמת API‏ 35) ומעלה, אפליקציות שמטרגטות לרמת API‏ 35 ומעלה מוצגות מקצה לקצה כברירת מחדל. סרגלי מידע כמו שורת הסטטוס, סרגל הניווט ושורת הכותרת של המחשב מוצגים מעל התוכן של האפליקציה, ומגרעות במסך יכולות להסתיר חלקים ממנו.

בלי ניהול נכון של הוספת חלונות, מתרחשות שתי התנגשויות פריסה עיקריות:

  • חפיפה עם סרגל המידע: הפריימים של הסרטון, הכתוביות ורכיבי ה-UI להפעלה מוסתרים חלקית על ידי שורת הסטטוס (שעון, סמלי סוללה), סרגל התנועות או סרגל הניווט, או המגרעות במסך (מגרעות המצלמה). הוראות כלליות להגדרה מפורטות במאמר הגדרה מקצה לקצה.
  • הפרעה של סרגל הכותרת בממשק המחשב: במצב ממשק מחשב, המערכת מציגה סרגל כותרת עליון לניהול החלונות. בפריסות רגילות שמעבדות כותרות בהתאמה אישית או אזורי מדיה מקצה לקצה בלי להביא בחשבון את סרגל הכותרת הזה, הפריימים של הסרטון ורכיבי ה-UI העליונים להפעלה מוסתרים ואי אפשר ללחוץ עליהם. למידע נוסף על מצבי חלונות, ראו תמיכה בממשק מחשב.
שורת הסטטוס של המערכת חופפת לקנבס המדיה מקצה לקצה ולרכיבי ה-UI להפעלה. סרגל הניווט באמצעות תנועות חופף לאזור המדיה מקצה לקצה. סרגל הכתוביות במחשב חופף לרכיבי ה-UI העליונים להפעלה.
תרשים 1. שורת הסטטוס של המערכת, סרגל הניווט באמצעות תנועות ושורת הכיתוב בשולחן העבודה חופפים לאזור המדיה מקצה לקצה ומסתירים את קטע הווידאו ואת רכיבי ה-UI להפעלה.

אסטרטגיות לניהול חרקים

האפליקציה צריכה להתאים באופן דינמי לתוספות המערכת, בהתאם למצב של הנגן – מצב אימרסיבי או לא אימרסיבי.

הגדרות לא עשירות

בהפעלה לא מקיפה, סרגלי המידע נשארים גלויים כדי לשמור על ההקשר של המכשיר.

כשהנגן מגיע עד לקצוות החלון, צריך להחיל את windowInsetsPadding עם WindowInsets.safeDrawing ו-only על כל סרגל בקרה של PlayerDefaults בקצוות שבהם הוא נפגש עם סרגלי המידע או המגרעת במסך (לדוגמה, Top + Horizontal ב-TopControls ו-Bottom + Horizontal ב-BottomControls). כך סרגלי המידע לא יסתירו את הפקדים, ומשטח הסרטון יתפרס על פני כל הקונטיינר.

@Composable
fun NonImmersiveVideoPlayer(
  player: Player,
  showControls: Boolean,
  modifier: Modifier = Modifier,
) {
  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the status bar, caption bar, and display cutout
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(WindowInsetsSides.Top + WindowInsetsSides.Horizontal)
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the navigation bar and display cutout
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(
                WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal
              )
            ),
      )
    },
  )
}

במצב לא אימרסיבי, האפליקציה משלבת ריפוד פנימי של החלון כדי להזיז את התוכן פנימה באופן דינמי.
איור 2. במצב לא אימרסיבי, האפליקציה מוסיפה ריפוד פנימי לחלון כדי להזיז את הפקדים פנימה.

הגדרות של מודעות במסך מלא (לאורך ולרוחב)

במצב אימרסיבי במסך מלא, המטרה היא להגדיל את אזור התצוגה כדי ליצור חוויה קולנועית, תוך שמירה על הגישה לרכיבי ה-UI להפעלה:

  1. מחילים את windowInsetsPadding על שכבות-על של ממשק השליטה במדיה (כמו אמצעי הבקרה העליונים והתחתונים) כדי למנוע מהן לחפוף למגרעות במסך או לאזורים של תנועות מובנות במערכת (לדוגמה, שילוב של WindowInsets.displayCutout עם WindowInsets.systemGestures באמצעי הבקרה התחתונים כדי שסרגל הדילוג לא יתנגש עם תנועות החלקה בקצה).
  2. מסתירים את סרגלי המידע באמצעות WindowInsetsControllerCompat בתוך DisposableEffect, כדי לוודא שהניראות של ממשק המשתמש של המערכת משוחזרת כשיוצאים מה-composable.

@Composable
fun ImmersiveVideoPlayer(player: Player, showControls: Boolean, modifier: Modifier = Modifier) {
  val view = LocalView.current

  // Manages the system UI lifecycle to create an edge-to-edge cinematic experience
  DisposableEffect(view) {
    // Finds the hosting Activity, unwrapping any ContextWrapper around the view's context
    val activity =
      generateSequence(view.context) { (it as? ContextWrapper)?.baseContext }
        .filterIsInstance<Activity>()
        .firstOrNull()
    val window = activity?.window ?: return@DisposableEffect onDispose {}
    val controller = WindowCompat.getInsetsController(window, view)

    // Records the current system bar state so it can be restored on dispose
    val insets = ViewCompat.getRootWindowInsets(view)
    val wereSystemBarsVisible =
      insets == null ||
        insets.isVisible(WindowInsetsCompat.Type.statusBars()) ||
        insets.isVisible(WindowInsetsCompat.Type.navigationBars())
    val previousBehavior = controller.systemBarsBehavior

    // Hides status bars, navigation bars, and caption bars to maximize the video canvas
    controller.hide(WindowInsetsCompat.Type.systemBars())

    // Allows hidden system bars to temporarily reappear with a swipe gesture from the edge
    controller.systemBarsBehavior =
      WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

    onDispose {
      // Restores the previous system bar state when leaving the composable
      controller.systemBarsBehavior = previousBehavior
      if (wereSystemBarsVisible) {
        controller.show(WindowInsetsCompat.Type.systemBars())
      }
    }
  }

  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the display cutout while the system bars are hidden
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout.only(
                WindowInsetsSides.Top + WindowInsetsSides.Horizontal
              )
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the display cutout and system gesture areas
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout
                .union(WindowInsets.systemGestures)
                .only(WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal)
            ),
      )
    },
  )
}

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

חישוב עדכונים דינמיים של גודל החלון והפריסה

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

במקרים כאלה, גם אם רכיב צאצא משתמש נכון ב-Modifier.fillMaxWidth(), הוא לא יצליח להתאים את עצמו אם מאגר ההורה שלו מוגבל על ידי מידות לא עדכניות, מה שיגרום למתיחה, לחיתוך או לפריסות שלא מגיבות.

בדוגמה הבאה, המסגרת השמאלית ממחישה רינדור נכון באזור תצוגה רגיל, והמסגרת הימנית ממחישה את הכישלון של התאמת מידות החלון הישנות כשהמכשיר נפתח, וכתוצאה מכך פריסת התוכן לא רספונסיבית.

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

כדי למנוע אילוצים מיושנים של פריסה, השתמשו ב-Jetpack Media Query API. מכיוון שה-API הזה ניסיוני ומושבת כברירת מחדל, קודם צריך להפעיל את הפונקציה mediaQuery על ידי הגדרת ComposeUiFlags.isMediaQueryIntegrationEnabled = true (לדוגמה, לפני שקוראים ל-setContent), ולהביע הסכמה באמצעות @OptIn(ExperimentalMediaQueryApi::class).

כדאי להשתמש ב-derivedMediaQuery כדי להעריך את התנאים של גודל החלון הנוכחי, כמו windowWidth, כדי שהפריסה תתעדכן כשהחלון משתנה בלי ליצור קומפוזיציות מחדש שלא לצורך. אתם יכולים לשלב את derivedMediaQuery עם נקודות עצירה של WindowSizeClass כדי לעבור בין פריסות של חלונית אחת לכמה חלוניות בנגן כשהחלון מתרחב:

@OptIn(ExperimentalMediaQueryApi::class)
@Composable
fun AdaptiveVideoPlayerScreen(
  player: Player,
  modifier: Modifier = Modifier,
  relatedContent: @Composable () -> Unit,
) {
  val isWideWindow by derivedMediaQuery {
    windowWidth >= WindowSizeClass.WIDTH_DP_MEDIUM_LOWER_BOUND.dp
  }

  if (isWideWindow) {
    // Medium or expanded width: place the player alongside a details or playlist pane
    Row(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.weight(0.65f).fillMaxHeight())
      Box(modifier = Modifier.weight(0.35f).fillMaxHeight()) { relatedContent() }
    }
  } else {
    // Compact width: stack a 16:9 player above the details pane
    Column(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.fillMaxWidth().aspectRatio(16f / 9f))
      Box(modifier = Modifier.weight(1f).fillMaxWidth()) { relatedContent() }
    }
  }
}

הגדרת קנה המידה ויחסי הגובה-רוחב של התוכן

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

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

אסטרטגיית החיתוך גורמת לאובדן תוכן משמעותי כשנדרשת חשיפה מלאה. אסטרטגיית התאמה ששומרת על יחס הגובה-רוחב המקורי לעיבוד של פריים מלא.
איור 5. השוואה בין התנהגויות של התאמה לעומס.

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

כשמציגים סרטון בפורמט 16:9 במסך בפורמט 4:3 או סרטון בפורמט 4:3 במסך בפורמט 16:9, ברירת המחדל של הרכיב הניתן לקישור Player היא ContentScale.Fit. כך הסרטון המלא מוצג בלי חיתוך, באמצעות הוספת פסים שחורים למעלה ולמטה או בצדדים.

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

הטמעות לדוגמה

אפשר לאכוף חשיפה של פריים מלא ולטפל ביחסי גובה-רוחב באמצעות מאפייני ContentScale רגילים של Compose.

שימוש ברכיב הקומפוזבילי Player

הדרך הכי פשוטה וישירה היא להשתמש ב-composable‏ Player. הוא משמש כמעטפת ברמה גבוהה שמטפלת באופן אוטומטי בגבולות קנה המידה, ומשלב ContentFrame לעיבוד וידאו עם שכבות-על של פקדים שניתן להתאים אישית (topControls,‏ centerControls,‏ bottomControls) ושכבת תריס:

@Composable
fun FitVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  Player(
    player = player,
    modifier = modifier.fillMaxSize(), // Fill the available space
    contentScale = ContentScale.Fit, // Default; shown for clarity
  )
}

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

מתג להחלפת מצב של התאמה דינמית לעומס בשליטת המשתמש

כדי לשפר את חוויית הצפייה באפליקציה, אתם יכולים להוסיף מתג אופציונלי למעבר בין אפשרויות שונות של שינוי קנה המידה של התוכן. כשמזהים תנועת הקשה כפולה, אפשר להחליף באופן מיידי את מצב הנגן בין ContentScale.Fit ל-ContentScale.Crop. אפשר גם להרחיב את הפונקציונליות הזו כדי לתמוך בהתאמות דינמיות של ContentScale באמצעות תנועת צביטה לשינוי מרחק התצוגה או תנועות אחרות עם מגע במספר נקודות, בדומה לאפליקציות מודרניות של סטרימינג של וידאו.

איור 6. מעבר בין ContentScale.Fit ל-ContentScale.Crop.

@Composable
fun ZoomableVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  var isCropped by rememberSaveable { mutableStateOf(false) }

  Player(
    player = player,
    modifier =
      modifier
        .fillMaxSize()
        // Handle double-tap to toggle between Fit and Crop scaling
        .pointerInput(Unit) { detectTapGestures(onDoubleTap = { isCropped = !isCropped }) },
    contentScale = if (isCropped) ContentScale.Crop else ContentScale.Fit,
  )
}

יש כמה אפשרויות לשינוי קנה המידה של התוכן, אבל כדאי לבחור את האפשרות המתאימה לפי תרחיש השימוש: השתמשו ב-ContentScale.Crop לסרטונים קצרים או לפידים שאפשר לגלול בהם, כשהמטרה העיקרית היא למלא את המסך. השתמשו בברירת המחדל ContentScale.Fit למדיה עם מידע חיוני בשוליים, כמו תוצאות של משחקי ספורט או כתוביות, כדי לשמור על ההקשר החזותי החיוני.