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

حقل الإدخال

احصل على Ritla UI

حقل نصي بتسمية ظاهرة ونص مساعد، بالحالات نفسها في كل حقول ⁨Ritla UI⁩: افتراضي وتمرير وتركيز وخطأ ومعطّل وللقراءة فقط وتعبئة تلقائية.

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

افتح في Figma

المعاينة

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

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

التثبيت

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

    npx ritla add input

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

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

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

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

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

الاستخدام

input.tsx
import { Input } from "@/components/ui/input";<Input label="Full name" required name="name" autoComplete="name" helperText="We use it on your receipts." />

أمثلة

الحالات

الحقل الفارغ رمادي والممتلئ أبيض. error برسالة يحلّ محل النص المساعد ويضع aria-invalid على الحقل. التمرير والتركيز والتعبئة التلقائية من المتصفح.

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

المحتوى البادئ والتابع

leadingIcon وprefix في بداية الحقل، وsuffix وtrailingIcon وstatus في نهايته، وتتبدّل أماكنها في العربية. في حقول dir="ltr" (البريد والروابط) يبقى الصف من اليسار إلى اليمين.

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

نص بلغتين

الحقل يأخذ dir="auto": كل قيمة تجري باتجاهها، فتبقى علامة الترقيم في آخر الجملة الإنجليزية داخل نموذج عربي. البريد والروابط والرموز دائمًا من اليسار إلى اليمين: مرّر dir="ltr".

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

مرجع الخصائص

Input

يقبل كل خصائص <input> أيضًا (type وname وvalue وplaceholder وautoComplete وinputMode…).

الخاصيةالنوعالافتراضيالوصف
labelReactNodeلا يوجدخاصية Label. مطلوبة وظاهرة دائمًا.
requiredbooleanfalseخاصية Required: النجمة وrequired على الحقل.
helperTextReactNodeلا يوجدخاصية Helper text.
errorReactNode | booleanلا يوجدState = Error. الرسالة تحلّ محل النص المساعد؛ true يلوّن النص المساعد بالأحمر.
disabledbooleanfalseState = Disabled.
readOnlybooleanfalseState = Read-only.
leadingIconIconComponentلا يوجد‏_Leading content، النوع Icon.
prefixReactNodeلا يوجد‏_Leading content، النوع Text only أو Currency.
suffixReactNodeلا يوجد‏_Trailing content، النوع Text.
trailingIconIconComponentلا يوجد‏_Trailing content، النوع Icon.
shortcutReactNode[]لا يوجدمفاتيح اختصار في نهاية الحقل (Input group). تلميح فقط: ضع aria-keyshortcuts على الحقل.
actionReactNodeلا يوجدزر في نهاية الحقل (Input group، Trailing icon)، مثل نسخ القيمة.
status"success" | "loading" | "warning" | "error" | "disabled"لا يوجد‏Show Field Status. زخرفية: اذكر الحالة في النص المساعد أيضًا.

إرشادات الاستخدام

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

1. اختر الحقل المناسب

استخدم الحقل الأخص بالبيانات. كل حقل يأتي بلوحة المفاتيح والتنسيق والتحقق والتعبئة التلقائية التي تناسبها: حقل رقم الهاتف ينسّق الأرقام حسب الدولة، وبيانات البطاقة تتحقق من رقمها، وحقل رمز التحقق يقبل لصق رمز الرسالة النصية.

البياناتاستخدمما يضيفه
نص قصير: اسم، بريد إلكتروني، مدينةحقل الإدخالالتسمية والنص المساعد والحالات؛ اضبط نوع الحقل (email، url) وautocomplete في الكود.
رقم هاتفرقم الهاتفاختيار الدولة، والتنسيق أثناء الكتابة، وقيمة بصيغة E.164، وقبول الأرقام المشرقية.
كمية أو مبلغحقل الأرقامأزرار الزيادة والنقص، ومفاتيح الأسهم، وحدود القيم، والأرقام حسب إعداد الأرقام، وبادئة عملة اختيارية.
كلمة مرورحقل كلمة المرورالإظهار والإخفاء، ومقياس القوة عند إنشاء حساب.
رمز لمرة واحدة من رسالة نصية أو بريدرمز التحققمن 4 إلى 6 خانات، ولصق الرمز كاملًا وتعبئته تلقائيًا.
رقم البطاقة وتاريخ انتهائها ورمز CVVبيانات البطاقةمجموعة واحدة، وتنسيق، وتعرّف على شبكة البطاقة، وتحقق Luhn، وتعبئة المتصفح للبطاقة.
عدة أسطر من النصمنطقة النصتكبر مع النص وتعرض عدّادًا.
اختيار واحد من قائمةالقائمة المنسدلةقائمة خيارات بدل الكتابة الحرة.

