الأكورديون
أسئلة تُفتح لتظهر إجاباتها، فتبقى صفحات المساعدة والإعدادات الطويلة قصيرة. يفتح الناس ما يحتاجونه فقط.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add accordionويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/accordionالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { Accordion, AccordionItem } from "@/components/ui/accordion";<Accordion divider> <AccordionItem value="refund" question="How long does a refund take?"> Most refunds reach your account within five working days. </AccordionItem></Accordion>أمثلة
قسم واحد في كل مرة
multiple={false}: فتح قسم يغلق الآخر. يناسب الإعدادات، أما الأسئلة الشائعة فاتركها تُفتح معًا لأن الناس يقارنون الإجابات.
الجوال والأيقونة في البداية
breakpoint="mobile" يصغّر الأسئلة إلى body-16 والمسافة إلى 8 بكسل، وiconPosition="start" يضع الأيقونة قبل السؤال. الإعدادان على القائمة كلها فلا يختلف عنصر عن آخر. الافتراضي auto: جوال تحت md وسطح مكتب فوقه.
الفتح من رابط
ابدأ والعناصر مغلقة، وافتح العنصر الذي يشير إليه الرابط بالتحكم في value. والبحث في الصفحة يفتح الإجابة المغلقة التي فيها النص: ابحث عن IBAN.
مرجع الخصائص
Accordion
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
multiple | boolean | true | فتح عدة عناصر معًا؛ false لعنصر واحد. |
defaultValue | string[] | لا يوجد | العناصر المفتوحة في البداية. |
value / onValueChange | string[] | لا يوجد | للتحكم في العناصر المفتوحة. |
breakpoint | "auto" | "desktop" | "mobile" | "auto" | خاصية Breakpoint للقائمة كلها. |
iconPosition | "end" | "start" | "end" | خاصية Icon position للقائمة كلها. |
divider | boolean | false | خاصية Divider: خط فوق كل عنصر. |
AccordionItem
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
question | ReactNode | لا يوجد | خاصية Question: زر داخل عنوان. |
children | ReactNode | لا يوجد | خاصية Answer: فقرة قصيرة أو قائمة أو رابط. |
value | string | لا يوجد | معرّف العنصر في value. |
id | string | لا يوجد | لروابط # إلى العنصر. |
icon | boolean | true | خاصية Icon: أيقونة الزائد والناقص. |
headingLevel | 2 | 3 | 4 | 5 | 6 | 3 | مستوى العنوان حول السؤال. |
disabled | boolean | false | يمنع الفتح والإغلاق. |
إرشادات الاستخدام
الأكورديون يُخفي تفاصيل لا يحتاجها إلا بعض الناس. هنا: الأكورديون أم القسم القابل للطي أم قسم الأسئلة الشائعة، وكتابة الأسئلة والأجوبة، والفتح والإغلاق، وما تتسع له اللوحة، وانعكاسه في العربية، وما تتحقق منه قبل التسليم.
1. أكورديون أم قسم قابل للطي أم أسئلة شائعة
الأكورديون يُخفي تفاصيل لا يحتاجها إلا بعض الناس. وإن كان الجميع يحتاج إلى المحتوى فاعرضه. واختر الجزء حسب عدد اللوحات ومكانها.
| تحتاج إلى | استخدم | السبب |
|---|---|---|
| الإجابة عن أسئلة كثيرة في مكدّس، تُفتح واحدًا واحدًا | عنصر أكورديون | يمسح الناس الأسئلة ويفتحون سؤالهم فقط. |
| إخفاء كتلة واحدة من تفاصيل اختيارية، مثل الرسوم | قسم قابل للطي | لوحة واحدة بسطر ملخص يبقى ظاهرًا. |
| إضافة كتلة أسئلة شائعة كاملة إلى صفحة تسويقية | قسم الأسئلة الشائعة، أنواع الأكورديون | قسم جاهز بعنوان وأسئلة ورابط تواصل. |
| عرض خمسة أجوبة قصيرة أو أقل | قسم الأسئلة الشائعة، الأنواع البسيطة | الأجوبة القصيرة تُقرأ أسرع وهي مفتوحة كلها. |
| التبديل بين عروض متساوية الوزن | التبويبات | يظهر عرض واحد فقط، ولكل عرض اسم. |
2. كتابة الأسئلة والأجوبة
السؤال هو الشيء الوحيد الذي يراه الناس قبل فتح العنصر، فاكتبه كما يسأله الناس. وأجب في الجملة الأولى، ثم أضف التفاصيل.
أسئلة يطرحها الناس
صفحة مساعدة لمحفظة.
افعل
- اكتب الأسئلة بكلمات الناس: «كم يستغرق التحويل؟»
- أجب عن السؤال في الجملة الأولى.
- الأجوبة فقرة قصيرة أو قائمة قصيرة.
- رتّب الأسئلة حسب عدد مرات طرحها.
تجنّب
- عناوين مواضيع مثل «عام» أو «أخرى» رؤوسًا.
- بدء الجواب بتكرار السؤال.
- إخفاء مقال طويل داخل عنصر واحد؛ اربط إليه.
3. الفتح والإغلاق
صف الرأس كله يفتح العنصر ويغلقه، لا الأيقونة وحدها. والأيقونة تُظهر الحالة: «+» مغلقًا و«−» مفتوحًا. وابدأ بكل العناصر مغلقة، إلا حين يصل الناس من رابط إلى جواب محدد.
افعل
- اجعل صف الرأس كله المحفّز.
- ابدأ مغلقًا؛ وافتح العنصر الذي يشير إليه الرابط.
- اسمح بفتح عدة عناصر معًا في الأسئلة الشائعة.
- أبقِ الأيقونة عند النهاية، في الجهة نفسها في كل عنصر.
- أبقِ العناصر المفتوحة مفتوحة حين يعود الناس إلى الصفحة.
تجنّب
- جعل الأيقونة وحدها قابلة للنقر.
- إغلاق العناصر الأخرى تلقائيًا في الأسئلة الشائعة؛ فالناس يقارنون الأجوبة.
- الجمع بين موضعي الأيقونة عند البداية والنهاية في مكدّس واحد.
- تحريك الفتح والإغلاق لمدة أطول من
duration/moderate.
4. ما تتسع له اللوحة
تحمل اللوحة جوابًا قصيرًا: فقرة، أو قائمة قصيرة، أو رابطًا إلى المزيد. وأبقِ المحتوى المطلوب وحقول النماذج خارج الأكورديون؛ فالناس يتخطون اللوحات المغلقة.
افعل
- ضع فقرة أو قائمة قصيرة أو رابطًا في اللوحة.
- اربط إلى مقال كامل حين يطول الجواب.
- استخدم الفاصل بين العناصر في المكدّس.
تجنّب
- أكورديون داخل أكورديون.
- إخفاء حقول نموذج مطلوبة أو شروط قانونية يجب أن يقرأها الناس.
- وضع الوسيلة الوحيدة لإنهاء مهمة داخل لوحة مغلقة.
5. العربية والاتجاه من اليمين إلى اليسار
استخدم النسخة العربية في العربية. تحاذي الأسئلة والأجوبة اليمين، وتنتقل الأيقونة إلى نهاية السطر، أي اليسار. وأيقونتا «+» و«−» متناظرتان، فلا شيء فيهما ينعكس. وتبقى المبالغ والأوقات في الأجوبة تُقرأ من اليسار إلى اليمين.
الأيقونة عند نهاية السطر
صفحة المساعدة نفسها بالعربية.
قبل التسليم
- الأسئلة مكتوبة كما يسألها الناس.
- حالة الفتح الافتراضية معلَّمة، والروابط العميقة تفتح عنصرها.
- المحتوى الذي يحتاجه الجميع غير مخفي.
- المكدّسات العربية تستخدم النسخة العربية.
- الجوال يستخدم نقطة توقف الجوال.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Tab | من سؤال إلى آخر، ثم إلى روابط الإجابة المفتوحة. |
| EnterSpace | يفتح السؤال أو يغلقه، ويبقى التركيز عليه. |
ARIA
- كل سؤال زر داخل عنوان (
h3افتراضيًا)، فيتنقل قارئ الشاشة بين الأسئلة ويسمع هل كل منها مفتوح. - للزر
aria-expandedوaria-controlsيشير إلى منطقة الإجابة. أيقونة الزائد والناقص زخرفية. - صف السؤال كله هو الزر، ومساحة اللمس 48 بكسل على الأقل.
- الفتح والإغلاق في 200 ملّي ثانية، وفوريان مع تقليل الحركة.
افعل
- زر الرأس داخل عنوان بالمستوى الصحيح.
aria-expandedعلى الزر وaria-controlsيشير إلى لوحته.- مفتاحا Enter وSpace يفتحان العنصر ويغلقانه، ويبقى التركيز على الرأس.
- صف الرأس بارتفاع 48 بكسل على الأقل.
تجنّب
- رؤوس من نص عادي مع معالج نقر.
- الأيقونة وحدها لإظهار الحالة.
ملاحظات العربية والاتجاه
ينعكس
- السؤال والإجابة يبدآن من اليمين، والأيقونة في نهاية السطر، أي على اليسار.
iconPosition="start"يضع الأيقونة على اليمين في العربية.
لا ينعكس
- أيقونتا الزائد والناقص متناظرتان، فلا شيء فيهما ينعكس.
- الأرقام
- المبالغ والأوقات في الإجابات تُقرأ من اليسار إلى اليمين؛ نسّق الأرقام بـ
formatNumber. - الخط العربي
- السؤال
body-18Medium (والجوالbody-16) والإجابةbody-16. الأسطر العربية أعلى، فيطول الصف ولا يُقص. - النص ثنائي الاتجاه
- اكتب الأسئلة العربية كما يسأل الناس بالعربية، لا ترجمة حرفية للإنجليزية.
افعل
- النسخة العربية لكل عنصر في مكدّس عربي.
- الأيقونة عند نهاية السطر، أي على اليسار في العربية.
- اكتب الأسئلة العربية كما يسألها الناس بالعربية.
- أبقِ المبالغ والأوقات والرموز من اليسار إلى اليمين داخل الأجوبة.
تجنّب
- نص عربي في النسخة الإنجليزية.
- ترجمة الأسئلة الإنجليزية كلمة كلمة.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.
- text-align: left مضبوطة صراحة على نص عربي في معظمه
- نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
- حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة
- نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
- تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)