گردونه

گردونه فهرستی پیمایش‌شدنی از مواردی را نمایش می‌دهد که به‌صورت پویا براساس اندازه پنجره تطبیق داده می‌شوند. از گردونه‌ها برای نمایش مجموعه‌ای از محتوای مرتبط استفاده کنید. عناصر گردونه بر تصاویر تأکید دارند، اما می‌توانند حاوی نوشتار کوتاهی باشند که با اندازه عنصر تطبیق پیدا می‌کند.

چهار چیدمان گردونه برای مطابقت با موارد استفاده مختلف دردسترس است:

• مرور چندگانه: شامل موارد با اندازه‌های مختلف است. برای مرور هم‌زمان موارد زیاد، مثل عکس‌ها، توصیه می‌شود.
• بدون قاب: شامل مواردی است که اندازه یکسانی دارند و از لبه صفحه به‌سمت بیرون جریان می‌یابند. می‌تواند سفارشی‌سازی شود تا نوشتار بیشتر یا دیگر عناصر رابط کاربری را در بالا یا پایین هر مورد نشان دهد.
• قهرمان: یک تصویر بزرگ را برای تمرکز برجسته می‌کند و با یک مورد کوچک، نگاهی اجمالی به آنچه در ادامه می‌آید ارائه می‌دهد. برای برجسته کردن محتوایی که می‌خواهید تأکید کنید، مانند ریزعکس‌های فیلم یا نمایش، توصیه می‌شود.
• تمام‌صفحه: هر بار یک مورد بزرگ لبه‌به‌لبه را نشان می‌دهد و به‌صورت عمودی پیمایش می‌کند. برای محتوایی که ارتفاع آن بیشتر از عرض آن است توصیه می‌شود.

این صفحه نحوه پیاده‌سازی چیدمان‌های مرور چندگانه و گردونه بدون محدودیت را به شما نشان می‌دهد. برای اطلاعات بیشتر درباره انواع چیدمان، رهنمودهای «ماده ۳ گردونه‌ای» را ببینید.

سطح میانای برنامه‌سازی کاربردی

برای پیاده‌سازی مرور چندگانه و گردونه‌های بدون محدودیت، از HorizontalMultiBrowseCarousel و 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 فاصله کوچکی بین موارد اضافه می‌کند.
  • لامبدای انتهایی 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 عرض ثابتی را برای هر عنصر در گردونه تنظیم می‌کند.

نتیجه

تصویر زیر نتیجه را از گلچین قبلی نشان می‌دهد: