الحقل

نظرة عامة

استخدم Field لتجميع عنصر تحكم واحد مع تسميته القابلة للوصول ونصه المساعد. تتكامل مكونات مثل Input مباشرةً مع الحقل.

استخدام

import { Field, Input } from 'twenty-ui/primitives/input';

export const EmailField = () => (
  <Field.Root name="email" validationMode="onBlur">
    <Field.Label>Work email</Field.Label>
    <Input type="email" required placeholder="you@example.com" />
    <Field.Description>
      We send account updates to this address.
    </Field.Description>
    <Field.Error match="valueMissing">Enter your email address.</Field.Error>
    <Field.Error match="typeMismatch">Enter a valid email address.</Field.Error>
  </Field.Root>
);

يدير Field.Root اسم عنصر التحكم وحالة تعطيله وصلاحيته. يربط Field.Label وField.Description محتواهما بعنصر التحكم. عيّن توقيت التحقق باستخدام validationMode؛ واستخدم validate للتحقق المخصص.

البنية التشريحية العربية

ضع عنصر تحكم واحدًا وأجزاءه الداعمة داخل Field.Root. تُظهر هذه الشجرة حقلًا مُنشأ باستخدام المكوّن Input المنسّق.

Field.Root
├── Field.Label
├── Input
├── Field.Description
└── Field.Error

الجزء	المتطلبة	الغرض
`Root`	مطلوب	يشارك الاسم وحالة التعطيل والتحقق مع عنصر التحكم.
`Item`	اختياري للمجموعات	يربط كل زر اختيار أو مربع اختيار بتسميته ووصفه الخاصين.
`Label`	مُوصى به	يوفّر تسمية مرئية ومرتبطة. يلزم دائمًا اسم يمكن الوصول إليه.
`Input` أو عنصر تحكم متكامل آخر	مطلوب	يتلقى إدخال المستخدم ويتصل بالحقل.
`Control`	عنصر تحكم بديل	يوفّر إدخالًا بلا تنسيق عندما لا تستخدم عنصر تحكم متكاملًا.
`Description`	اختياري	يضيف نص مساعدة دائمًا مرتبطًا بعنصر التحكم.
`خطأ`	اختياري	يعرض ملاحظات لحالة تحقق مطابقة.
`Validity`	اختياري	يكشف عن الصلاحية عبر دالة تصيير الأبناء.

يتكامل Input وTextarea بالفعل مع الحقل. ضعهما مباشرةً داخل Root؛ فهما يوفّران سلوك عنصر التحكم بنفسيهما. تحتفظ عناصر التحكم المركّبة، مثل تحديد، بجذرها وأجزائها الخاصة داخل الحقل.

أخطاء خارجية

استخدم invalid عندما يكون تطبيقك مسؤولًا عن حالة الخطأ. يجعل match الصريح رسالة الخطأ مرئية.

import { Field, Input } from 'twenty-ui/primitives/input';

type UsernameFieldProps = { error?: string };

export const UsernameField = ({ error }: UsernameFieldProps) => (
  <Field.Root name="username" invalid={Boolean(error)}>
    <Field.Label>Username</Field.Label>
    <Input autoComplete="username" />
    <Field.Error match={Boolean(error)}>{error}</Field.Error>
  </Field.Root>
);

اجعل رسائل الخطأ قابلة للتنفيذ وقدّم تسمية مرئية حتى عندما يحتوي عنصر التحكم على نص نائب.

عناصر التحكم المجمّعة

استخدم Field.Item داخل مجموعة أزرار اختيار أو مربعات اختيار لربط كل خيار بتسمية ووصف خاصين به. أبقِ تسمية المجموعة خارج العناصر. يمكن تعطيل عنصر بشكل مستقل؛ إذ يعطّل Field.Root المعطّل كل عنصر.

import { Field, Radio, RadioGroup } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsField = () => (
  <Field.Root name="notifications">
    <Field.Label>Notifications</Field.Label>
    <RadioGroup defaultValue="important" style={{ gap: 16, marginTop: 12 }}>
      <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>
        <Radio value="important" />
        <Text>
          <Field.Label>Important updates</Field.Label>
          <Field.Description>
            Only messages that need your attention
          </Field.Description>
        </Text>
      </Field.Item>
      <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>
        <Radio value="all" />
        <Text>
          <Field.Label>All updates</Field.Label>
          <Field.Description>Every change to your records</Field.Description>
        </Text>
      </Field.Item>
      <Field.Item
        disabled
        style={{ display: 'flex', alignItems: 'start', gap: 12 }}
      >
        <Radio value="digest" />
        <Text>
          <Field.Label>Daily digest</Field.Label>
          <Field.Description>Coming soon</Field.Description>
        </Text>
      </Field.Item>
    </RadioGroup>
  </Field.Root>
);

التكامل والأنواع الأصلية

يحافظ الحقل على توقيت التحقق في Base UI، والتحقق المخصص، وقيم عناصر التحكم المُتحكَّم بها وغير المُتحكَّم بها، وتفاصيل حدث تغيير القيمة. يكشف Validity عن نتيجة التحقق من خلال دالة الأبناء الخاصة به. تحتفظ عناصر التحكم المتكاملة بسلوك النموذج الأصلي الخاص بها. تمرّر Root وItem وLabel وControl وDescription وError الخصائص الأصلية والمراجع وتكوين render. عناصرها الافتراضية هي div وdiv وlabel وinput وparagraph وdiv، على التوالي. لا يعرض Validity عنصره الخاص. استورد FieldRootProps وFieldItemProps وFieldLabelProps وFieldControlProps وFieldDescriptionProps وFieldErrorProps وFieldValidityProps من twenty-ui/primitives/input لعقود الأجزاء الأساسية المقابلة.

الإزاحة

يُنشأ المرجع من الأنواع العامة للمكونات. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء القابلة للوصول ومعالجات الأحداث، على الأجزاء التي تصيّر عناصر.

Field.Root

RefObject<FieldRootActions | null>

A ref to imperative actions.

validate: Validates the field when called.

string | ((state: FieldRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

Whether the field’s value has been changed from its initial value. Useful when the field state is controlled by an external library.

boolean

افتراضي:"false"

Whether the component should ignore user interaction. Takes precedence over the disabled prop on the <Field.Control> component.

boolean

Whether the field is invalid. Useful when the field state is controlled by an external library.

string

Identifies the field when a form is submitted. Takes precedence over the name prop on the <Field.Control> component.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: FieldRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

boolean

Whether the field has been touched. Useful when the field state is controlled by an external library.

A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid. Returning nothing, null, an empty string, or an empty array means the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using validationMode="onSubmit".

number

افتراضي:"0"

How long to wait between validate callbacks if validationMode="onChange" is used. Specified in milliseconds.

"onBlur" | "onChange" | "onSubmit"

افتراضي:"onSubmit"

Determines when the field should be validated. This takes precedence over the validationMode prop on <Form>.

onSubmit: triggers validation when the form is submitted, and re-validates on change after submission.
onBlur: triggers validation when the control loses focus.
onChange: triggers validation on every change to the control value.

Field.Item

string | ((state: FieldItemState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

افتراضي:"false"

Whether the wrapped control should ignore user interaction. The disabled prop on <Field.Root> takes precedence over this.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldItemState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: FieldItemState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Label

string | ((state: FieldLabelState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

افتراضي:"true"

Whether the component renders a native <label> element when replacing it via the render prop. Set to false if the rendered element is not a label (for example, <div>).This is useful to avoid inheriting label behaviors on <button> controls (such as <Select.Trigger> and <Combobox.Trigger>), including avoiding :hover on the button when hovering the label, and preventing clicks on the label from firing on the button.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldLabelState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: FieldLabelState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Control

string | ((state: FieldControlState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

string | number | readonly string[]

The default value of the input. Use when uncontrolled.

((value: string, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)

Callback fired when the value changes. Use when controlled.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldControlState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: FieldControlState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Description

string | ((state: FieldDescriptionState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldDescriptionState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: FieldDescriptionState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Error

string | ((state: FieldErrorState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean | keyof ValidityState

Determines whether to show the error message according to the field’s ValidityState. Specifying true will always show the error message, and lets external libraries control the visibility.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldErrorState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: FieldErrorState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

Field.Validity

(state: FieldValidityState) => ReactNode

مطلوب

A function that accepts the field validity state as an argument.

<Field.Validity>
  {(validity) => {
    return <div>...</div>
  }}
</Field.Validity>

المطورون

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

مكتبة واجهة المستخدم

نظرة عامة

استخدام

البنية التشريحية العربية

أخطاء خارجية

عناصر التحكم المجمّعة

التكامل والأنواع الأصلية

الإزاحة

Field.Root

Field.Item

Field.Label

Field.Control

Field.Description

Field.Error

Field.Validity

​نظرة عامة

​استخدام

​البنية التشريحية العربية

​أخطاء خارجية

​عناصر التحكم المجمّعة

​التكامل والأنواع الأصلية

​الإزاحة

​Field.Root

​Field.Item

​Field.Label

​Field.Control

​Field.Description

​Field.Error

​Field.Validity

نظرة عامة

استخدام

البنية التشريحية العربية

أخطاء خارجية

عناصر التحكم المجمّعة

التكامل والأنواع الأصلية

الإزاحة

Field.Root

Field.Item

Field.Label

Field.Control

Field.Description

Field.Error

Field.Validity