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

حقل البحث

احصل على Ritla UI

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

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

افتح في Figma

المعاينة

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

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

التثبيت

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

    npx ritla add search-field

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

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

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

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

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

الاستخدام

search-field.tsx
import { SearchField } from "@/components/ui/search-field";<SearchField label="Search transactions" suggestions={merchants} onValueChange={setQuery} />

أمثلة

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

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

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

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

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

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

مرجع الخصائص

SearchField

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

الخاصيةالنوعالافتراضيالوصف
labelReactNodeلا يوجدخاصية Label.
variant"outline" | "minimal""outline"خاصية Style.
value / defaultValuestringلا يوجدنص البحث.
onValueChange(value: string) => voidلا يوجدمع كل تغيير، ومنه اختيار اقتراح والمسح.
onClear() => voidلا يوجدبعد أن يفرغ زر المسح الحقل.
loadingboolean | "skeleton"falseState = Loading: المؤشر مع بقاء نص البحث. "skeleton" هو State = Skeleton: الحقل كله شكل مؤقت أثناء تحميل الصفحة، مع aria-busy.
suggestionsstring[]لا يوجداقتراحات تظهر أثناء الكتابة.
inlineCompletebooleanfalseState = Auto complete.
statusstringلا يوجدعدد النتائج أو حالتها، يُعلَن بهدوء.
clearLabelstringلا يوجداسم زر المسح. الافتراضي «مسح البحث» بلغة الصفحة.
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": اسم تاجر إنجليزي في واجهة عربية يجري من اليسار.

افعل

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

تجنّب

  • عبارة عربية في النسخة الإنجليزية.
  • الاعتماد على التطابق الحرفي في النص العربي.

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

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

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