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

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

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

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

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

النتيجة

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