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

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

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

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

توضّح هذه الصفحة كيفية تنفيذ تصاميم لوحات العرض الدوّارة للتصفّح المتعدّد والممتدة خارج الحاوية. راجِع إرشادات 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 عرضًا ثابتًا لكل عنصر في لوحة العرض الدوّارة.

النتيجة

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