رقم الهاتف
حقل رقم هاتف باختيار الدولة من العلم، بقائمة بحث بالعربية والإنجليزية ومفاتيح الدول، وتنسيق الرقم أثناء الكتابة. يعيد الرقم بالصيغة الدولية (E.164).
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 40 من 41مقاسات العرض: 3تاريخ الفحص: قراءة خاطئة معروفة في محرّك الفحص لدينا: R023
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add phone-inputويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/phone-inputالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactlibphonenumber-jsأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { PhoneInput } from "@/components/ui/phone-input";<PhoneInput label="Phone number" defaultCountry="SA" onValueChange={(e164, { valid }) => save(e164, valid)} />أمثلة
الحالات والقائمة
رقم محفوظ (defaultValue بالصيغة الدولية يختار الدولة)، وcountries لقائمة محددة، والخطأ والتعطيل. الأعلام ملفات SVG ثابتة في public/flags يثبّتها @ritla/flags.
مرجع الخصائص
PhoneInput
يقبل خصائص <input> أيضًا (name وautoComplete…).
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
label | ReactNode | لا يوجد | خاصية Label. |
value / defaultValue | string | لا يوجد | الرقم بالصيغة الدولية («+966501234567»). |
onValueChange | (e164: string, details: { country, national, valid }) => void | لا يوجد | مع كل تغيير. valid يعني طولًا وبادئة صحيحين للدولة. |
country / defaultCountry | CountryCode | "SA" | الدولة المختارة (رمز ISO). |
onCountryChange | (country: CountryCode) => void | لا يوجد | عند اختيار دولة. |
countries | CountryCode[] | لا يوجد | حصر القائمة في دول محددة. |
flagsBase | string | "/flags" | مسار ملفات الأعلام. |
required / helperText / error / disabled | … | لا يوجد | كما في حقل الإدخال. |
إرشادات الاستخدام
حقل رقم الهاتف لرقم واحد مع رمز دولته. هنا: متى تستخدمه، وكيف يعمل التنسيق والتحقق.
1. متى تستخدم حقل رقم الهاتف
لرقم هاتف واحد مع رمز دولته: إنشاء حساب، ورمز التحقق، وبيانات الاتصال.
افعل
- اختر الدولة من لغة المستخدم ومنطقته.
- اعرض الصيغة المتوقعة نصًا مساعدًا.
تجنّب
- طلب رمز الدولة في حقل منفصل.
- رفض الأرقام غير المعروفة دون قول السبب.
2. التنسيق والتحقق
يعرض المنتقي العلم ورمز الاتصال، ويأخذ الحقل الرقم المحلي.
افعل
- تحقّق من الرقم حين يغادر التركيز الحقل.
- اسمح بلصق رقم كامل يبدأ بـ+.
تجنّب
- فرض قالب ثابت واحد على كل الدول.
3. العربية والاتجاه من اليمين إلى اليسار
ينعكس المنتقي والتسمية. ويبقى الرقم من اليسار إلى اليمين، وتبقى + في بدايته.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| EnterArrowDown | على العلم: يفتح قائمة الدول مع مربع البحث. |
| ArrowUpArrowDown | بين الدول؛ Enter يختار، وEscape يغلق. |
| Tab | من العلم إلى الرقم. |
ARIA
- زر العلم باسم «الدولة: السعودية +966» بلغة الصفحة؛ العلم زخرفي.
- حقل الرقم
type="tel"معautocomplete="tel-national"، مرتبط بالتسمية والنص المساعد.
افعل
type="tel"وautocomplete="tel".- سمِّ منتقي الدولة «رمز الدولة».
تجنّب
- العلم وحده دليلًا على الدولة.
ملاحظات العربية والاتجاه
ينعكس
- قائمة الدول تتبع الصفحة: بالعربية ومن اليمين إلى اليسار، مرتبة أبجديًا بالعربية.
لا ينعكس
- صف الحقل كله من اليسار إلى اليمين كما يُكتب الرقم: العلم يسارًا والرقم بعده، في العربية أيضًا.
- مفتاح الدولة («+966») معزول بـ
<bdi dir="ltr">في القائمة.
- الأرقام
- الأرقام المشرقية والفارسية المكتوبة تُحفظ بأرقام غربية (
0123456789)، ويبقى الرقم بأرقام غربية كما في الاتصال. - الخط العربي
- أسماء الدول
label-14بخط الصفحة. والبحث يطابق العربية كما تُكتب، بلا همزات ولا حركات: «السعوديه» تجد «السعودية». - النص ثنائي الاتجاه
- البحث يجد الدولة بالعربية أو الإنجليزية أو برمزها أو بمفتاحها («966»).
افعل
- أبقِ +962 من اليسار إلى اليمين داخل العربية.
- أسماء الدول بالعربية في المنتقي العربي.
تجنّب
- وضع رمز الاتصال بعد الرقم في العربية.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.
- نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
- تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)
- حاوية مجبرة على الاتجاه من اليسار، أو تجاوز لخوارزمية الاتجاه، فوق محتوى عربي
- مخاطر اتجاه غير معزولة: أرقام هواتف وبريد إلكتروني ومقاطع لاتينية داخل نص عربي
- حقول الهاتف والبريد الإلكتروني والرابط تُعرض من اليمين إلى اليسار (ويجب أن تبقى من اليسار إلى اليمين)
- حقول الهوية بلا رموز autocomplete