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

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

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

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

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

النتيجة

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