چرخ فلک

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

چهار طرح چرخ و فلک برای مناسب با موارد استفاده مختلف وجود دارد:

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

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

سطح API

برای پیاده‌سازی چرخ فلک‌های چند مرورگر و غیرمحدود، از ترکیب‌پذیرهای HorizontalMultiBrowseCarousel و HorizontalUncontainedCarousel استفاده کنید. این ترکیب‌پذیرها پارامترهای کلیدی زیر را به اشتراک می‌گذارند:

• state : یک نمونه CarouselState که فهرست آیتم فعلی و موقعیت اسکرول را مدیریت می کند. این حالت را با استفاده از rememberCarouselState { itemCount } ایجاد کنید، که itemCount تعداد کل موارد در چرخ فلک است.
• itemSpacing : مقدار فضای خالی بین آیتم های مجاور در چرخ فلک را مشخص می کند.
• contentPadding : بالشتک را در اطراف ناحیه محتوای چرخ فلک اعمال می کند. از این برای اضافه کردن فضا قبل از اولین مورد یا بعد از آخرین مورد یا برای ارائه حاشیه برای موارد در منطقه قابل پیمایش استفاده کنید.
• content : یک تابع ترکیبی که یک شاخص عدد صحیح دریافت می کند. از این لامبدا برای تعریف UI برای هر مورد در چرخ فلک بر اساس شاخص آن استفاده کنید.

این ترکیب‌پذیرها در نحوه تعیین اندازه آیتم متفاوت هستند:

• 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 یک عرض ثابت برای هر آیتم در چرخ فلک تعیین می کند.

نتیجه

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