> ## 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/ru/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`: при стандартном `step`, равном `1`, введённое значение `2.5` блокирует отправку. Установите `showButtons={false}` для редактирования текста с тем же поведением клавиатуры.

У каждой кнопки есть доступное имя по умолчанию. Используйте `decrementLabel` и `incrementLabel`, чтобы задать контекстные или переведённые имена. Задайте полю ввода видимую метку `Field.Label`, `aria-label` или `aria-labelledby`.

## Формы и фокус

Используйте `name`, чтобы включить числовое значение в форму. `form` связывает его с формой в другом месте документа. Кнопки изменения используют `type="button"`, поэтому изменение значения не отправляет форму. `required` участвует в нативной валидации.

Используйте контролируемый `value`, если приложению нужно сбрасывать поле. Нативный сброс формы не сбрасывает числовое состояние.

`disabled` предотвращает изменения и исключает значение из отправки формы. `readOnly` предотвращает изменения, сохраняя возможность фокусировки поля ввода и доступность его значения для формы.

Нативные атрибуты и обработчики поля ввода, `className`, `style`, `ref` и `render` применяются к видимому текстовому полю ввода. Ref получает `HTMLInputElement`; вызовите `ref.current?.focus()`, чтобы установить на нём фокус. При компоновке через `render` передайте предоставленные props и ref в нативное поле ввода. Настройте окружающую компоновку с помощью отдельного элемента или используйте части `NumberField.Root` и `NumberField.Group`, когда требуется доступ к обёртке. Объедините поле ввода с `Field.Description` и `Field.Error` для подсказок и сообщений валидации.

В пресете намеренно используются компактные стили, латинские цифры, до 15 знаков дробной части, группировка начиная с пяти цифр целой части и одинаковый `step` для обычных изменений и изменений с Shift и Alt. Эти настройки применяются только к `NumberStepper`. Полный примитив `NumberField` сохраняет параметры форматирования и изменения шага Base UI.

## Рендерер компонента Front

Песочницы рендереров 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.