الانتقال إلى المحتوى الرئيسي

نظرة عامة

يكشف NumberField عن الأجزاء السبعة كافةً لحقل الأرقام Base UI المثبّت: Root وGroup وInput وDecrement وIncrement وScrubArea وScrubAreaCursor. استورده من twenty-ui/primitives/input. يحتفظ بالحالة الرقمية والتنسيق والتدرّج وتفاصيل الأحداث والتكامل مع النماذج الأصلية في Base UI، مع تنسيق Twenty UI للإدخال والمجموعة وعناصر التحكم في الضبط. للاستخدام مع الإعداد المسبق المضغوط ذي التنسيق الثابت والإعدادات الافتراضية لخطوة المعدِّل، استخدم NumberStepper من twenty-ui/components/input.

استخدام

Root يمتلك الحالة الرقمية. Input هو إدخال النص المرئي. استخدم Group لترتيب عنصري التحكم الاختياريين للإنقاص والزيادة حوله. وفّر المحتوى والأسماء المتاحة لعناصر التحكم؛ فلا يضيف البدائي أيقونات أو تسميات.
ترتبط Field.Label وField.Description وField.Error بالإدخال المرئي. بدلًا من ذلك، مرّر aria-label أو aria-labelledby إلى Input. القيمة الافتراضية لـ aria-roledescription هي Number field؛ وهي لا توفّر اسمًا متاحًا.

القيم ودوال الاستدعاء

احذف value لحقل غير متحكَّم فيه، ووفّر defaultValue رقميًا عند الحاجة إلى قيمة أولية. يبدأ فارغًا عند حذف defaultValue. لحقل متحكَّم فيه، مرّر رقمًا أو null عبر value وحدّثه من onValueChange.
ينتج عن المسح 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. تنسيق العرض منفصل عن القيمة الرقمية الأولية التي يرسلها النموذج. لا يفرض البدائي أرقامًا لاتينية أو تجميعًا أو دقة أو خطوات معدِّل.
تستخدم الكتابة واللصق الإعدادات المحلية المضبوطة ورموز التنسيق المدعومة. يُسوّي فقدان التركيز النص المعروض. يمكن لخيارات الدقة أو التقريب الصريحة أيضًا تسوية الرقم المثبّت؛ ومن دون تلك الخيارات، لا يستبدل التنسيق وحده قيمة رقمية لم تُلمس بنص عرض مقرّب.

التخطي والحدود

القيمة الافتراضية لـ 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 الاختياري. تنطبق الخطوة النشطة والحدود أيضًا على السحب. استخدم تسمية مرئية كهدف للسحب مع إبقاء الإدخال متاحًا للتحرير بلوحة المفاتيح. أنشئ 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 والتخصيص

تستهدف السمات الأصلية و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

boolean
افتراضي:"false"
Allows typed, pasted, and autofilled values outside min and max. Native range validation still applies; step interactions remain bounded.
boolean
افتراضي:"false"
Allows wheel adjustments while the visible input is focused and hovered. Defaults to false.
ReactNode
Composed NumberField parts and supporting content.
string | ((state: NumberFieldRootState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
number
افتراضي:"empty"
Initial uncontrolled number. Omit to start empty; the public type accepts a number.
boolean
افتراضي:"false"
Prevents interaction and excludes the value from form submission.
string
ID of the form owning the hidden native number input.
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.
string
ID associated with the visible input. Generated when omitted.
Ref<HTMLInputElement>
Ref to the hidden native number input used for submission and validation. Use Input.ref to focus the visible text input.
number
افتراضي:"10"
Amount used while Shift is held. Defaults to 10.
LocalesArgument
Locale or locale list used to format and parse numbers. Defaults to the runtime locale.
number
Inclusive maximum for stepping and native range validation.
number
Inclusive minimum for stepping and native range validation.
string
Name of the raw numeric value submitted by the hidden input.
((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.
((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.
boolean
افتراضي:"false"
Prevents changes while keeping the visible input focusable.
Ref<HTMLDivElement>
Ref to the root div, or the element composed through Root.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldRootState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
boolean
افتراضي:"false"
Requires a numeric value for native form submission.
number
افتراضي:"0.1"
Amount used while Alt is held. Defaults to 0.1.
boolean
افتراضي:"false"
Snaps step interactions to multiples of the active step. Defaults to false.
number | "any"
افتراضي:"1"
Base amount for buttons, arrow keys, wheel, and scrubbing. Use any to disable native step validation while stepping by 1.
CSSProperties | ((state: NumberFieldRootState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.
number | null
Controlled raw numeric value. Use null for an empty field.

NumberField.Group

ReactNode
The visible input and any increment or decrement controls.
string | ((state: NumberFieldGroupState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
Ref<HTMLDivElement>
Ref to the group div, or the element composed through Group.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldGroupState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldGroupState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.

NumberField.Input

string
افتراضي:"Number field"
Describes the role to assistive technology. Defaults to Number field; use Field.Label, aria-label, or aria-labelledby for the accessible name.
string | ((state: NumberFieldInputState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
Ref<HTMLInputElement>
Ref to the visible native text input.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, 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.
number
Native input size attribute. Use styles to customize visual dimensions.
CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.

NumberField.Increment

ReactNode
Visible content for the increment control. Supply its accessible name.
string | ((state: NumberFieldIncrementState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
boolean
افتراضي:"true"
Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction.
Ref<HTMLButtonElement>
Ref to the increment button, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldIncrementState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldIncrementState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.

NumberField.Decrement

ReactNode
Visible content for the decrement control. Supply its accessible name.
string | ((state: NumberFieldDecrementState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
boolean
افتراضي:"true"
Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction.
Ref<HTMLButtonElement>
Ref to the decrement button, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldDecrementState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldDecrementState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.

NumberField.ScrubArea

ReactNode
Content the user can drag to adjust the number, plus an optional ScrubAreaCursor.
string | ((state: NumberFieldScrubAreaState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
"horizontal" | "vertical"
افتراضي:"horizontal"
Pointer movement direction used for scrubbing.
number
افتراضي:"2"
Pixels of pointer movement needed for a step. Larger values reduce sensitivity.
Ref<HTMLSpanElement>
Ref to the scrub area span, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldScrubAreaState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.
number
Optional distance from the scrub area center at which the pointer loops around.

NumberField.ScrubAreaCursor

ReactNode
Custom cursor content shown during supported pointer-lock scrubbing.
string | ((state: NumberFieldScrubAreaCursorState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
Ref<HTMLSpanElement>
Ref to the cursor span portaled to the document body while active. Null while absent.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaCursorState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldScrubAreaCursorState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.