معرض متحرّك
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}. |
إمكانية الوصول
يعرض عرض الشرائح role="region" مع aria-roledescription="carousel"، وكل شريحة role="group" بوصف شريحة. ينقل السهمان الأيسر والأيمن بين الشرائح، ويقفز Home وEnd إلى الطرفين، وتُعلّم الشرائح غير النشطة بـ inert فلا يمكن التركيز على محتوى مخفي.
تُعلن تغييرات الشرائح بهدوء، ولزرَي السابق والتالي أسماء متاحة، وتحمل النقطة الحالية aria-current.