קרוסלה

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

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

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

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

ממשק API

כדי להטמיע קרוסלות עם גלישה בכמה מוצרים וקרוסלות ללא תוכן, משתמשים ברכיבי ה-Composable‏ 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 מספק תיאור נגישות של התמונה.

התוצאה

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

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

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

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

התוצאה

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