קרוסלה

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

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

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

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

פלטפורמת ה-API

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

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

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

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

תוצאה

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