چرخ فلک

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

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

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

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

سطح API

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

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

این composableها در نحوه تعیین اندازه آیتم متفاوت هستند:

• itemWidth (برای HorizontalUncontainedCarousel ): عرض دقیق هر آیتم در یک carousel بدون محدودیت را مشخص می‌کند.
• preferredItemWidth (برای HorizontalMultiBrowseCarousel ): عرض ایده‌آل برای آیتم‌ها در یک carousel چندمروری را پیشنهاد می‌دهد و به کامپوننت اجازه می‌دهد در صورت وجود فضا، چندین آیتم را نمایش دهد.

مثال: چرخ فلک چندمروری

این قطعه کد یک چرخ و فلک چندمروری را پیاده‌سازی می‌کند:

@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 تعریف می‌کند که داده‌ها را برای هر عنصر در carousel ساختاردهی می‌کند.
• List از اشیاء CarouselItem را که با منابع تصویر و توضیحات پر شده‌اند، ایجاد و به خاطر می‌سپارد.
• از ترکیب‌بندی HorizontalMultiBrowseCarousel استفاده می‌کند که برای نمایش چندین آیتم در یک چرخ‌وفلک طراحی شده است.
  • وضعیت چرخ فلک با استفاده از rememberCarouselState مقداردهی اولیه می‌شود که تعداد کل آیتم‌ها را دریافت می‌کند.
  • آیتم‌ها یک preferredItemWidth دارند (در اینجا، 186.dp )، که عرض بهینه برای هر آیتم را پیشنهاد می‌دهد. چرخ فلک از این برای تعیین اینکه چند آیتم می‌توانند همزمان روی صفحه نمایش داده شوند، استفاده می‌کند.
  • پارامتر itemSpacing یک فاصله کوچک بین آیتم‌ها ایجاد می‌کند.
  • لامبدا انتهایی HorizontalMultiBrowseCarousel روی CarouselItems تکرار می‌شود. در هر تکرار، آیتم موجود در اندیس i را بازیابی کرده و یک Image قابل ترکیب برای آن رندر می‌کند.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) یک ماسک شکل از پیش تعریف شده را به هر تصویر اعمال می‌کند و به آن گوشه‌های گرد می‌دهد.
  • contentDescription توضیحاتی در مورد دسترسی‌پذیری تصویر ارائه می‌دهد.

نتیجه

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

مثال: چرخ فلک بدون محدودیت

قطعه کد زیر یک چرخ فلک بدون کنترل (uncontained carousel) پیاده‌سازی می‌کند:

@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 طرح‌بندی carousel را ایجاد می‌کند.
  • پارامتر itemWidth برای هر آیتم در carousel یک عرض ثابت تعیین می‌کند.

نتیجه

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

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

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

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

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

سطح API

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

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

این composableها در نحوه تعیین اندازه آیتم متفاوت هستند:

• itemWidth (برای HorizontalUncontainedCarousel ): عرض دقیق هر آیتم در یک carousel بدون محدودیت را مشخص می‌کند.
• preferredItemWidth (برای HorizontalMultiBrowseCarousel ): عرض ایده‌آل برای آیتم‌ها در یک carousel چندمروری را پیشنهاد می‌دهد و به کامپوننت اجازه می‌دهد در صورت وجود فضا، چندین آیتم را نمایش دهد.

مثال: چرخ فلک چندمروری

این قطعه کد یک چرخ و فلک چندمروری را پیاده‌سازی می‌کند:

@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 تعریف می‌کند که داده‌ها را برای هر عنصر در carousel ساختاردهی می‌کند.
• List از اشیاء CarouselItem را که با منابع تصویر و توضیحات پر شده‌اند، ایجاد و به خاطر می‌سپارد.
• از ترکیب‌بندی HorizontalMultiBrowseCarousel استفاده می‌کند که برای نمایش چندین آیتم در یک چرخ‌وفلک طراحی شده است.
  • وضعیت چرخ فلک با استفاده از rememberCarouselState مقداردهی اولیه می‌شود که تعداد کل آیتم‌ها را دریافت می‌کند.
  • آیتم‌ها یک preferredItemWidth دارند (در اینجا، 186.dp )، که عرض بهینه برای هر آیتم را پیشنهاد می‌دهد. چرخ فلک از این برای تعیین اینکه چند آیتم می‌توانند همزمان روی صفحه نمایش داده شوند، استفاده می‌کند.
  • پارامتر itemSpacing یک فاصله کوچک بین آیتم‌ها ایجاد می‌کند.
  • لامبدا انتهایی HorizontalMultiBrowseCarousel روی CarouselItems تکرار می‌شود. در هر تکرار، آیتم موجود در اندیس i را بازیابی کرده و یک Image قابل ترکیب برای آن رندر می‌کند.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) یک ماسک شکل از پیش تعریف شده را به هر تصویر اعمال می‌کند و گوشه‌های آن را گرد می‌کند.
  • contentDescription توضیحاتی در مورد دسترسی‌پذیری تصویر ارائه می‌دهد.

نتیجه

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

مثال: چرخ فلک بدون محدودیت

قطعه کد زیر یک چرخ فلک بدون کنترل (uncontained carousel) پیاده‌سازی می‌کند:

@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 طرح‌بندی carousel را ایجاد می‌کند.
  • پارامتر itemWidth برای هر آیتم در carousel یک عرض ثابت تعیین می‌کند.

نتیجه

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