استخدم الحقل المخصص

رقم جوال في نموذج إنشاء حساب.

افعل: حقل رقم الهاتفتأتي معه الدولة ورمز الاتصال والتنسيق، وتُحفظ القيمة بصيغة قياسية واحدة.
تجنّب: حقل نصي عادييكتب الناس 07… أو +962… أو 00962…، وعلى المنتج أن يفكّ هذا التشابك.

2. التسمية والنص المؤقت والنص المساعد

لكل حقل تسمية ظاهرة فوقه تسمّي البيانات. والنص المؤقت مجرد مثال على الصيغة يختفي حين يبدأ الناس الكتابة، فلا يحل محل التسمية أبدًا. والنص المساعد تحت الحقل يشرح ما لا تستطيعه التسمية: الصيغة، والحدود، وسبب السؤال.

التسمية فوق والمثال داخل الحقل

حقل بريد إلكتروني.

افعل: تسمية ظاهرة ونص مساعدتبقى التسمية أثناء الكتابة، ويقول النص المساعد لماذا نحتاج إلى البريد.
تجنّب: النص المؤقت بدل التسميةحين يبدأ الناس الكتابة، لا شيء يقول ما الحقل.

افعل

  • اكتب تسميات قصيرة بأسماء: «البريد الإلكتروني»، «رقم الجوال»، «تاريخ الميلاد».
  • استخدم النص المؤقت مثالًا على الصيغة، أو اتركه فارغًا.
  • ضع قواعد الصيغة وأسبابها في النص المساعد، قبل أن يخطئ الناس.
  • علّم الحقول الاختيارية القليلة حين تكون معظم الحقول مطلوبة، أو العكس.

تجنّب

  • استخدام النص المؤقت بدل التسمية.
  • وضع التعليمات في النص المؤقت، فهي تختفي مع أول حرف.
  • إنهاء التسميات بنقطتين.
  • كتابة التسمية سؤالًا حين يكفي اسم.

3. الأخطاء

تحقّق حين يغادر الناس الحقل أو يرسلون النموذج، لا مع كل حرف. اعرض الرسالة تحت الحقل في حالة الخطأ، وقل ما الخطأ وكيف يُصلح، واحتفظ بما كتبوه. وتحل الرسالة محل النص المساعد ما دام الخطأ قائمًا.

قل كيف يُصلح

بريد إلكتروني بلا نطاق.

افعل: رسالة محددةالرسالة تسمّي المشكلة وتعرض مثالًا صحيحًا.
تجنّب: رسالة عامة«إدخال غير صالح» تقول إن شيئًا خطأ، لا ما هو ولا كيف يُصلح.

افعل

  • قل كيف يُصلح الخطأ: «أدخل بريدًا مثل name@example.com».
  • احتفظ بالقيمة المكتوبة كي يصححها الناس.
  • انقل التركيز إلى أول حقل فيه خطأ بعد إرسال فاشل.
  • استخدم حالة الخطأ والرسالة معًا؛ اللون وحده لا يكفي.

تجنّب

  • عرض رسائل عامة مثل «إدخال غير صالح» أو «خطأ».
  • مسح الحقل حين يفشل التحقق.
  • عرض الأخطاء قبل أن ينتهي الناس من الكتابة.
  • لوم المستخدم: «أدخلتَ بريدًا خاطئًا».

4. العربية، والبيانات التي تبقى من اليسار إلى اليمين

في الشاشات العربية استخدم النسخ العربية: تُحاذى التسمية والنص المساعد والنص إلى اليمين بخط IBM Plex Sans Arabic. وبعض البيانات تُكتب من اليسار إلى اليمين في كل اللغات: البريد الإلكتروني، وعناوين المواقع، وأرقام الهاتف والبطاقات، والرموز والمعرّفات. هذه الحقول تبقى من اليسار إلى اليمين داخل نموذج عربي (في Figma Latin input = Yes على _Input، وفي الكود dir="ltr" على الحقل). أما ما يكتبه الناس بحرية فيأخذ dir="auto"، فتُقرأ الإجابة الإنجليزية في نموذج عربي صحيحة.

