انتقل إلى المحتوى

القائمة المنسدلة

احصل على Ritla UI

حقل لاختيار خيار واحد أو عدة خيارات من قائمة، بتسمية حقل الإدخال وحالاته، وبحث حين تطول القائمة. استخدمها لخمسة خيارات أو أكثر؛ وللأقل أزرار الاختيار أو مربعات التفعيل.

فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:

افتح في Figma

المعاينة

«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.

المعاينةالكود
إنجليزيمعكوسعربي
← RTL

التثبيت

  1. أضف المكوّن

    npx ritla add select

    ويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/select

  2. الاعتماديات التي يضيفها

    @base-ui/react@phosphor-icons/react

  3. أو انسخه يدويًا

    التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.

الاستخدام

select.tsx
import { Select } from "@/components/ui/select";<Select label="Transfer purpose" options={[{ value: "rent", label: "Rent" }, …]} onValueChange={setPurpose} />

أمثلة

الحالات

قائمة قصيرة (5 خيارات) تُفتح بلا بحث. لا تحدد خيارًا مسبقًا إلا إذا كان آمنًا.

إنجليزيمعكوسعربي
← RTL

أيقونة ووصف

icon وdescription لكل خيار، وdisabled لخيار غير متاح. الخيار المختار عليه علامة.

إنجليزيمعكوسعربي
← RTL

اختيار متعدد

MultiSelect: الخيارات المختارة وسوم في الحقل ولكل منها زر حذف، والكتابة في الحقل تصفّي القائمة، والصفوف بمربعات تفعيل وتبقى القائمة مفتوحة حتى «تم».

إنجليزيمعكوسعربي
← RTL

حالات الاختيار المتعدد

بعد maxTags وسوم يلخّص الحقل الباقي («+2 أخرى») حتى تركّز عليه؛ والخطأ والتعطيل كما في حقل الإدخال؛ وonCreate يضيف «إنشاء جديد» بما كتبه الشخص.

إنجليزيمعكوسعربي
← RTL

مرجع الخصائص

Select

الخاصيةالنوعالافتراضيالوصف
labelReactNodeلا يوجدخاصية Show label.
options{ value, label, description?, icon?, disabled? }[]لا يوجدالخيارات.
value / defaultValuestring | nullلا يوجدقيمة الخيار المختار.
onValueChange(value: string | null) => voidلا يوجدعند الاختيار.
searchablebooleanoptions ≥ 8مربع البحث في أعلى القائمة.
placeholder / searchPlaceholder / emptyTextstringلا يوجدالافتراضي بلغة الصفحة («اختر خيارًا»، «بحث»، «لا توجد نتائج»).
namestringلا يوجداسم الحقل في النموذج.
required / helperText / error / disabled…لا يوجدكما في حقل الإدخال.

MultiSelect

الخاصيةالنوعالافتراضيالوصف
options{ value, label, description?, icon?, disabled? }[]لا يوجدالخيارات، كما في Select.
value / defaultValuestring[]لا يوجدقيم الخيارات المختارة.
onValueChange(value: string[]) => voidلا يوجدعند الاختيار أو الحذف.
maxTagsnumber3الوسوم الظاهرة والحقل غير مركّز؛ الباقي «+N أخرى».
onCreate(query: string) => voidلا يوجديضيف زر «إنشاء جديد» في أسفل القائمة.
placeholder / emptyText / namestringلا يوجدكما في Select («اختر خيارات»).
label / required / helperText / error / disabled…لا يوجدكما في حقل الإدخال.

إرشادات الاستخدام

القائمة المنسدلة لاختيار قيمة من خيارات كثيرة لا تتسع للعرض دفعة واحدة. هنا: متى تختارها، وما القيمة الافتراضية، وكيف ترتب الخيارات، وما تتحقق منه قبل التسليم.

1. القائمة المنسدلة أم غيرها

القائمة المنسدلة مناسبة حين تكون الخيارات أكثر من أن تُعرض معًا، ويعرف الناس ما يبحثون عنه. ومع خيارات قليلة اعرضها كلها، فالناس يقارنون أفضل حين يرون كل خيار.

