Обзор
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. Активный шаг применяется к кнопкам, Arrow Up и Arrow Down, колесу прокрутки и перемещению в области скраббинга. Значение 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 нацеливаются на часть, которая их получает. Настройка Input применяется к видимому элементу управления; настройка обёртки относится к Root или Group. Чтобы перевести элемент управления в фокус, используйте Input.ref, а не Root.inputRef.
Каждая часть принимает элемент или обратный вызов через render с соответствующим общедоступным типом состояния. Передайте предоставленные свойства и ref соответствующему элементу DOM, чтобы редактирование, фокус, метки и проверка продолжали работать. Когда элемент управления шагом отображает элемент, не являющийся кнопкой, задайте nativeButton={false}. className и style также принимают обратные вызовы состояния. Состояние включает числовой value, отформатированный inputValue, required, disabled, readOnly, scrubbing и унаследованное состояние Field.
Общедоступные точки входа экспортируют типы свойств и состояния для каждой части, а также NumberFieldRootChangeEventDetails, NumberFieldRootChangeEventReason, NumberFieldRootCommitEventDetails и NumberFieldRootCommitEventReason.
Рендерер компонента Front
Фикстуры песочницы React и Preact проверяют начальное форматирование локали, локализованную вставку, необработанные числовые значения формы, доступные метки, ref, композицию рендеринга, фиксации при потере фокуса, сведения об изменении и фиксации с клавиатуры, а также сведения об изменении указателем. Последовательный ввод после очистки контролируемого локализованного поля в настоящее время сбрасывает каретку в рендерере: ввод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.