קרוסלה

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

יש ארבע פריסות של קרוסלה שמתאימות לתרחישי שימוש שונים:

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

תרשים 1. סוגי קרוסלה לא מוגבלים (1) ומסך מלא (2).

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

פלטפורמת ה-API

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

• ‫state: מופע CarouselState שמנהל את האינדקס של הפריט הנוכחי ואת מיקום הגלילה. יוצרים את המצב הזה באמצעות rememberCarouselState { itemCount }, כאשר itemCount הוא המספר הכולל של הפריטים בקרוסלה.
• ‫itemSpacing: מגדיר את כמות השטח הריק בין פריטים סמוכים בקרוסלה.
• ‫contentPadding: מוסיף ריווח מסביב לאזור התוכן של הקרוסלה. אפשר להשתמש בזה כדי להוסיף רווח לפני הפריט הראשון או אחרי הפריט האחרון, או כדי לספק שוליים לפריטים באזור שאפשר לגלול בו.
• ‫content: פונקציה קומפוזבילית שמקבלת אינדקס של מספר שלם. אפשר להשתמש בפונקציית ה-lambda הזו כדי להגדיר את ממשק המשתמש של כל פריט בקרוסלה על סמך האינדקס שלו.

הפונקציות האלה שונות זו מזו באופן שבו הן מציינות את גודל הפריט:

• ‫itemWidth (עבור HorizontalUncontainedCarousel): מציין את הרוחב המדויק של כל פריט בקרוסלה לא מוגבלת.
• ‫preferredItemWidth (בשביל HorizontalMultiBrowseCarousel): מציע את הרוחב האידיאלי לפריטים בקרוסלה עם כמה פריטים, ומאפשר לרכיב להציג כמה פריטים אם יש מספיק מקום.

דוגמה: קרוסלה עם כמה מוצרים

קטע הקוד הזה מטמיע קרוסלה עם כמה אפשרויות עיון:

@Composable
fun CarouselExample_MultiBrowse() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val items = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalMultiBrowseCarousel(
        state = rememberCarouselState { items.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        preferredItemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = items[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

מידע חשוב על הקוד

• הגדרת CarouselItem מחלקת נתונים, שמבנה את הנתונים של כל רכיב בקרוסלה.
• יוצרת List של CarouselItem אובייקטים ומאכלסת אותם במשאבי תמונות ובתיאורים.
• משתמשים ברכיב הקומפוזבילי HorizontalMultiBrowseCarousel, שמיועד להצגת כמה פריטים בקרוסלה.
  • המצב של הקרוסלה מאותחל באמצעות rememberCarouselState, שמקבל את המספר הכולל של הפריטים.
  • לפריטים יש preferredItemWidth (כאן, 186.dp), שמציין רוחב אופטימלי לכל פריט. הקרוסלה משתמשת בערך הזה כדי לקבוע כמה פריטים יכולים להיכנס למסך בו-זמנית.
  • הפרמטר itemSpacing מוסיף רווח קטן בין הפריטים.
  • ה-lambda האחורי של HorizontalMultiBrowseCarousel חוזר על עצמו ב-CarouselItems. בכל איטרציה, הפונקציה מאחזרת את הפריט באינדקס i ומציגה את הרכיב Image.
  • ‫Modifier.maskClip(MaterialTheme.shapes.extraLarge) מחיל מסכה בצורה מוגדרת מראש על כל תמונה, וכך יוצר פינות מעוגלות.
  • ‫contentDescription מספק תיאור נגישות לתמונה.

תוצאה

בתמונה הבאה מוצגת התוצאה מקטע הקוד הקודם:

איור 2. קרוסלה עם כמה פריטים, כשהפריט האחרון חתוך.

דוגמה: קרוסלה ללא מסגרת

קטע הקוד הבא מטמיע קרוסלה לא מוגבלת:

@Composable
fun CarouselExample() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val carouselItems = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalUncontainedCarousel(
        state = rememberCarouselState { carouselItems.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        itemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = carouselItems[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

מידע חשוב על הקוד

• רכיב ה-HorizontalUncontainedCarousel composable יוצר את פריסת הקרוסלה.
  • הפרמטר itemWidth מגדיר רוחב קבוע לכל פריט בקרוסלה.

תוצאה

בתמונה הבאה מוצגת התוצאה מקטע הקוד הקודם:

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