Field

التثبيتنسخ رابط العنوان

Field هو أساس كل عنصر تحكم في النماذج. وكل عنصر تضيفه من هذا القسم يثبّته معه.

الاستخدامنسخ رابط العنوان

import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

export function NationalIdField({ error }: { error?: string }) {
  return (
    <Field name="nationalId" invalid={Boolean(error)}>
      <FieldLabel required>رقم الهوية الوطنية</FieldLabel>
      <Input required inputMode="numeric" />
      <FieldDescription>١٠ أرقام تبدأ بالرقم ١ أو ٢.</FieldDescription>
      <FieldError match={Boolean(error)}>{error}</FieldError>
    </Field>
  );
}

ضع عنصر تحكم واحدًا في كل Field. تسمّي التسمية العنصر، ويُقرأ النص المساعد ورسالة الخطأ بعده عبر aria-describedby. استخدم Input أو Textarea أو Select أو Number Input أو Search Box أو Checkbox أو Radio أو Switch أو File Upload عنصرَ تحكم.

البنيةنسخ رابط العنوان

• Field (<div>): يحمل الحالة (invalid وdisabled) التي تقرؤها كل الأجزاء.
• FieldLabel (<label>): الاسم الظاهر. required يضيف * أحمر، وoptional يضيف النص «(اختياري)».
• عنصر التحكم: أي مكوّن نموذج من هذا القسم.
• FieldDescription (<p>): نص مساعد تحت عنصر التحكم.
• FieldError: الرسالة مع أيقونة تنبيه.
• FieldContent وFieldGroup وFieldSet وFieldLegend وFieldItem ترتّب المجموعات وعناصر التحكم الأفقية.

أمثلةنسخ رابط العنوان

المطلوب والاختيارينسخ رابط العنوان

علّم الحقول المطلوبة بـ required على التسمية وعلى عنصر التحكم، فتُرى العلامة ويُعلَن الشرط. وفي نموذج أغلب حقوله مطلوبة، علّم الاستثناءات بـ optional وترجم النص عبر optionalLabel.

<FieldLabel required>الاسم الكامل</FieldLabel>
<FieldLabel optional optionalLabel="اختياري">المسمى الوظيفي</FieldLabel>

رسائل الخطأنسخ رابط العنوان

اضبط invalid على Field وmatch على FieldError لتتحكم في الخطأ من حالتك. وبدون match تظهر الرسالة عند فشل تحقق المتصفح. ولها أيقونة دائمًا، فلا يعتمد الخطأ على اللون وحده.

نموذج كاملنسخ رابط العنوان

طلب رخصة بناء مبني من عناصر تحكم داخل Field فقط. أرسله فارغًا لترى كل رسائل الخطأ.

المجموعات والعناصر الأفقيةنسخ رابط العنوان

استخدم orientation="horizontal" مع FieldContent لمربع اختيار أو مفتاح تبديل، وFieldSet مع FieldLegend لمجموعة أزرار اختيار أو عدة مربعات اختيار. ويعطي FieldItem كل زر اختيار تسميته ونصه المساعد.

<Field orientation="horizontal">
  <Checkbox />
  <FieldContent>
    <FieldLabel>أوافق على الشروط</FieldLabel>
    <FieldDescription>يمكنك سحب الموافقة لاحقًا.</FieldDescription>
  </FieldContent>
</Field>

RTLنسخ رابط العنوان

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

إمكانية الوصولنسخ رابط العنوان

• تربط Base UI التسمية بعنصر التحكم، فتكون اسمه المتاح لتقنيات المساعدة.
• يُضاف FieldDescription وFieldError إلى aria-describedby الخاص بالعنصر، فيُقرآن بعد التسمية.
• لعنصر التحكم غير الصالح aria-invalid="true". وللرسالة أيقونة ونص، ولا تعتمد على اللون وحده (WCAG 1.4.1).
• علامة * مخفية عن قارئات الشاشة؛ اضبط required على العنصر ليُعلَن أنه مطلوب.
• تستخدم المجموعات <fieldset> و<legend>، فيُقرأ اسم المجموعة مع كل عنصر.

مرجع APIنسخ رابط العنوان

الاختلافات عن DGAنسخ رابط العنوان

• Field غير موجود في ملف Figma؛ استُخلص من أجزاء التسمية والنص المساعد والخطأ في صفحات الإدخال.
• لا يعتمد الخطأ على اللون وحده: aria-invalid وحد أحمر ورسالة تبدأ بأيقونة.

التبايننسخ رابط العنوان