حقل البحث
حقل بحث بالعدسة وزر مسح عند وجود نص ومؤشر تحميل، واقتراحات اختيارية أثناء الكتابة. بإطار داخل الصفحات والنماذج، أو بخط سفلي في أشرطة الأدوات والقوائم.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add search-fieldويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/search-fieldالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { SearchField } from "@/components/ui/search-field";<SearchField label="Search transactions" suggestions={merchants} onValueChange={setQuery} />أمثلة
الأنماط والحالات
variant: outline (بإطار) أو minimal (بخط سفلي، لا يُستخدم داخل النماذج). loading يُظهر المؤشر ويبقي نص البحث كما هو، وloading="skeleton" يضع شكلًا مؤقتًا مكان الحقل كله أثناء تحميل الصفحة.
الإكمال التلقائي
inlineComplete يُظهر بقية أول اقتراح مطابق بلون باهت بعد النص: Tab (أو سهم الاتجاه للأمام) لقبوله، أو تابع الكتابة.
مرجع الخصائص
SearchField
يقبل خصائص <input> أيضًا.
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
label | ReactNode | لا يوجد | خاصية Label. |
variant | "outline" | "minimal" | "outline" | خاصية Style. |
value / defaultValue | string | لا يوجد | نص البحث. |
onValueChange | (value: string) => void | لا يوجد | مع كل تغيير، ومنه اختيار اقتراح والمسح. |
onClear | () => void | لا يوجد | بعد أن يفرغ زر المسح الحقل. |
loading | boolean | "skeleton" | false | State = Loading: المؤشر مع بقاء نص البحث. "skeleton" هو State = Skeleton: الحقل كله شكل مؤقت أثناء تحميل الصفحة، مع aria-busy. |
suggestions | string[] | لا يوجد | اقتراحات تظهر أثناء الكتابة. |
inlineComplete | boolean | false | State = Auto complete. |
status | string | لا يوجد | عدد النتائج أو حالتها، يُعلَن بهدوء. |
clearLabel | string | لا يوجد | اسم زر المسح. الافتراضي «مسح البحث» بلغة الصفحة. |
helperText / error / disabled | … | لا يوجد | كما في حقل الإدخال. |
إرشادات الاستخدام
البحث يساعد الناس على إيجاد ما يريدون في قائمة أو في المنتج كله. هنا: أي مكوّن تختار، وماذا تكتب في النص المؤقت، وما يحدث أثناء الكتابة، وكيف يتعامل البحث مع العربية، وما تتحقق منه قبل التسليم.
1. أي بحث
أربعة مكوّنات تغطي الأماكن التي يبحث فيها الناس. اختر حسب مكان البحث وحسب المساحة التي تحتاجها النتائج.
| المكان | استخدم | ملاحظات |
|---|---|---|
| تصفية قائمة أو جدول في الصفحة | حقل البحث بنمط outline | حقل بإطار فوق القائمة، والنتائج تُصفّى في مكانها. |
| أشرطة الأدوات وترويسات القوائم واللوحات الكثيفة | حقل البحث بنمط minimal | خط سفلي فقط، ولا يكون داخل نموذج أبدًا. |
| ترويسة التطبيق، والبحث في كل شيء | شريط البحث | شريط مستدير بارتفاع 56 بكسل مع القائمة وإجراءين على الأكثر أو الصورة الرمزية. |
| الاقتراحات والنتائج على الحاسوب | شاشة البحث في نافذة منبثقة | يُفتح فوق الصفحة من الشريط أو من اختصار. |
| الاقتراحات والنتائج على الجوال | شاشة البحث بملء الشاشة | يأخذ الشاشة كلها، وسهم الرجوع يغلقه. |
افعل
- أبقِ البحث ظاهرًا حين يكون المهمة الرئيسية في الصفحة.
- استخدم بحثًا واحدًا لكل نطاق: الترويسة تبحث في كل شيء، والحقل فوق القائمة يبحث فيها.
تجنّب
- إخفاء البحث خلف أيقونة في صفحة مبنية على الإيجاد.
- استخدام نمط
minimalداخل نموذج.
2. النص المؤقت والنطاق
النص المؤقت يقول ما الذي يُبحث فيه: «البحث في المعاملات» لا «بحث» وحدها، حين لا يكون النطاق واضحًا. ويختفي حين يكتب الناس، فهو يصف النطاق فقط؛ أما الاسم الذي تسمعه قارئات الشاشة فيأتي من التسمية التي تمررها في الكود.
قل ما الذي يُبحث فيه
البحث فوق قائمة المعاملات.
افعل
- سمِّ النطاق: «البحث في المعاملات»، «البحث في التجار».
- اجعله قصيرًا يتسع على الجوال.
- أعطِ الحقل اسمًا تسمعه قارئات الشاشة حتى دون تسمية ظاهرة.
تجنّب
- كتابة تعليمات في النص المؤقت: «اكتب اسمًا واضغط Enter».
- نص مبهم مثل «اكتب هنا…».
- وعود لا يستطيعها البحث، مثل «ابحث عن أي شيء».
3. أثناء الكتابة
اعرض الاقتراحات أثناء الكتابة، والنتائج حين يضغط الناس Enter أو يختارون اقتراحًا. واحتفظ بالعبارة في الحقل أثناء تحميل النتائج وبعد ظهورها، كي يحسّنها الناس. ويظهر زر المسح بمجرد وجود نص، والمسح يعيد العرض دون تصفية.
احتفظ بالعبارة أثناء التحميل
البحث في التجار.
افعل
- ابدأ الاقتراحات بعد حرف أو حرفين، وبعد توقف قصير في الكتابة.
- اعرض حالة التحميل واحتفظ بالعبارة أثناء التحميل.
- قل حين لا توجد نتائج، واقترح ما يمكن تجربته.
- اعرض عمليات البحث الأخيرة في الحقل الفارغ.
تجنّب
- مسح العبارة حين تظهر النتائج.
- إلزام الناس بضغط
Enterقبل أن يحدث شيء في قائمة قصيرة. - عرض صفحة فارغة بلا رسالة حين لا يطابق شيء.
4. البحث بالعربية
في الشاشات العربية استخدم النسخ العربية: تنتقل العدسة إلى اليمين وزر المسح إلى اليسار. وتأخذ العبارة dir="auto"، فتُقرأ الأسماء الإنجليزية المكتوبة في بحث عربي صحيحة. أما مطابقة العربية جيدًا فتحدث في خادم البحث: يكتب الناس الكلمة نفسها بأكثر من إملاء، والمطابقة الحرفية تفوّتها.
| وحّد | مثال | السبب |
|---|---|---|
| صور الألف إلى ألف مجردة | كتابة «احمد» تجد «أحمد» | معظم الناس يتركون الهمزة عند الكتابة. |
| التاء المربوطة والهاء في آخر الكلمة | كتابة «مدرسه» تجد «مدرسة» | النهايتان شائعتان في النص المكتوب. |
| الألف المقصورة والياء في آخر الكلمة | كتابة «مستشفي» تجد «مستشفى» | لوحات المفاتيح والعادات تختلف من بلد إلى آخر. |
| حذف التشكيل والتطويل | كتابة «كتاب» تجد «كِتَاب» و«كتـاب» | الحركات والتطويل ليست من الكلمة. |
| الأرقام المشرقية إلى الأرقام الغربية | كتابة «١٢٣» تجد «123» | يكتب الناس الأرقام بأي من لوحتي المفاتيح. |
الحقل يتبع اتجاه القراءة
البحث في التجار بالعربية.
قبل التسليم
- المكوّن المناسب للمكان: حقل أو شريط أو عرض.
- النص المؤقت يسمّي النطاق، باللغتين.
- حالات التحميل وعدم وجود نتائج وعمليات البحث الأخيرة مصمّمة.
- الشاشات العربية تستخدم النسخ العربية، وتوحيد العربية مدوّن لفريق الخادم.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| ArrowDownArrowUp | بين الاقتراحات. |
| Enter | يختار الاقتراح المحدد. |
| Escape | يغلق الاقتراحات، ثم يمسح النص (زر المسح للمؤشر واللمس). |
| TabArrowRight | مع inlineComplete وفي آخر النص: يقبل الإكمال الباهت. |
ARIA
- المنطقة
role="search"والحقلtype="search"بتسمية ظاهرة؛ الاقتراحاتlistboxمرتبطة بالحقل (Base UI). - زر المسح باسم «مسح البحث» بلغة الصفحة، ويعيد التركيز إلى الحقل.
- مرّر عدد النتائج في
statusليُعلَن بهدوء: أثناء فتح الاقتراحات تخفي Base UI بقية الصفحة عن قارئ الشاشة، فلا تُسمع منطقة حية خارج الحقل.
افعل
- اسم يُعلَن لكل حقل بحث: «البحث في المعاملات».
- أعلن عدد النتائج: مرّر
statusفيُقرأ بهدوء. - الأسهم تتنقل بين الاقتراحات، وEnter يختار، وEscape يغلق.
- سمِّ زر المسح («مسح البحث») وأعد التركيز إلى الحقل.
تجنّب
- نقل التركيز إلى النتائج أثناء الكتابة.
- الاكتفاء بالعدسة تسميةً للحقل.
ملاحظات العربية والاتجاه
ينعكس
- العدسة في بداية الحقل (اليمين) وزر المسح والمؤشر في نهايته (اليسار).
لا ينعكس
- أيقونات العدسة والمسح والتحميل لا تنعكس.
- الأرقام
- ما يكتبه المستخدم يبقى كما كتبه؛ اعرض عدد النتائج بأرقام الصفحة (
formatNumber). - الخط العربي
label-16كبقية الحقول، والاقتراحاتlabel-14.- النص ثنائي الاتجاه
- الحقل والاقتراحات تأخذ
dir="auto": اسم تاجر إنجليزي في واجهة عربية يجري من اليسار.
افعل
- النسخة العربية في الشاشات العربية.
- وحّد العبارة والنص المفهرس بالطريقة نفسها.
- ابحث في الاسمين العربي والإنجليزي للشيء نفسه: الدول، والمنتجات.
تجنّب
- عبارة عربية في النسخة الإنجليزية.
- الاعتماد على التطابق الحرفي في النص العربي.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.