نظرة عامة
NumberStepper هو إعداد مسبق مدمج ومريح مبني من NumberField. يجمع بين حقل إدخال نصي رقمي وأزرار اختيارية للإنقاص والزيادة. استورده من twenty-ui/components/input. استخدم NumberField عندما تحتاج إلى خيارات الإعدادات المحلية أو التنسيق، أو خطوات معدِّلة مختلفة، أو المسح، أو تركيب الأجزاء بشكل مستقل.
استخدام
الخيارات المرئية
قارن الحالات الافتراضية والمقيّدة والمعطّلة وللقراءة فقط وغير الصالحة، مع أزرار الخطوات أو بدونها.قيمة غير متحكَّم بها
استخدمdefaultValue لتعيين الكمية الأولية. يتولى حقل الإدخال التغييرات اللاحقة.
قيمة متحكَّم بها
مرّر رقمًا أوnull عبر value وحدّثه في onValueChange للتحكم في الكمية نفسها ضمن حالة React. تتلقى دالة رد الاتصال القيمة الرقمية التالية وتفاصيل الحدث.
null. يبقى النص غير المكتمل، مثل - أو +، قابلاً للتحرير دون الإبلاغ عن رقم غير صالح إلى أن يُستبدل أو يُغيَّر بخطوة. بشكل افتراضي، تُبلِغ التعديلات الرقمية القابلة للتحليل عن القيمة المقيّدة؛ وتُطبَّع المسودة المعروضة عند فقدان التركيز. لا تستدعي القيم المطابقة للقيمة الحالية onValueChange مرة أخرى.
تُبلِغ onValueCommitted(value, details) عن القيمة بعد اعتماد تعديل: عند فقدان التركيز بعد الكتابة أو المسح، وعند تحرير المؤشر بعد تعديل بواسطة زر، وفورًا لتعديلات لوحة المفاتيح. تتضمن تفاصيلها event الأصلي وreason. يحتفظ onValueChange بتفاصيل التغيير، بما فيها أساليب الإلغاء واتجاه التدرج الاختياري.
التحقق من صحة التطبيق
عيّنallowOutOfRange عندما يحتاج التطبيق إلى القيمة المحللة قبل تطبيق حدوده أو التحقق من صحته. يتلقى onValueChange بعد ذلك الأرقام المكتوبة والملصقة خارج النطاق. تحافظ الحقول غير المتحكَّم بها، أو الحقول المتحكَّم بها التي تقبل تلك القيم، عليها عند فقدان التركيز. تعود الحقول المتحكَّم بها التي ترفضها إلى قيمتها المقبولة عند فقدان التركيز. على سبيل المثال، يؤدي استبدال 60 بـ 45 إلى الإبلاغ عن 4 ثم 45، حتى عندما يكون min={30}. يمكن للتطبيق تجاهل القيمة الوسيطة دون حفظ الحد الأدنى عن طريق الخطأ.
تظل الأزرار وتعديلات لوحة المفاتيح متوقفة عند min وmax. يمنع التحقق الأصلي من صحة النموذج الإرسال ما دامت قيمة مقبولة خارج ذلك النطاق. القيمة الافتراضية لـ allowOutOfRange هي false.
الحدود والتفاعل
يشملmin وmax القيمتين الحدّيتين. تتوقف أزرار الزيادة والنقصان عند الحد المطابق. يضبط السهم لأعلى والسهم لأسفل حقل الإدخال ذي التركيز بمقدار step، الذي تكون قيمته الافتراضية 1. يحدّد Home وEnd الحد المطابق عند توفيره؛ استدعِ event.preventBaseUIHandler() في onKeyDown للاحتفاظ بسلوك تحرير النص للمفتاح بدلًا من ذلك. تنطبق الخطوة نفسها عند الضغط باستمرار على Shift أو Alt. تدعم القيم المعروضة حتى 15 رقمًا كسريًا؛ استخدم خطوة موجبة ضمن هذه الدقة للتعديلات العشرية.
تستخدم القيم أرقامًا لاتينية وتعرض فواصل تجميع بدءًا من خمسة أرقام صحيحة، مثل 12,500. تُقبل فواصل التجميع الخاصة بالإعدادات المحلية للمتصفح عند الكتابة واللصق.
يتحكم step في التعديلات؛ ولا يقرّب القيم المكتوبة إلى خطوة. عند تعيين min، يتطلب التحقق الأصلي من صحة النموذج أيضًا min زائد مضاعف لـ step: مع القيمة الافتراضية 1 لـ step، تمنع القيمة المكتوبة 2.5 الإرسال. عيّن showButtons={false} لتحرير النص مع سلوك لوحة المفاتيح نفسه.
لكل زر اسم افتراضي متاح. استخدم decrementLabel وincrementLabel لتوفير أسماء سياقية أو مترجمة. امنح حقل الإدخال Field.Label مرئيًا، أو aria-label، أو aria-labelledby.
النماذج والتركيز
استخدمname لتضمين القيمة الرقمية في نموذج. يربطه form بنموذج في موضع آخر من المستند. تستخدم أزرار التعديل type="button"، لذا لا يؤدي تعديل قيمة إلى إرسال النموذج. يشارك required في التحقق الأصلي من الصحة.
استخدم value متحكَّمًا بها عندما يحتاج تطبيقك إلى إعادة تعيين الحقل. لا تؤدي إعادة تعيين نموذج أصلية إلى إعادة تعيين الحالة الرقمية.
يمنع disabled التغييرات ويستبعد القيمة من إرسال النموذج. يمنع readOnly التغييرات مع الإبقاء على قابلية تركيز حقل الإدخال وإتاحة قيمته للنموذج.
تنطبق سمات ومعالجات حقل الإدخال الأصلية، وclassName، وstyle، وref، وrender على حقل إدخال النص المرئي. يتلقى المرجع HTMLInputElement؛ استدعِ ref.current?.focus() لتركيزه. عند التركيب عبر render، مرّر الخصائص والمرجع المقدَّمين إلى حقل إدخال أصلي. خصّص التخطيط المحيط بعنصر منفصل، أو استخدم جزأي NumberField.Root وNumberField.Group عند الحاجة إلى الوصول إلى الغلاف. اجمع حقل الإدخال مع Field.Description وField.Error للحصول على رسائل الإرشاد والتحقق من الصحة.
يستخدم الإعداد المسبق عمدًا تنسيقًا مدمجًا، وأرقامًا لاتينية، وما يصل إلى 15 رقمًا كسريًا، وتجميعًا بدءًا من خمسة أرقام صحيحة، وstep نفسها للتعديلات العادية وتعديلات Shift وAlt. تنطبق هذه الخيارات على NumberStepper فقط. يحتفظ بديل NumberField الكامل بخيارات التنسيق والتدرج الخاصة بـ Base UI.
عارض مكوّن الواجهة الأمامية
تدعم بيئات الاختبار المعزولة لعارضَي React وPreact الكتابة، وتعديلات لوحة المفاتيح، والحدود، وقيم النماذج، والتدرج بالمؤشر، واللصق فوق النص المحدد. يتحقق معرض العارض من هذه التفاعلات في وقتي التشغيل كليهما. كما هو الحال معNumberField، تُبلِغ تعديلات المؤشر عن التغييرات، لكن بيئة الاختبار المعزولة لا تسلّم حاليًا دالة رد الاتصال الخاصة بالاعتماد المطابقة عند تحرير المؤشر. تحتفظ مضيفات React العادية بسلوك الاعتماد الكامل.
الخصائص
boolean
افتراضي:"false"
Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded.
string
افتراضي:"Number field"
A user-friendly description of the input’s role for assistive tech. This is a role
description, not an accessible name — use
Field.Label or aria-label to name the control.string | ((state: NumberFieldInputState) => string | undefined)
Class applied to the visible input.
string
افتراضي:"Decrease value"
Accessible name for the decrement button.
number
Initial number when the field owns its value.
boolean
افتراضي:"false"
Disables the input and both buttons, and omits the form value.
string
ID of the form that owns the submitted numeric value.
string
ID of the visible input. Generated when omitted.
string
افتراضي:"Increase value"
Accessible name for the increment button.
number
Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.
number
Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.
string
Name of the numeric value submitted with a form.
((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)
Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number.
((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) => void)
Called with the committed number or null and generic event details after an edit is committed. Details contain the native event and reason, without change cancellation methods.
boolean
افتراضي:"false"
Prevents numeric changes while keeping the input focusable.
Ref<HTMLInputElement>
Ref to the visible input element.
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. Use a separate element to customize the surrounding layout.
boolean
افتراضي:"false"
Requires a numeric value for native form submission.
boolean
افتراضي:"true"
Shows the decrement and increment buttons.
number
افتراضي:"1"
Amount added or subtracted by the buttons and arrow keys.
CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)
Inline styles applied to the visible input.
number | null
Controlled numeric value. Use null for an empty field.