حقل الإدخال
حقل نصي بتسمية ظاهرة ونص مساعد، بالحالات نفسها في كل حقول Ritla UI: افتراضي وتمرير وتركيز وخطأ ومعطّل وللقراءة فقط وتعبئة تلقائية.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add inputويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/inputالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
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 على الحقل. التمرير والتركيز والتعبئة التلقائية من المتصفح.
المحتوى البادئ والتابع
leadingIcon وprefix في بداية الحقل، وsuffix وtrailingIcon وstatus في نهايته، وتتبدّل أماكنها في العربية. في حقول dir="ltr" (البريد والروابط) يبقى الصف من اليسار إلى اليمين.
نص بلغتين
الحقل يأخذ dir="auto": كل قيمة تجري باتجاهها، فتبقى علامة الترقيم في آخر الجملة الإنجليزية داخل نموذج عربي. البريد والروابط والرموز دائمًا من اليسار إلى اليمين: مرّر dir="ltr".
مرجع الخصائص
Input
يقبل كل خصائص <input> أيضًا (type وname وvalue وplaceholder وautoComplete وinputMode…).
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
label | ReactNode | لا يوجد | خاصية Label. مطلوبة وظاهرة دائمًا. |
required | boolean | false | خاصية Required: النجمة وrequired على الحقل. |
helperText | ReactNode | لا يوجد | خاصية Helper text. |
error | ReactNode | boolean | لا يوجد | State = Error. الرسالة تحلّ محل النص المساعد؛ true يلوّن النص المساعد بالأحمر. |
disabled | boolean | false | State = Disabled. |
readOnly | boolean | false | State = Read-only. |
leadingIcon | IconComponent | لا يوجد | _Leading content، النوع Icon. |
prefix | ReactNode | لا يوجد | _Leading content، النوع Text only أو Currency. |
suffix | ReactNode | لا يوجد | _Trailing content، النوع Text. |
trailingIcon | IconComponent | لا يوجد | _Trailing content، النوع Icon. |
shortcut | ReactNode[] | لا يوجد | مفاتيح اختصار في نهاية الحقل (Input group). تلميح فقط: ضع aria-keyshortcuts على الحقل. |
action | ReactNode | لا يوجد | زر في نهاية الحقل (Input group، Trailing icon)، مثل نسخ القيمة. |
status | "success" | "loading" | "warning" | "error" | "disabled" | لا يوجد | Show Field Status. زخرفية: اذكر الحالة في النص المساعد أيضًا. |
إرشادات الاستخدام
حقل الإدخال يجمع نصًا قصيرًا بتسمية ظاهرة ونص مساعد. هنا: أي حقل تختار، وكيف تكتب التسمية والأخطاء، وكيف تبقى البيانات اللاتينية من اليسار إلى اليمين، وما تتحقق منه قبل التسليم.
1. اختر الحقل المناسب
استخدم الحقل الأخص بالبيانات. كل حقل يأتي بلوحة المفاتيح والتنسيق والتحقق والتعبئة التلقائية التي تناسبها: حقل رقم الهاتف ينسّق الأرقام حسب الدولة، وبيانات البطاقة تتحقق من رقمها، وحقل رمز التحقق يقبل لصق رمز الرسالة النصية.
| البيانات | استخدم | ما يضيفه |
|---|---|---|
| نص قصير: اسم، بريد إلكتروني، مدينة | حقل الإدخال | التسمية والنص المساعد والحالات؛ اضبط نوع الحقل (email، url) وautocomplete في الكود. |
| رقم هاتف | رقم الهاتف | اختيار الدولة، والتنسيق أثناء الكتابة، وقيمة بصيغة E.164، وقبول الأرقام المشرقية. |
| كمية أو مبلغ | حقل الأرقام | أزرار الزيادة والنقص، ومفاتيح الأسهم، وحدود القيم، والأرقام حسب إعداد الأرقام، وبادئة عملة اختيارية. |
| كلمة مرور | حقل كلمة المرور | الإظهار والإخفاء، ومقياس القوة عند إنشاء حساب. |
| رمز لمرة واحدة من رسالة نصية أو بريد | رمز التحقق | من 4 إلى 6 خانات، ولصق الرمز كاملًا وتعبئته تلقائيًا. |
| رقم البطاقة وتاريخ انتهائها ورمز CVV | بيانات البطاقة | مجموعة واحدة، وتنسيق، وتعرّف على شبكة البطاقة، وتحقق Luhn، وتعبئة المتصفح للبطاقة. |
| عدة أسطر من النص | منطقة النص | تكبر مع النص وتعرض عدّادًا. |
| اختيار واحد من قائمة | القائمة المنسدلة | قائمة خيارات بدل الكتابة الحرة. |
استخدم الحقل المخصص
رقم جوال في نموذج إنشاء حساب.
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.
- اكتب التسميات والنصوص المساعدة بالعربية أصلًا، لا ترجمةً.
تجنّب
- تسميات عربية في النسخة الإنجليزية.
- محاذاة بريد أو رقم هاتف إلى اليمين داخل حقل عربي.
- مطالبة الناس بتبديل لوحة المفاتيح لكتابة الأرقام.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.