حقل عربي وبيانات من اليسار إلى اليمين

بريد إلكتروني يُكتب في نموذج إنشاء حساب عربي.

افعل: نسخة عربية وبريد من اليسار إلى اليمينتُقرأ التسمية والنص المساعد من اليمين إلى اليسار، والعنوان كما يُكتب.
تجنّب: نسخة إنجليزية بتسمية عربيةتقع التسمية العربية على اليسار بخط لاتيني، ولا يعود النموذج مصطفًا.

5. العرض والتخطيط

رتّب الحقول في عمود واحد والتسمية فوق كل حقل. واجعل عرض كل حقل بقدر البيانات المتوقعة: الرمز البريدي ورمز CVV قصيران، والبريد والعنوان طويلان. واجمع الحقول المترابطة (بيانات البطاقة، نطاق تاريخ)، واترك space-24 بين الحقول.

العرض يلمّح إلى الإجابة

جزء العنوان في نموذج الدفع.

افعل: بقدر المحتوىالحقل القصير يقول إن الإجابة المتوقعة قصيرة.
تجنّب: كل شيء بعرض كاملرمز بريدي بعرض كامل يبدو كأنه يطلب عنوانًا كاملًا.

افعل

  • استخدم عمودًا واحدًا، فالناس يقرأون النماذج من الأعلى إلى الأسفل.
  • طابِق العرض مع الطول المتوقع للإجابة.
  • ضع الحقول القصيرة المترابطة جنبًا إلى جنب: المدينة والرمز البريدي.

تجنّب

  • جعل كل حقل بعرض كامل أيًا كان محتواه.
  • وضع حقول لا علاقة بينها جنبًا إلى جنب لتوفير المساحة.
  • وضع التسميات بجانب الحقل، فأطوال التسميات العربية تتفاوت كثيرًا.

6. للقراءة فقط والتعطيل والتعبئة التلقائية

حالة «للقراءة فقط» تعرض قيمة يقرأها الناس وينسخونها دون تغييرها، مثل رقم الحساب، وتحتفظ بالتباين الكامل. و«معطّل» يعني أن الحقل لا ينطبق الآن، فيبهت نصه وقد تتخطاه قارئات الشاشة. والتعبئة التلقائية هي اللون الذي يضيفه المتصفح حين يملأ الحقل؛ أبقِه كي يراجع الناس ما مُلئ.

«للقراءة فقط» للقيم التي تُحفظ

رقم آيبان في شاشة إعدادات السحب.

افعل: للقراءة فقطتباين كامل، قابل للتحديد، وواضح أنه لا يُعدَّل.
تجنّب: معطّلالنص الباهت صعب القراءة ولا يمكن تحديده لنسخه.

افعل

  • استخدم «للقراءة فقط» للقيم التي يحتاج الناس إلى رؤيتها أو نسخها.
  • اشرح الحقل المعطّل في نصه المساعد، أو أخفِه.
  • أبقِ لون التعبئة التلقائية حتى يعدّل الناس الحقل.

تجنّب

  • استخدام «معطّل» لمعلومات يحتاج الناس إلى قراءتها.
  • تصميم قيمة للقراءة فقط كأنها حقل عادي قابل للتعديل.

7. كلمات المرور والرموز والبطاقات

هذه الحقول تتعامل مع بيانات حساسة، فتعتمد على المتصفح ونظام التشغيل: التعبئة التلقائية تملؤها، ومديرو كلمات المرور يحفظونها، ورموز الرسائل النصية تصل وحدها. اضبط autocomplete المناسب في الكود ولا تعاند الإعدادات الافتراضية.

افعل

  • قدّم الإظهار والإخفاء في كل حقل كلمة مرور.
  • اعرض مقياس القوة فقط حين ينشئ الناس كلمة مرور، بتقييمك أنت.
  • اسمح بلصق رمز التحقق كاملًا؛ الكود يملأ الخانات كلها دفعة واحدة.
  • أبقِ بيانات البطاقة مجموعة واحدة: الرقم، ثم تاريخ الانتهاء، ثم CVV، بهذا الترتيب.
  • اضبط autocomplete: current-password وnew-password وone-time-code وcc-number.

