القائمة المنسدلة
حقل لاختيار خيار واحد أو عدة خيارات من قائمة، بتسمية حقل الإدخال وحالاته، وبحث حين تطول القائمة. استخدمها لخمسة خيارات أو أكثر؛ وللأقل أزرار الاختيار أو مربعات التفعيل.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add selectويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/selectالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { Select } from "@/components/ui/select";<Select label="Transfer purpose" options={[{ value: "rent", label: "Rent" }, …]} onValueChange={setPurpose} />أمثلة
الحالات
قائمة قصيرة (5 خيارات) تُفتح بلا بحث. لا تحدد خيارًا مسبقًا إلا إذا كان آمنًا.
أيقونة ووصف
icon وdescription لكل خيار، وdisabled لخيار غير متاح. الخيار المختار عليه علامة.
اختيار متعدد
MultiSelect: الخيارات المختارة وسوم في الحقل ولكل منها زر حذف، والكتابة في الحقل تصفّي القائمة، والصفوف بمربعات تفعيل وتبقى القائمة مفتوحة حتى «تم».
حالات الاختيار المتعدد
بعد maxTags وسوم يلخّص الحقل الباقي («+2 أخرى») حتى تركّز عليه؛ والخطأ والتعطيل كما في حقل الإدخال؛ وonCreate يضيف «إنشاء جديد» بما كتبه الشخص.
مرجع الخصائص
Select
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
label | ReactNode | لا يوجد | خاصية Show label. |
options | { value, label, description?, icon?, disabled? }[] | لا يوجد | الخيارات. |
value / defaultValue | string | null | لا يوجد | قيمة الخيار المختار. |
onValueChange | (value: string | null) => void | لا يوجد | عند الاختيار. |
searchable | boolean | options ≥ 8 | مربع البحث في أعلى القائمة. |
placeholder / searchPlaceholder / emptyText | string | لا يوجد | الافتراضي بلغة الصفحة («اختر خيارًا»، «بحث»، «لا توجد نتائج»). |
name | string | لا يوجد | اسم الحقل في النموذج. |
required / helperText / error / disabled | … | لا يوجد | كما في حقل الإدخال. |
MultiSelect
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
options | { value, label, description?, icon?, disabled? }[] | لا يوجد | الخيارات، كما في Select. |
value / defaultValue | string[] | لا يوجد | قيم الخيارات المختارة. |
onValueChange | (value: string[]) => void | لا يوجد | عند الاختيار أو الحذف. |
maxTags | number | 3 | الوسوم الظاهرة والحقل غير مركّز؛ الباقي «+N أخرى». |
onCreate | (query: string) => void | لا يوجد | يضيف زر «إنشاء جديد» في أسفل القائمة. |
placeholder / emptyText / name | string | لا يوجد | كما في 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")). - أسماء الدول والمدن العربية المعتمدة: «الأردن» لا «جوردان».
تجنّب
- تسميات خيارات إنجليزية في نموذج عربي.
- نقل الأسماء حرفيًا بدل ترجمتها.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.