קרוסלה

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

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

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

בדף הזה מוסבר איך להטמיע את פריסות הקרוסלה של כמה דפדפנים ושל קרוסלה לא מוגבלת. מידע נוסף על סוגי הפריסות מופיע בהנחיות לשימוש בקרוסלה ב-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 מגדיר רוחב קבוע לכל פריט בקרוסלה.

התוצאה

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