لوحة عرض دوّارة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تعرِض لوحة العرض الدوّارة قائمة قابلة للتنقّل من العناصر التي تتكيّف ديناميكيًا استنادًا إلى حجم النافذة. استخدِم لوحات العرض الدوّارة لعرض مجموعة من المحتوى ذي الصلة. تُبرز عناصر لوحة العرض الدوّارة العناصر المرئية، ولكن يمكن أن تحتوي أيضًا على نص موجز يتلاءم مع حجم العنصر.

تتوفّر أربعة تصاميم للمنظّمات الدوّارة تناسب حالات الاستخدام المختلفة:

• التصفّح المتعدّد: يتضمّن عناصر مختلفة الأحجام. يُنصح باستخدامها لتصفّح العديد من العناصر في الوقت نفسه، مثل الصور.
• غير محصور: يحتوي على عناصر بحجم واحد وتتجاوز حدود الشاشة. يمكن تخصيصها لعرض المزيد من النص أو واجهة مستخدم أخرى أعلى أو أسفل كل عنصر.
• الصورة الرئيسية: تسلّط الضوء على صورة كبيرة واحدة للتركيز عليها، كما تقدّم لمحة عن المحتوى التالي باستخدام عنصر صغير. يُنصح باستخدام هذا الخيار لإبراز المحتوى الذي تريد التركيز عليه، مثل الصور المصغّرة للأفلام أو البرامج.
• ملء الشاشة: تعرِض هذه الطريقة عنصرًا كبيرًا واحدًا من الحافة إلى الحافة في كل مرة، ويمكنك التمرير عموديًا. يُنصح باستخدام هذا التنسيق للمحتوى الأطول من عرضه.

توضّح لك هذه الصفحة كيفية تنفيذ تنسيقَي لوحة العرض الدوّارة المتعدّدة التصفّح والغير محصورة. اطّلِع على إرشادات 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 تنسيق العرض الإعلاني على شكل لوحة دوّارة.
  • تُحدِّد المَعلمة itemWidth عرضًا ثابتًا لكل عنصر في لوحة العرض الدوّارة.

النتيجة

تعرض الصورة التالية النتيجة من المقتطف السابق: