البناء · جديد

حقل البحث

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

المعاينة

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

التثبيت

قريبًايُفتح التثبيت من السجل مع الإطلاق. حتى ذلك الحين، هذا هو الأمر الذي ستستخدمه.

npx shadcn@latest add @ritla/search-field

الاعتماديات التي يضيفها: @base-ui/react, @phosphor-icons/react

الاستخدام

import { SearchField } from "@/components/ui/search-field";

<SearchField label="Search transactions" suggestions={merchants} onValueChange={setQuery} />

أمثلة

الأنماط والحالات

variant: ‏outline (بإطار) أو minimal (بخط سفلي، لا يُستخدم داخل النماذج). loading يُظهر المؤشر ويبقي نص البحث كما هو.

الإكمال التلقائي

inlineComplete يُظهر بقية أول اقتراح مطابق بلون باهت بعد النص: Tab (أو سهم الاتجاه للأمام) لقبوله، أو تابع الكتابة.

مرجع الخصائص

SearchField

يقبل خصائص <input> أيضًا.

الخاصية	النوع	الافتراضي	الوصف
`label`	`ReactNode`		خاصية Label.
`variant`	`"outline" \| "minimal"`	`"outline"`	خاصية Style.
`value / defaultValue`	`string`		نص البحث.
`onValueChange`	`(value: string) => void`		مع كل تغيير، ومنه اختيار اقتراح والمسح.
`onClear`	`() => void`		بعد أن يفرغ زر المسح الحقل.
`loading`	`boolean`	`false`	State = Loading.
`suggestions`	`string[]`		اقتراحات تظهر أثناء الكتابة.
`inlineComplete`	`boolean`	`false`	State = Auto complete.
`status`	`string`		عدد النتائج أو حالتها، يُعلَن بهدوء.
`clearLabel`	`string`		اسم زر المسح. الافتراضي «مسح البحث» بلغة الصفحة.
`helperText / error / disabled`	`…`		كما في حقل الإدخال.

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

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

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

المفتاح	ما يفعله
`ArrowDownArrowUp`	بين الاقتراحات.
`Enter`	يختار الاقتراح المحدد.
`Escape`	يغلق الاقتراحات، ثم يمسح النص (زر المسح للمؤشر واللمس).
`TabArrowRight`	مع `inlineComplete` وفي آخر النص: يقبل الإكمال الباهت.

ARIA

المنطقة role="search" والحقل type="search" بتسمية ظاهرة؛ الاقتراحات listbox مرتبطة بالحقل (Base UI).
زر المسح باسم «مسح البحث» بلغة الصفحة، ويعيد التركيز إلى الحقل.
مرّر عدد النتائج في status ليُعلَن بهدوء: أثناء فتح الاقتراحات تخفي Base UI بقية الصفحة عن قارئ الشاشة، فلا تُسمع منطقة حية خارج الحقل.

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

ينعكس

العدسة في بداية الحقل (اليمين) وزر المسح والمؤشر في نهايته (اليسار).

لا ينعكس

أيقونات العدسة والمسح والتحميل لا تنعكس.

الأرقام: ما يكتبه المستخدم يبقى كما كتبه؛ اعرض عدد النتائج بأرقام الصفحة (formatNumber).
الخط العربي: label-16 كبقية الحقول، والاقتراحات label-14.
النص ثنائي الاتجاه: الحقل والاقتراحات تأخذ dir="auto": اسم تاجر إنجليزي في واجهة عربية يجري من اليسار.

كل المكونات ›