الاختياراستخدمالسبب
خيار من 2 إلى 4 في نموذجأزرار الاختياركل خيار ظاهر وعلى بعد ضغطة واحدة.
خيار من 5 أو أكثرالقائمة المنسدلة، اختيار واحدحقل مدمج، ويعمل البحث فيه من 8 خيارات.
عدة خيارات من خيارات قليلةمجموعة مربعات التفعيلكل الخيارات ظاهرة، وكل خيار يُفعَّل أو يُلغى.
عدة خيارات من خيارات كثيرةالقائمة المنسدلة، اختيار متعددتظهر الخيارات المختارة وسومًا مع «+N أخرى».
تبديل عرض أو تصفية في الصفحةمجموعة أزرار التبديليُطبَّق فورًا دون فتح قائمة.
دولة لرقم هاتفرقم الهاتفاختيار الدولة مدمج فيه.
إجراء (تعديل، حذف، تصدير)زر القائمةالقائمة المنسدلة تختار قيمة، والقائمة تنفّذ إجراءات.

اعرض القوائم القصيرة

اختيار دولة، واختيار سرعة التوصيل.

افعل: قائمة منسدلة لقائمة طويلةمئتا دولة لا تتسع على الشاشة، والقائمة المنسدلة بالبحث تتسع.
تجنّب: قائمة منسدلة لخيارينالتوصيل السريع مخفي خلف ضغطة، ولا يستطيع الناس مقارنة الأسعار بنظرة.

2. النص المؤقت والقيمة الافتراضية

قبل أي اختيار يعرض الحقل نصًا مؤقتًا مثل «اختر خيارًا» (يكتبه الكود بلغة الصفحة). واختر خيارًا مسبقًا فقط حين يكون قيمة افتراضية آمنة يحتفظ بها معظم الناس، مثل عملة المتجر. ولا تختر مسبقًا ما يجب أن يفكر فيه الناس.

لا تخمّن البيانات الشخصية

المدينة في عنوان التوصيل.

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

افعل

  • اترك الحقل فارغًا مع نص مؤقت حين لا توجد قيمة افتراضية آمنة.
  • اختر مسبقًا قيمة آمنة: عملة المتجر، الشهر الحالي، لغة الصفحة.
  • قل «اختر مدينة»، مسمّيًا ما يُختار، حين تكون التسمية وحدها مبهمة.

تجنّب

  • اختيار البيانات الشخصية مسبقًا: المدينة، الجنس، الجنسية.
  • وضع خيار «أخرى» أو «لا شيء» أولًا لملء الحقل.
  • استخدام النص المؤقت تسميةً وحيدة.

3. قائمة الخيارات

رتّب الخيارات كما يبحث عنها الناس: أبجديًا للقوائم الطويلة مثل الدول، وحسب الشيوع أو الترتيب الطبيعي للقصيرة (المقاسات، الأشهر). واجعل التسميات قصيرة ومتمايزة، وأضف سطر وصف فقط حين يتشابه خياران. واجمع القوائم الطويلة تحت عناوين أقسام.

افعل

  • رتّب القوائم الطويلة أبجديًا بلغة الصفحة.
  • حافظ على الترتيب الطبيعي حين يوجد: S، M، L؛ من يناير إلى ديسمبر.
  • شغّل البحث للقوائم الطويلة؛ الكود يفعله من 8 خيارات.
  • قل ما العمل حين لا يجد البحث شيئًا («لا نتائج مطابقة»).

تجنّب

  • الترتيب حسب معرّف داخلي أو ترتيب قاعدة البيانات.
  • خلط اللغات في قائمة واحدة.
  • وضع أكثر من سطر نص في كل خيار.

4. الاختيار المتعدد

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

افعل

  • استخدم الاختيار المتعدد حين يختار الناس عدة خيارات من قائمة طويلة، مثل المهارات أو المدن.
  • اسمح بإزالة وسم من الحقل دون فتح القائمة.
  • قدّم «إنشاء جديد» فقط حيث تكون الخيارات الجديدة منطقية، مثل الوسوم.

تجنّب

  • استخدام الاختيار المتعدد لخيارين أو ثلاثة؛ استخدم مربعات التفعيل.
  • إغلاق القائمة بعد كل اختيار.
  • إخفاء ما اختير خلف عدد وحده.

5. العربية

استخدم النسخة العربية: يقع السهم عند نهاية السطر (اليسار)، وتُفتح القائمة باتجاه الصفحة ولغتها. واكتب تسميات الخيارات بالعربية ورتّبها بترتيب العربية (Intl.Collator("ar"))، فالترتيب بالبايتات يخطئ فيها. وأسماء الدول والمدن تأتي من مصدر معرَّب، لا من نقل حرفي.

نموذج عربي وخيارات عربية

حقل الدولة في صفحة دفع عربية.

افعل: النسخة العربيةالتسمية والقيمة والسهم تتبع التخطيط العربي.
تجنّب: النسخة الإنجليزية بقيمة عربيةيقع السهم على اليمين ويحتفظ النص بالخطوط اللاتينية.

قبل التسليم

  • القائمة المنسدلة فقط لخمسة خيارات أو أكثر؛ الأقل أزرار اختيار أو مجموعة أزرار تبديل.
  • لا تفاصيل شخصية مختارة مسبقًا.
  • ترتيب الخيارات وحدّ البحث محدَّدان.
  • النماذج العربية تستخدم النسخة العربية بخيارات عربية مرتبة صحيحًا.

إمكانية الوصول

لوحة المفاتيح

المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.

المفتاحما يفعله
EnterSpaceArrowDownيفتح القائمة.
ArrowUpArrowDownبين الخيارات؛ Enter يختار وEscape يغلق.
A–Zفي القائمة القصيرة: ينتقل إلى الخيار الذي يبدأ بالحرف. في الطويلة: يكتب في البحث.
Backspaceفي الاختيار المتعدد وحقل الكتابة فارغ: يحذف آخر وسم.

ARIA

  • الحقل زر مرتبط بالتسمية ويفتح listbox؛ الخيار المختار aria-selected وعليه علامة ظاهرة.
  • النص المساعد والخطأ مرتبطان كما في حقل الإدخال.
  • في الاختيار المتعدد: الحقل role="combobox"، وكل صف خيار واحد بـaria-selected (مربع التفعيل مرسوم لا عنصر ثانٍ)، وعدد المختار يُعلن («تم اختيار 3»)، ولكل وسم زر «إزالة» باسمه.

افعل

  • تسمية ظاهرة لكل قائمة منسدلة.
  • الأسهم تتنقل، وEnter يختار، وEscape يغلق، والكتابة تقفز إلى ما يطابقها.
  • في الاختيار المتعدد، لكل وسم زر إزالة له اسم، وBackspace يزيل آخر وسم.

تجنّب

  • قائمة منسدلة مبنية من div لا تُفتح إلا بالنقر.
  • السهم وحده دليلًا على أن الحقل يفتح قائمة.

ملاحظات العربية والاتجاه

ينعكس

  • السهم في نهاية الحقل (اليسار)، والأيقونة والعلامة في الصفوف تتبادلان المكان.
  • القائمة تحمل اتجاه الصفحة ولغتها حتى إن فُتحت من جزيرة LTR.

لا ينعكس

  • السهم يشير إلى الأسفل في الاتجاهين؛ علامة الاختيار لا تنعكس.
الأرقام
الأرقام في الخيارات كما تكتبها؛ استخدم formatNumber للمبالغ.
الخط العربي
الحقل label-16، والصفوف label-14 بوزن Medium والوصف label-12. والبحث يطابق العربية كما تُكتب: صور الهمزة تطابق الألف، والتاء المربوطة الهاء، والألف المقصورة الياء، ولا تُحتسب الحركات، فتجد «اسامه» «أسامة».
النص ثنائي الاتجاه
كل خيار ووصفه يأخذان dir="auto": اسم إنجليزي في قائمة عربية يجري من اليسار.

افعل

  • النسخة العربية في النماذج العربية.
  • رتّب بترتيب العربية (Intl.Collator("ar")).
  • أسماء الدول والمدن العربية المعتمدة: «الأردن» لا «جوردان».

تجنّب

  • تسميات خيارات إنجليزية في نموذج عربي.
  • نقل الأسماء حرفيًا بدل ترجمتها.

الفحوص التي يجتازها

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

  • R050نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
  • R051تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)
  • R023حقول نص تُعرض من اليسار إلى اليمين حيث يُتوقع إدخال عربي