> ## 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.

# مُدرِّج الأرقام

> حرّر رقمًا بحدود اختيارية وأزرار للزيادة أو النقصان.

## نظرة عامة

`NumberStepper` هو إعداد مسبق مدمج ومريح مبني من [NumberField](https://docs.twenty.com/ar/ui/primitives/input/number-field.md). يجمع بين حقل إدخال نصي رقمي وأزرار اختيارية للإنقاص والزيادة. استورده من `twenty-ui/components/input`. استخدم `NumberField` عندما تحتاج إلى خيارات الإعدادات المحلية أو التنسيق، أو خطوات معدِّلة مختلفة، أو المسح، أو تركيب الأجزاء بشكل مستقل.

**Light**

[مثال NumberStepper (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال NumberStepper (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberstepper--display)

## استخدام

```tsx theme={null}
import { NumberStepper } from 'twenty-ui/components/input';
import { Field } from 'twenty-ui/primitives/input';

export const QuantityInput = () => (
  <Field.Root>
    <Field.Label style={{ color: 'var(--t-font-color-primary)' }}>
      Quantity
    </Field.Label>
    <NumberStepper defaultValue={3} min={0} max={10} />
    <Field.Description style={{ color: 'var(--t-font-color-secondary)' }}>
      Choose up to ten items.
    </Field.Description>
  </Field.Root>
);
```

## الخيارات المرئية

قارن الحالات الافتراضية والمقيّدة والمعطّلة وللقراءة فقط وغير الصالحة، مع أزرار الخطوات أو بدونها.

**Light**

[حدود حالات أداة زيادة الأرقام وخفضها وحالاتها (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[حدود حالات أداة زيادة الأرقام وخفضها وحالاتها (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberstepper--catalog)

## قيمة غير متحكَّم بها

استخدم `defaultValue` لتعيين الكمية الأولية. يتولى حقل الإدخال التغييرات اللاحقة.

```tsx theme={null}
import { NumberStepper } from 'twenty-ui/components/input';
import { Field } from 'twenty-ui/primitives/input';

export const QuantityInput = () => (
  <Field.Root>
    <Field.Label>Quantity</Field.Label>
    <NumberStepper name="quantity" defaultValue={3} min={0} max={10} step={1} />
    <Field.Description>Choose up to ten items.</Field.Description>
  </Field.Root>
);
```

## قيمة متحكَّم بها

مرّر رقمًا أو `null` عبر `value` وحدّثه في `onValueChange` للتحكم في الكمية نفسها ضمن حالة React. تتلقى دالة رد الاتصال القيمة الرقمية التالية وتفاصيل الحدث.

```tsx theme={null}
import { useState } from 'react';
import { NumberStepper } from 'twenty-ui/components/input';
import { Field } from 'twenty-ui/primitives/input';

export const QuantityInput = () => {
  const [quantity, setQuantity] = useState<number | null>(3);

  return (
    <Field.Root>
      <Field.Label>Quantity</Field.Label>
      <NumberStepper
        name="quantity"
        value={quantity}
        onValueChange={setQuantity}
        min={0}
        max={10}
        step={1}
      />
      <Field.Description>Choose up to ten items.</Field.Description>
    </Field.Root>
  );
};
```

يؤدي مسح الحقل إلى الإبلاغ عن `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 العادية بسلوك الاعتماد الكامل.

## الخصائص

**allowOutOfRange** `boolean` (default: false)

Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded.

**aria-roledescription** `string` (default: 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.

**className** `string | ((state: NumberFieldInputState) =\> string | undefined)`

Class applied to the visible input.

**decrementLabel** `string` (default: Decrease value)

Accessible name for the decrement button.

**defaultValue** `number`

Initial number when the field owns its value.

**disabled** `boolean` (default: false)

Disables the input and both buttons, and omits the form value.

**form** `string`

ID of the form that owns the submitted numeric value.

**id** `string`

ID of the visible input. Generated when omitted.

**incrementLabel** `string` (default: Increase value)

Accessible name for the increment button.

**max** `number`

Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.

**min** `number`

Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.

**name** `string`

Name of the numeric value submitted with a form.

**onValueChange** `((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.

**onValueCommitted** `((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.

**readOnly** `boolean` (default: false)

Prevents numeric changes while keeping the input focusable.

**ref** `Ref\<HTMLInputElement\>`

Ref to the visible input element.

**render** `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.

**required** `boolean` (default: false)

Requires a numeric value for native form submission.

**showButtons** `boolean` (default: true)

Shows the decrement and increment buttons.

**step** `number` (default: 1)

Amount added or subtracted by the buttons and arrow keys.

**style** `CSSProperties | ((state: NumberFieldInputState) =\> CSSProperties | undefined)`

Inline styles applied to the visible input.

**value** `number | null`

Controlled numeric value. Use null for an empty field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.