Перейти к основному содержанию

Обзор

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: при стандартном 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 сохраняют полное поведение подтверждения.

Свойства

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.