> ## Documentation Index > Fetch the complete documentation index at: https://docs.twenty.com/llms.txt > Use this file to discover all available pages before exploring further. # حقل الأرقام > أنشئ حقلاً رقمياً بتنسيق محلي، وتدرّج، ونماذج أصلية، ومسح بالسحب. ## نظرة عامة يكشف `NumberField` عن الأجزاء السبعة كافةً لحقل الأرقام Base UI المثبّت: `Root` و`Group` و`Input` و`Decrement` و`Increment` و`ScrubArea` و`ScrubAreaCursor`. استورده من `twenty-ui/primitives/input`. يحتفظ بالحالة الرقمية والتنسيق والتدرّج وتفاصيل الأحداث والتكامل مع النماذج الأصلية في Base UI، مع تنسيق Twenty UI للإدخال والمجموعة وعناصر التحكم في الضبط. للاستخدام مع الإعداد المسبق المضغوط ذي التنسيق الثابت والإعدادات الافتراضية لخطوة المعدِّل، استخدم [NumberStepper](https://docs.twenty.com/ar/ui/components/input/number-stepper.md) من `twenty-ui/components/input`. **Light** [مثال NumberField (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--display\&viewMode=story\&globals=colorScheme:light) **Dark** [مثال NumberField (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--display\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--display) ## استخدام `Root` يمتلك الحالة الرقمية. `Input` هو إدخال النص المرئي. استخدم `Group` لترتيب عنصري التحكم الاختياريين للإنقاص والزيادة حوله. وفّر المحتوى والأسماء المتاحة لعناصر التحكم؛ فلا يضيف البدائي أيقونات أو تسميات. ```tsx theme={null} import { IconMinus, IconPlus } from 'twenty-ui/icon'; import { Field, NumberField } from 'twenty-ui/primitives/input'; export const QuantityInput = () => ( Quantity Choose up to ten items. ); ``` ترتبط `Field.Label` و`Field.Description` و`Field.Error` بالإدخال المرئي. بدلًا من ذلك، مرّر `aria-label` أو `aria-labelledby` إلى `Input`. القيمة الافتراضية لـ `aria-roledescription` هي `Number field`؛ وهي لا توفّر اسمًا متاحًا. ## القيم ودوال الاستدعاء احذف `value` لحقل غير متحكَّم فيه، ووفّر `defaultValue` رقميًا عند الحاجة إلى قيمة أولية. يبدأ فارغًا عند حذف `defaultValue`. لحقل متحكَّم فيه، مرّر رقمًا أو `null` عبر `value` وحدّثه من `onValueChange`. ```tsx theme={null} import { useState } from 'react'; import { Field, NumberField } from 'twenty-ui/primitives/input'; export const PriceInput = () => { const [price, setPrice] = useState(null); const [savedPrice, setSavedPrice] = useState(null); return ( Price Last committed price: {savedPrice ?? 'empty'} ); }; ``` ينتج عن المسح `null`، بما في ذلك عند ضبط `min`. تظل المسودات غير المكتملة مثل `-` قابلة للتحرير من دون الإبلاغ عن رقم غير صالح. تؤدي الكتابة القابلة للتحليل إلى تحديث القيمة الرقمية قبل تثبيت التحرير. تبدأ الخطوة الأولى من قيمة فارغة من الصفر المقيَّد بالحدود؛ وتستخدم الخطوات اللاحقة مقدار الخطوة النشط. يحتفظ `onValueChange(value, details)` بـ `event` و`reason` و`cancel` و`allowPropagation` و`isCanceled` و`isPropagationAllowed` و`trigger` و`direction` الاختياري. تميّز الأسباب بين الكتابة (`input-change`) والمسح (`input-clear`) والتسوية عند فقدان التركيز (`input-blur`) واللصق (`input-paste`) ولوحة المفاتيح وضغوط الزيادة أو الإنقاص والعجلة والسحب والتعبئة التلقائية الأصلية (`none`). يمنع استدعاء `cancel()` تحديث الحالة الرقمية؛ لكن المتحكّمين يختارون قيمتهم المقبولة مع ذلك. يُشغَّل `onValueCommitted(value, details)` عند فقدان التركيز بعد التحرير، وعند تحرير المؤشر بعد التخطي أو السحب، وفورًا لتعديلات لوحة المفاتيح والعجلة. يثبّت المسح `null` عند فقدان التركيز. تحتوي تفاصيل التثبيت على `event` و`reason`؛ وهي تفاصيل عامة بلا أساليب لإلغاء التغيير. لا يؤدي التركيز على حقل لم يُلمس ثم فقدان التركيز عنه إلى تثبيت قيمة بحد ذاته عندما لا تكون هناك حاجة إلى تسوية رقمية. يمكن لخيارات التقريب الصريحة تسوية قيمة لم تُلمس وتثبيتها. ## الإعدادات المحلية والتنسيق اضبط `locale` و`format` على `Root`. يحتفظان بعقد Base UI المثبّت: يقبل `locale` ‏`Intl.LocalesArgument`، ويقبل `format` ‏`Intl.NumberFormatOptions`. تنسيق العرض منفصل عن القيمة الرقمية الأولية التي يرسلها النموذج. لا يفرض البدائي أرقامًا لاتينية أو تجميعًا أو دقة أو خطوات معدِّل. **Light** [تنسيق الإعدادات المحلية والعملة (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--locale-currency\&viewMode=story\&globals=colorScheme:light) **Dark** [تنسيق الإعدادات المحلية والعملة (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--locale-currency\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--locale-currency) ```tsx theme={null} import { Field, NumberField } from 'twenty-ui/primitives/input'; export const AmountInput = () => ( Amount in euros ); ``` تستخدم الكتابة واللصق الإعدادات المحلية المضبوطة ورموز التنسيق المدعومة. يُسوّي فقدان التركيز النص المعروض. يمكن لخيارات الدقة أو التقريب الصريحة أيضًا تسوية الرقم المثبّت؛ ومن دون تلك الخيارات، لا يستبدل التنسيق وحده قيمة رقمية لم تُلمس بنص عرض مقرّب. ## التخطي والحدود القيمة الافتراضية لـ `step` هي `1`، ولـ `smallStep` هي `0.1` أثناء الضغط على Alt، ولـ `largeStep` هي `10` أثناء الضغط على Shift. تنطبق الخطوة النشطة على الأزرار والسهم للأعلى والسهم للأسفل والعجلة وحركة منطقة السحب. القيمة الافتراضية لـ `snapOnStep` هي `false`؛ فعّله لمحاذاة التعديلات مع الخطوة النشطة. يحدّد Home وEnd الحد الصريح المقابل. يمكن لمعالجات المفاتيح الأصلية استدعاء `event.preventBaseUIHandler()` عندما يحتاج المالك إلى تجاوز سلوك لوحة مفاتيح Base UI. `min` و`max` شاملان. تظل تفاعلات التخطي ضمن الحدود. افتراضيًا، تُقيَّد القيم المكتوبة والملصقة رقميًا أيضًا، مع تسوية المسودة عند فقدان التركيز. اضبط `allowOutOfRange` لقبول التعديلات المباشرة خارج تلك الحدود، والسماح للتحقق الأصلي من النطاق أو تحقق التطبيق بالإبلاغ عن المشكلة. يعطّل `step="any"` التحقق الأصلي من الخطوة، بينما يستخدم التخطي التفاعلي `1` وخطوات المعدِّل المضبوطة. مع خطوة رقمية، وفّر `min` صراحةً عندما يجب أن يتحقق الإرسال الأصلي من محاذاة الخطوة. لا تقرّب الخطوة الرقمية كل قيمة مكتوبة إلى خطوة. ## السحب يغيّر `ScrubArea` القيمة الرقمية أثناء تحرك المؤشر. وهو يدعم الحركة الأفقية أو العمودية، و`pixelSensitivity`، و`teleportDistance` الاختياري. تنطبق الخطوة النشطة والحدود أيضًا على السحب. استخدم تسمية مرئية كهدف للسحب مع إبقاء الإدخال متاحًا للتحرير بلوحة المفاتيح. **Light** [اسحب تسمية العرض (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--with-scrubbing\&viewMode=story\&globals=colorScheme:light) **Dark** [اسحب تسمية العرض (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--with-scrubbing\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--with-scrubbing) أنشئ `ScrubAreaCursor` داخل `ScrubArea` للحصول على مؤشر مخصص أثناء السحب مع قفل المؤشر. يُنقل إلى نص المستند أثناء نشاطه. يعود Base UI إلى المؤشر العادي لإدخال اللمس، وقفل المؤشر المرفوض، وWebKit. اضبط `allowWheelScrub` على `Root` للسماح بالضبط بالعجلة أثناء تركيز الإدخال والتمرير فوقه؛ وقيمته الافتراضية هي `false`. ## النماذج وحالة التعطيل يعرض `Root` عنصر `input type="number"` أصليًا مخفيًا لإرسال القيمة الرقمية الأولية والتحقق الأصلي. اضبط `name` و`form` و`required` و`min` و`max` و`step` على `Root`. يمكن أن يربط `form` الحقل بنموذج في موضع آخر من المستند. تستخدم عناصر تحكم الضبط الافتراضية `type="button"`، لذلك لا يؤدي التخطي إلى إرسال النموذج. يمنع `disabled` التفاعل ويستثني القيمة من الإرسال. يمنع `readOnly` التغييرات مع إبقاء الإدخال المرئي قابلاً للتركيز وقيمة نموذجه متاحة. استخدم قيمة متحكَّمًا فيها عندما يجب على التطبيق إعادة تعيين الحالة الرقمية؛ إذ إن إعادة تعيين النموذج الأصلية لا تعيد تعيينها. ## أهداف DOM والتخصيص | الجزء أو الخاصية | هدف DOM وref الافتراضي | | - | - | | `Root` / `Root.ref` | عنصر `div` الخارجي | | `Root.inputRef` | إدخال الرقم الأصلي المخفي | | `Root.id` | يربط معرّف إدخال النص المرئي | | `Group` / `Group.ref` | عنصر `div` للمجموعة | | `Input` / `Input.ref` | عنصر `input type="text"` المرئي | | `Decrement` / `Increment` | أزرار أصلية | | `ScrubArea` | عنصر `span` | | `ScrubAreaCursor` | عنصر `span` يُنقل إلى نص المستند أثناء نشاطه؛ وتكون قيمة ref الخاصة به null بخلاف ذلك | تستهدف السمات الأصلية و`className` و`style` و`render` الجزء الذي يتلقاها. ينطبق تخصيص الإدخال على عنصر التحكم المرئي؛ أما تخصيص الغلاف فيوضع على `Root` أو `Group`. لتركيز عنصر التحكم، استخدم `Input.ref` بدلًا من `Root.inputRef`. يقبل كل جزء عنصرًا أو دالة استدعاء عبر `render`، مع نوع الحالة العامة المقابل. مرّر الخصائص وref المقدمة إلى عنصر DOM المناسب لكي يستمر عمل التحرير والتركيز والتسميات والتحقق. عندما يعرض عنصر تحكم التخطي عنصرًا ليس زرًا، اضبط `nativeButton={false}`. يقبل `className` و`style` أيضًا دوال استدعاء للحالة. تتضمن الحالة `value` الرقمي و`inputValue` المنسق و`required` و`disabled` و`readOnly` و`scrubbing` وحالة Field الموروثة. تصدّر نقاط الإدخال العامة الخصائص ونوع الحالة لكل جزء، بالإضافة إلى `NumberFieldRootChangeEventDetails` و`NumberFieldRootChangeEventReason` و`NumberFieldRootCommitEventDetails` و`NumberFieldRootCommitEventReason`. ## عارض مكوّن الواجهة الأمامية تتحقق تجهيزات صندوق الحماية لـ React وPreact من تنسيق الإعدادات المحلية الأولي، واللصق المترجم محليًا، وقيم النموذج الرقمية الأولية، والتسميات المتاحة، وrefs، وتركيب العرض، والتثبيت عند فقدان التركيز، وتفاصيل التغيير والتثبيت بلوحة المفاتيح، وتفاصيل التغيير بالمؤشر. تؤدي الكتابة المتتابعة بعد مسح حقل محلي متحكَّم فيه حاليًا إلى إعادة تعيين موضع المؤشر في العارض: إذ يمكن أن تؤدي كتابة `2` ثم `3` إلى إنتاج `32`. يمكن أن يتسابق ضبط مؤشر منسق أيضًا مع فقدان التركيز ويترك الإدخال المرئي يعرض القيمة السابقة. تبلغ تعديلات المؤشر عن التغييرات، لكن تحرير المؤشر لا يقدّم دالة استدعاء التثبيت المقابلة؛ وقد يثبّت فقدان التركيز اللاحق باستخدام `input-blur` بدلًا من ذلك. لا يتوفر أيضًا في صندوق الحماية سحب منطقة السحب واستخدام مؤشرها المخصص. لا تؤثر هذه القيود في مضيفات React العادية. ## الإزاحة يُنشأ المرجع من أنواع المكوّنات العامة المثبّتة. تُقبل أيضًا السمات الأصلية ومعالجات الأحداث على الأجزاء التي تعرض عناصر. ### NumberField.Root **Root.allowOutOfRange** `boolean` (default: false) Allows typed, pasted, and autofilled values outside min and max. Native range validation still applies; step interactions remain bounded. **Root.allowWheelScrub** `boolean` (default: false) Allows wheel adjustments while the visible input is focused and hovered. Defaults to false. **Root.children** `ReactNode` Composed NumberField parts and supporting content. **Root.className** `string | ((state: NumberFieldRootState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Root.defaultValue** `number` (default: empty) Initial uncontrolled number. Omit to start empty; the public type accepts a number. **Root.disabled** `boolean` (default: false) Prevents interaction and excludes the value from form submission. **Root.form** `string` ID of the form owning the hidden native number input. **Root.format** `NumberFormatOptions` Intl.NumberFormat options for display and parsing, including currency, units, percent, grouping, and precision. Explicit rounding options can normalize the committed value on blur. **Root.id** `string` ID associated with the visible input. Generated when omitted. **Root.inputRef** `Ref\` Ref to the hidden native number input used for submission and validation. Use Input.ref to focus the visible text input. **Root.largeStep** `number` (default: 10) Amount used while Shift is held. Defaults to 10. **Root.locale** `LocalesArgument` Locale or locale list used to format and parse numbers. Defaults to the runtime locale. **Root.max** `number` Inclusive maximum for stepping and native range validation. **Root.min** `number` Inclusive minimum for stepping and native range validation. **Root.name** `string` Name of the raw numeric value submitted by the hidden input. **Root.onValueChange** `((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) =\> void)` Receives the next number or null and change details with the native event, reason, cancellation and propagation methods, and optional stepping direction. **Root.onValueCommitted** `((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) =\> void)` Receives the committed number or null and generic details containing event and reason. Typing commits on blur; pointer steps and scrubbing commit on release; keyboard and wheel changes commit immediately. **Root.readOnly** `boolean` (default: false) Prevents changes while keeping the visible input focusable. **Root.ref** `Ref\` Ref to the root div, or the element composed through Root.render. **Root.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Root.required** `boolean` (default: false) Requires a numeric value for native form submission. **Root.smallStep** `number` (default: 0.1) Amount used while Alt is held. Defaults to 0.1. **Root.snapOnStep** `boolean` (default: false) Snaps step interactions to multiples of the active step. Defaults to false. **Root.step** `number | "any"` (default: 1) Base amount for buttons, arrow keys, wheel, and scrubbing. Use any to disable native step validation while stepping by 1. **Root.style** `CSSProperties | ((state: NumberFieldRootState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. **Root.value** `number | null` Controlled raw numeric value. Use null for an empty field. ### NumberField.Group **Group.children** `ReactNode` The visible input and any increment or decrement controls. **Group.className** `string | ((state: NumberFieldGroupState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Group.ref** `Ref\` Ref to the group div, or the element composed through Group.render. **Group.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Group.style** `CSSProperties | ((state: NumberFieldGroupState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Input **Input.aria-roledescription** `string` (default: Number field) Describes the role to assistive technology. Defaults to Number field; use Field.Label, aria-label, or aria-labelledby for the accessible name. **Input.className** `string | ((state: NumberFieldInputState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Input.ref** `Ref\` Ref to the visible native text input. **Input.render** `ReactElement\\> | ComponentRenderFn\, HTMLInputElement\>, NumberFieldInputState\>` Composes the visible text input with an element or render callback. Forward the supplied props and ref to an input. Customize layout through Root or Group. **Input.size** `number` Native input size attribute. Use styles to customize visual dimensions. **Input.style** `CSSProperties | ((state: NumberFieldInputState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Increment **Increment.children** `ReactNode` Visible content for the increment control. Supply its accessible name. **Increment.className** `string | ((state: NumberFieldIncrementState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Increment.nativeButton** `boolean` (default: true) Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction. **Increment.ref** `Ref\` Ref to the increment button, or the element composed through render. **Increment.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Increment.style** `CSSProperties | ((state: NumberFieldIncrementState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Decrement **Decrement.children** `ReactNode` Visible content for the decrement control. Supply its accessible name. **Decrement.className** `string | ((state: NumberFieldDecrementState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Decrement.nativeButton** `boolean` (default: true) Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction. **Decrement.ref** `Ref\` Ref to the decrement button, or the element composed through render. **Decrement.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Decrement.style** `CSSProperties | ((state: NumberFieldDecrementState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.ScrubArea **ScrubArea.children** `ReactNode` Content the user can drag to adjust the number, plus an optional ScrubAreaCursor. **ScrubArea.className** `string | ((state: NumberFieldScrubAreaState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **ScrubArea.direction** `"horizontal" | "vertical"` (default: horizontal) Pointer movement direction used for scrubbing. **ScrubArea.pixelSensitivity** `number` (default: 2) Pixels of pointer movement needed for a step. Larger values reduce sensitivity. **ScrubArea.ref** `Ref\` Ref to the scrub area span, or the element composed through render. **ScrubArea.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **ScrubArea.style** `CSSProperties | ((state: NumberFieldScrubAreaState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. **ScrubArea.teleportDistance** `number` Optional distance from the scrub area center at which the pointer loops around. ### NumberField.ScrubAreaCursor **ScrubAreaCursor.children** `ReactNode` Custom cursor content shown during supported pointer-lock scrubbing. **ScrubAreaCursor.className** `string | ((state: NumberFieldScrubAreaCursorState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **ScrubAreaCursor.ref** `Ref\` Ref to the cursor span portaled to the document body while active. Null while absent. **ScrubAreaCursor.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **ScrubAreaCursor.style** `CSSProperties | ((state: NumberFieldScrubAreaCursorState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.