מערכת Android מפעילה מגוון רחב של גורמי צורה מעבר לסמארטפונים רגילים לאורך, כולל מכשירים מתקפלים, טאבלטים, סביבות של ממשק מחשב ומסכים חיצוניים. אם מניחים שהגיאומטריה של המסך סטטית, תוכן המדיה עלול להימתח, להיחתך או להופיע עם פסים שחורים בצדדים באופן לא מכוון. האפליקציה צריכה להתאים את עצמה באופן דינמי ליחסי גובה-רוחב שונים של מדיה (מ-4:3 הקלאסי ועד למסך רחב במיוחד) במצבי תצוגה שונים.
רוב הכשלים בפריסת המדיה ב-Jetpack Compose נובעים משלוש בעיות נפוצות בארכיטקטורה:
- טיפול לא עקבי ב-window inset והתנגשויות מקצה לקצה.
- עדכוני פריסה לא עקביים בגלל חישוב שגוי של גודל החלון.
- הגדרה שגויה של אפשרויות התאמת התוכן.
במדריך הזה נסביר על אסטרטגיות ושיטות מומלצות לטיפול בכל אחד מהתחומים האלה באמצעות Media3 ו-Jetpack Compose.
איך מטפלים בהתנגשויות בין הוספות לחלונות לבין פריסה מקצה לקצה
במכשירים עם Android 15 (רמת API 35) ומעלה, אפליקציות שמטרגטות לרמת API 35 ומעלה מוצגות מקצה לקצה כברירת מחדל. סרגלי מידע כמו שורת הסטטוס, סרגל הניווט ושורת הכותרת של המחשב מוצגים מעל התוכן של האפליקציה, ומגרעות במסך יכולות להסתיר חלקים ממנו.
בלי ניהול נכון של הוספת חלונות, מתרחשות שתי התנגשויות פריסה עיקריות:
- חפיפה עם סרגל המידע: הפריימים של הסרטון, הכתוביות ורכיבי ה-UI להפעלה מוסתרים חלקית על ידי שורת הסטטוס (שעון, סמלי סוללה), סרגל התנועות או סרגל הניווט, או המגרעות במסך (מגרעות המצלמה). הוראות כלליות להגדרה מפורטות במאמר הגדרה מקצה לקצה.
- הפרעה של סרגל הכותרת בממשק המחשב: במצב ממשק מחשב, המערכת מציגה סרגל כותרת עליון לניהול החלונות. בפריסות רגילות שמעבדות כותרות בהתאמה אישית או אזורי מדיה מקצה לקצה בלי להביא בחשבון את סרגל הכותרת הזה, הפריימים של הסרטון ורכיבי ה-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 ) ), ) }, ) }
הגדרות של מודעות במסך מלא (לאורך ולרוחב)
במצב אימרסיבי במסך מלא, המטרה היא להגדיל את אזור התצוגה כדי ליצור חוויה קולנועית, תוך שמירה על הגישה לרכיבי ה-UI להפעלה:
- מחילים את
windowInsetsPaddingעל שכבות-על של ממשק השליטה במדיה (כמו אמצעי הבקרה העליונים והתחתונים) כדי למנוע מהן לחפוף למגרעות במסך או לאזורים של תנועות מובנות במערכת (לדוגמה, שילוב שלWindowInsets.displayCutoutעםWindowInsets.systemGesturesבאמצעי הבקרה התחתונים כדי שסרגל הדילוג לא יתנגש עם תנועות החלקה בקצה). - מסתירים את סרגלי המידע באמצעות
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) ), ) }, ) }
חישוב עדכונים דינמיים של גודל החלון והפריסה
אם מחשבים את רוחב או גובה המסך רק פעם אחת כשהאפליקציה מופעלת, הפריסות מסתמכות על ערכים לא עדכניים כשתצורת המכשיר משתנה – למשל כשפותחים מכשיר מתקפל, משנים את הגודל של סשן ריבוי חלונות או מסובבים את המסך.
במקרים כאלה, גם אם רכיב צאצא משתמש נכון ב-Modifier.fillMaxWidth(), הוא לא יצליח להתאים את עצמו אם מאגר ההורה שלו מוגבל על ידי מידות לא עדכניות, מה שיגרום למתיחה, לחיתוך או לפריסות שלא מגיבות.
בדוגמה הבאה, המסגרת השמאלית ממחישה רינדור נכון באזור תצוגה רגיל, והמסגרת הימנית ממחישה את הכישלון של התאמת מידות החלון הישנות כשהמכשיר נפתח, וכתוצאה מכך פריסת התוכן לא רספונסיבית.
כדי למנוע אילוצים מיושנים של פריסה, השתמשו ב-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() } } } }
הגדרת קנה המידה ויחסי הגובה-רוחב של התוכן
הבחינו בין ניהול השטח הזמין של מאגר התוכן לבין שינוי קנה המידה של תוכן המדיה עצמו. כדי להגדיר את גבולות הקונטיינר ביחס לסרגלי המידע ולמגרעות במסך, השתמשו בניהול הוספות, כמו ריפוד של אזור בטוח. לאחר מכן, מיישמים אסטרטגיות התאמה לעומס בתוך הגבולות האלה. במאמר מבנה והרכב התוכן מוסבר איך לעצב את מבנה הקונטיינרים ולהתאים את התוכן החזותי ליחסי גובה-רוחב שונים.
בדוגמה הבאה, התמונה משמאל מראה איך אסטרטגיית חיתוך יכולה לחתוך תוכן כשנדרשת חשיפה מלאה, והתמונה מימין מראה איך אסטרטגיית התאמה שומרת על יחס הגובה-רוחב המקורי לעיבוד של פריים מלא.
רכיבי 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 באמצעות תנועת צביטה לשינוי מרחק התצוגה או תנועות אחרות עם מגע במספר נקודות, בדומה לאפליקציות מודרניות של סטרימינג של וידאו.
@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 למדיה עם מידע חיוני בשוליים, כמו תוצאות של משחקי ספורט או כתוביות, כדי לשמור על ההקשר החזותי החיוני.