حقل الأرقام
حقل رقمي بزرّي زيادة ونقصان وبادئة عملة اختيارية. يكتب القيمة بأرقام الصفحة (123 أو ١٢٣) ويقبل النوعين عند الكتابة.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 40 من 41مقاسات العرض: 3تاريخ الفحص: قراءة خاطئة معروفة في محرّك الفحص لدينا: R023
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add number-inputويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/number-inputالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { NumberInput } from "@/components/ui/number-input";<NumberInput label="Amount" prefix="$" defaultValue={100} min={0} step={50} />أمثلة
الحالات والتنسيق
format يمرّر خيارات Intl.NumberFormat (الكسور والتجميع). في حالة القراءة فقط تختفي الأزرار.
مرجع الخصائص
NumberInput
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
label | ReactNode | لا يوجد | خاصية Label. |
value / defaultValue | number | لا يوجد | القيمة الرقمية (لا النص المنسّق). |
onValueChange | (value: number | null) => void | لا يوجد | عند تغيّر القيمة. |
min / max / step | number | step 1 | الحدود والخطوة. |
largeStep | number | step × 10 | خطوة Shift مع الأسهم: عشر خطوات افتراضيًا. |
format | Intl.NumberFormatOptions | لا يوجد | تنسيق القيمة. |
prefix | ReactNode | لا يوجد | _Leading content: عملة أو وحدة. |
stepper | boolean | true | إظهار زرّي الزيادة والنقصان. |
decrementLabel / incrementLabel | string | لا يوجد | اسما الزرّين لقارئ الشاشة. الافتراضي بلغة الصفحة. |
required / helperText / error / disabled / readOnly | … | لا يوجد | كما في حقل الإدخال. |
إرشادات الاستخدام
حقل الأرقام للمبالغ والكميات التي تُكتب باليد. هنا: متى تستخدمه، وكيف تقول الحدود والأخطاء، وما تتحقق منه قبل التسليم.
1. متى تستخدمه
للمال والكميات التي تُكتب باليد: مبالغ التحويل، والحدود، والكميات. واستخدم المنزلق فقط للقيم التقريبية.
افعل
- اعرض العملة بجوار القيمة.
- اعرض الرصيد أو الحد تحت الحقل.
- نسّق القيمة بفواصل الآلاف أثناء الكتابة.
تجنّب
- استخدام حقل نصي عادي للمال.
- السماح بخانات عشرية أكثر مما للعملة.
2. الحدود والأخطاء
قل القاعدة قبل أن يخالفها الناس، وتحقّق منها حين يتوقفون عن الكتابة.
افعل
- استخدم ثلاث خانات عشرية للدينار الأردني والدينار الكويتي، وخانتين لمعظم العملات الأخرى.
- اعرض الحد نصًا مساعدًا.
تجنّب
- استخدام أزرار الزيادة والنقص للمبالغ.
- عرض خطأ قبل أن ينتهي الشخص من الكتابة.
3. العربية والاتجاه من اليمين إلى اليسار
ينعكس الحقل وتقع العملة عند نهاية القراءة. وتبقى الأرقام لاتينية ومن اليسار إلى اليمين.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| ArrowUpArrowDown | يزيد القيمة أو ينقصها بخطوة. |
| ShiftArrowUp | عشر خطوات (largeStep). |
| HomeEnd | أدنى وأعلى قيمة، إن وُجدتا. |
ARIA
- الحقل مرتبط بالتسمية والنص المساعد مثل حقل الإدخال.
- زرّا الزيادة والنقصان باسمين («زيادة» و«إنقاص») بلغة الصفحة.
افعل
inputmode="decimal"على الهواتف.- اربط النص المساعد والخطأ بالحقل.
تجنّب
- النص المؤقت بدل التسمية.
ملاحظات العربية والاتجاه
ينعكس
- العملة في بداية الحقل (اليمين) والزرّان في نهايته، والزيادة في أقصى اليسار.
لا ينعكس
- الرقم يُقرأ من اليسار إلى اليمين (
dir="ltr") فلا تنقلب إشارة السالب، ويُحاذى إلى بداية الحقل.
- الأرقام
- يتبع
numeralsمنRitlaProvider: ١٬٢٣٤ أو 1,234. الأرقام العربية والفارسية المكتوبة تُفهم كأرقام. - الخط العربي
label-16كبقية الحقول.
افعل
- اقبل الأرقام المشرقية من لوحة المفاتيح وحوّلها.
- استخدم «د.أ» و«ر.س» في العربية.
تجنّب
- عرض الأرقام المشرقية ما لم يعرضها المنتج كله.
- إبعاد إشارة السالب عن الرقم.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.
- نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
- تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)
- مخاطر اتجاه غير معزولة: أرقام هواتف وبريد إلكتروني ومقاطع لاتينية داخل نص عربي
- نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
- حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة