قائمة منسدلة

Dropdown

حقل قائمة منسدلة في React باختيار مفرد ومتعدد، بحث داخل اللوحة، خيارات مجمعة، وربط كامل للحقل. مبني على cmdk للتصفية السريعة بالعربية والإنجليزية.

فتح في Storybook ↗

يتكون حقل الاختيار Dropdown من عناصر DropdownItem. أضف multiple للاختيار المتعدد، أو searchable لإضافة بحث داخل اللوحة.

متى تستخدمه

استخدم Dropdown حين يحتاج حقل الاختيار إلى بحث أو قيم متعددة أو خيارات مجمعة: اختيار عدة خدمات، أو التصفية بحسب مدن كثيرة، أو الاختيار من قائمة مرجعية طويلة. استخدم Select للاختيار المفرد البسيط، وChip لمجموعة مرشحات ظاهرة.

وفر emptyMessage لتظهر رسالة توضيحية حين لا يجد البحث نتائج.

أمثلة

اختيار مفرد

المدينة

قابل للبحث

الدولة

اختيار متعدد

الخدمات

خيارات مجمعة

حزمة التقنيات

الخصائص

الخصائص التي يعرفها Dropdown. سمات العنصر الأصلي تمر كما هي.

<Dropdown>

الخاصية	النوع	الوصف
`size`	`"md" \| "lg"`
`variant`	`"default" \| "filled-lighter" \| "filled-darker"`
`open`	`boolean`
`defaultOpen`	`boolean`
`onOpenChange`	`(open: boolean) => void`
`label`	`react.ReactNode`	Visible label above the trigger.
`helperText`	`react.ReactNode`	Hint shown below the trigger when there's no error.
`errorMessage`	`react.ReactNode`	Message shown below the trigger when `error` is true.
`error`	`boolean`	Marks the field invalid - sets `aria-invalid` and the error border.
`required`	`boolean`	Adds the required asterisk and `aria-required`; with `name`, blocks native submit while empty.
`name`	`string`	Submits the selection under this name in native forms (`FormData`). Single submits the value, or `""` when empty. `multiple` submits one entry per value under this exact name (read with `getAll(name)`; pass `name="cities[]"` for PHP and Laravel), and nothing when empty.
`form`	`string`	Associates the hidden inputs with a `<form>` by id, like the native `form` attribute.
`disabled`	`boolean`	Disables the trigger entirely.
`readOnly`	`boolean`	Shows the value but blocks opening (SDGA Read-only).
`placeholder`	`react.ReactNode`	Placeholder shown when nothing is selected.
`searchable`	`boolean`	Render the in-panel filter input (combobox behavior). Off by default - the plain SDGA dropdown. A hidden focusable input is kept either way for cmdk's keyboard model.
`searchPlaceholder`	`string`	Placeholder for the filter input when `searchable`.
`emptyMessage`	`react.ReactNode`	Shown when a filter matches nothing.
`getLabel`	`(value: string) => ReactNode`	Override the trigger label resolver (e.g. async-loaded options).
`id`	`string`
`className`	`string`
`aria-label`	`string`
`aria-labelledby`	`string`
`children`إلزامي	`react.ReactNode`	`<DropdownItem>` (+ optional `DropdownGroup` / `DropdownSeparator`).
`multiple`	`false`
`value`	`string`
`defaultValue`	`string`
`onValueChange`	`(value: string) => void`

<DropdownItem>

الخاصية	النوع	الوصف
`value`إلزامي	`string`	Stable value for filtering + selection.
`keywords`	`string[]`	Extra search terms cmdk matches against the filter input.
`disabled`	`boolean`	Whether this item is currently disabled.
`onSelect`	`(value: string) => void`	Fires alongside the root's `onValueChange`.
`children`	`ReactNode`
`asChild`	`boolean`
`forceMount`	`boolean`	Whether this item is forcibly rendered regardless of filtering.

<DropdownGroup>

الخاصية	النوع	الوصف
`heading`	`react.ReactNode`	Optional heading to render for this group.
`children`	`ReactNode`
`asChild`	`boolean`
`value`	`string`	If no heading is provided, you must provide a value that is unique for this group.
`forceMount`	`boolean`	Whether this group is forcibly rendered regardless of filtering.

<DropdownSeparator>

الخاصية	النوع	الافتراضي	الوصف
`asChild`	`boolean`
`alwaysRender`	`boolean`		Whether this separator should always be rendered. Useful if you disable automatic filtering.

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

يعرض المشغل aria-haspopup، وتستخدم تسمية الحقل، النص المساعد، ورسالة الخطأ الربط نفسه المستخدم في TextInput. داخل اللوحة، يتبع حقل البحث وقائمة الخيارات نمط combobox من cmdk، ويدعمان هذه المفاتيح: الأسهم للتنقل بين الخيارات، Enter لتبديل الخيار المظلل، وEscape للإغلاق.

تعلن التقنيات المساعدة القيم المختارة. وفي وضع الاختيار المتعدد، يبقى كل اختيار ظاهراً في المشغل.