קרוסלה

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

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

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

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

פלטפורמת ה-API

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

• ‫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 מספק תיאור נגישות לתמונה.

תוצאה

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

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

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

@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 יוצר את פריסת הקרוסלה.
  • הפרמטר itemWidth מגדיר רוחב קבוע לכל פריט בקרוסלה.

תוצאה

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