معرض متحرك
Carouselعرض شرائح متاح الوصول في React يدعم الأسهم، النقاط، لوحة المفاتيح، السحب، والتكرار، ويتبع نموذج الدور carousel مع إعلانات حية. تنقل يراعي الاتجاه من اليمين إلى اليسار.
يعرض Carousel شريحة واحدة في كل مرة داخل CarouselViewport. يعمل التنقل بالأسهم، النقاط، لوحة المفاتيح، والسحب. أضف loop للعودة إلى الشريحة الأولى بعد الأخيرة.
متى تستخدمه
استخدم Carousel لمجموعة صغيرة من الشرائح المتساوية الأهمية، مثل الخدمات المميزة أو الإعلانات في صفحة البوابة الرئيسية. اكتف بعدد قليل من الشرائح، ولا تشغل تلقائياً أي محتوى يحتاج المستخدم إلى قراءته.
إذا احتاج المستخدم إلى مقارنة العناصر، تناسبه الشبكة أكثر من عرض الشرائح.
أمثلة
الخصائص
الخصائص التي يعرفها Carousel. سمات العنصر الأصلي تمر كما هي.
<Carousel>
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
index | number | Controlled active index (a slide, or a page when slideSize is set). | |
defaultIndex | number | Uncontrolled initial index. Defaults to 0. | |
onIndexChange | (index: number) => void | Fires with the new index on any navigation. | |
controls | "both" | "dots" | "arrows" | Which controls to lay out: dots below, arrows flanking, or both. | |
loop | boolean | Wrap past the ends instead of stopping. | |
dotSize | DotSize | Dot indicator diameter: sm 8 · md 12 · lg 16 px. | |
arrowStyle | ArrowStyle | Arrow button style: filled green primary, transparent subtle, or the square gray neutral (SDGA Button Neutral). | |
arrowSize | ArrowSize | Arrow button diameter: sm 32 · md 40 · lg 48 px. | |
swipe | boolean | Enable pointer/touch swipe to navigate. Defaults to true. | |
autoplay | boolean | Auto-advance (house extension; pauses on hover/focus + reduced-motion). | |
autoplayInterval | number | Auto-advance interval in ms. Defaults to 5000. | |
slideSize | string | Fixed inline size of every slide (any CSS length). Switches to page-based navigation: the viewport shows as many whole slides as fit, and arrows/dots move one page at a time. Without it, each slide fills the viewport. | |
gap | string | Space between slides (any CSS length). Defaults to 0. | |
align | "center" | "start" | Where the active page sits when slides don't fill the viewport; center lets the neighbours peek at both edges. | |
flush | boolean | Drop the SDGA shell padding (inline 24 / block 32) so the carousel sits flush in its container. | |
arrowGap | string | Space between the arrows and the viewport (flank, SDGA 44px) or their inset from its edges (overlay, 0). | |
arrowPlacement | "overlay" | "flank" | flank (default) lays the arrows out beside the viewport; overlay floats them over its edges. | |
announce | (index: number, count: number) => string | Builds the screen-reader announcement after navigation (a visually hidden status). Defaults to Slide {n} of {m}. |
<CarouselSlide>
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
index | number | 0-based position - injected by CarouselViewport. |
<CarouselNav>
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
label | string | Accessible label for the icon-only button. | |
asChild | boolean | Compose with a custom element (e.g. a router link) via Radix Slot. | |
children | react.ReactNode | Override the default chevron glyph. |
<CarouselDots>
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
bare | boolean | Drop the pill padding (SDGA "Dots Only"). | |
dotLabel | (index: number, count: number) => string | Build each dot's accessible label. Defaults to Go to slide {n}. |
إمكانية الوصول
يعرض Carousel role="region" مع aria-roledescription="carousel"، وتحمل كل شريحة role="group" مع وصف شريحة. ينتقل مفتاحا السهم الأيسر والأيمن بين الشرائح، وينتقل Home وEnd إلى الشريحة الأولى والأخيرة. تحمل الشرائح غير النشطة السمة inert، لذا لا يمكن التركيز على المحتوى المخفي.
يعلن Carousel تغييرات الشرائح بهدوء، وتحمل النقطة الحالية aria-current. ولزري السابق والتالي أسماء متاحة الوصول.