تجنّب

  • منع اللصق في حقول كلمة المرور أو الرمز.
  • طلب تأكيد كلمة المرور في حقل ثانٍ ما دام الإظهار والإخفاء متاحًا.
  • تقسيم رقم البطاقة إلى أربعة حقول منفصلة.
  • عرض قواعد كلمة المرور بعد محاولة فاشلة فقط؛ ضعها في النص المساعد.

قبل التسليم

  • كل حقل يستخدم المكوّن الأخص ببياناته.
  • لكل حقل تسمية ظاهرة، والنص المؤقت يعرض صيغة فقط.
  • رسائل الخطأ مكتوبة لكل قاعدة تحقق.
  • الشاشات العربية تستخدم النسخ العربية، والبيانات اللاتينية تبقى من اليسار إلى اليمين.
  • العروض تطابق الإجابات المتوقعة، في عمود واحد.
  • قيم autocomplete مدوّنة لفريق التطوير.

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

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

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

المفتاحما يفعله
Tabينقل التركيز إلى الحقل: يصير إطاره أزرق داكنًا وحوله هالة خفيفة (هالة حمراء في حالة الخطأ)، ويظهر إطار التركيز في وضع التباين العالي.

ARIA

  • التسمية <label> مرتبطة بالحقل، والنص المساعد أو رسالة الخطأ عبر aria-describedby.
  • الخطأ يضع aria-invalid على الحقل، ويُقرأ نص الخطأ الجديد بهدوء (aria-live="polite").
  • النجمة زخرفية؛ required على الحقل هو ما يُعلَن.
  • استخدم type وinputMode وautoComplete المناسبة (email، tel، numeric).

افعل

  • تسمية ظاهرة لكل حقل، وهي اسمه الذي يُعلَن.
  • حالة الخطأ مع رسالة، مربوطة بـaria-describedby وaria-invalid.
  • ارتفاع 48 بكسل وحلقة تركيز كاملة لا تقصّها منطقة تمرير.
  • ترتيب Tab يتبع الترتيب المرئي في الاتجاهين.

تجنّب

  • الاكتفاء بالإطار الأحمر.
  • إخفاء التسمية بصريًا دون اسم يُعلَن.
  • إنهاء مهلة النموذج أثناء الكتابة.

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

ينعكس

  • التسمية والنص المساعد والأيقونة البادئة في بداية السطر (اليمين)، والحالة واللاحقة في نهايته.
  • الأيقونات الاتجاهية تنعكس.

لا ينعكس

  • مع dir="ltr" (البريد والروابط والرموز) يصير صف الحقل كله من اليسار إلى اليمين، كحقل الهاتف في Figma: تبقى «https://» قبل القيمة و«.ritla.app» بعدها.
  • أيقونات الحالة لا تنعكس.
الأرقام
ما يكتبه المستخدم يبقى كما كتبه. للأرقام استخدم حقل الأرقام، فهو يتبع خاصية numerals.
الخط العربي
النص label-16 والتسمية والنص المساعد label-12، بارتفاع سطر أطول في العربية؛ الحقل بارتفاع 48px ثابت يتسع لهما.
النص ثنائي الاتجاه
الحقل يأخذ dir="auto" افتراضيًا، فتجري كل قيمة باتجاه لغتها.

افعل

  • النسخة العربية لكل حقل في شاشة عربية.
  • أبقِ البريد والروابط وأرقام الهاتف والبطاقات والرموز من اليسار إلى اليمين (Latin input = Yes في Figma، وdir="ltr" في الكود).
  • اقبل الأرقام المشرقية في حقول الأرقام والهاتف والرموز والبطاقات؛ يحوّلها الكود إلى 0123456789.
  • اكتب التسميات والنصوص المساعدة بالعربية أصلًا، لا ترجمةً.

تجنّب

  • تسميات عربية في النسخة الإنجليزية.
  • محاذاة بريد أو رقم هاتف إلى اليمين داخل حقل عربي.
  • مطالبة الناس بتبديل لوحة المفاتيح لكتابة الأرقام.

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

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

  • R050نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
  • R051تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)
  • R042نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
  • R043حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة