گردونه

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

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

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

شکل ۱. انواع گردونه نامحدود (۱) و تمام‌صفحه (۲).

این صفحه به شما نشان می‌دهد که چگونه طرح‌بندی‌های گردونه چندمروری و نامحدود را پیاده‌سازی کنید. برای اطلاعات بیشتر درباره انواع چیدمان، رهنمودهای Carousel Material 3 را ببینید.

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

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

نتیجه

تصویر زیر نتیجه قطعه کد قبلی را نشان می‌دهد:

شکل ۳.‏ گردونه‌ای بدون محفظه که آخرین مورد در گردونه برش داده نشده است.