> ## 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. # Числовое поле > Создайте числовое поле с локализованным форматированием, пошаговым изменением, нативными формами и перетаскиванием. ## Обзор `NumberField` предоставляет все семь компонентов установленного числового поля Base UI: `Root`, `Group`, `Input`, `Decrement`, `Increment`, `ScrubArea` и `ScrubAreaCursor`. Импортируйте его из `twenty-ui/primitives/input`. Оно сохраняет числовое состояние, форматирование, пошаговое изменение, сведения о событиях и интеграцию с нативными формами из Base UI, добавляя стилизацию Twenty UI для поля ввода, группы и элементов управления изменением значения. Для компактной предустановки с фиксированным форматированием и значениями шагов модификаторов по умолчанию используйте [NumberStepper](https://docs.twenty.com/ru/ui/components/input/number-stepper.md) из `twenty-ui/components/input`. **Light** [Пример NumberField (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--display\&viewMode=story\&globals=colorScheme:light) **Dark** [Пример NumberField (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--display\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--display) ## Использование `Root` управляет числовым состоянием. `Input` представляет собой видимое текстовое поле ввода. Используйте `Group`, чтобы разместить вокруг него необязательные элементы управления уменьшением и увеличением. Предоставьте содержимое и доступные имена для элементов управления; примитив не добавляет значки или метки. ```tsx theme={null} import { IconMinus, IconPlus } from 'twenty-ui/icon'; import { Field, NumberField } from 'twenty-ui/primitives/input'; export const QuantityInput = () => ( Quantity Choose up to ten items. ); ``` `Field.Label`, `Field.Description` и `Field.Error` связываются с видимым полем ввода. В качестве альтернативы передайте `aria-label` или `aria-labelledby` в `Input`. Значение по умолчанию для `aria-roledescription` — `Number field`; оно не предоставляет доступное имя. ## Значения и обратные вызовы Не указывайте `value` для неконтролируемого поля и передавайте числовой `defaultValue`, когда требуется начальное значение. Если не указать `defaultValue`, поле будет изначально пустым. Для контролируемого поля передайте число или `null` через `value` и обновляйте его из `onValueChange`. ```tsx theme={null} import { useState } from 'react'; import { Field, NumberField } from 'twenty-ui/primitives/input'; export const PriceInput = () => { const [price, setPrice] = useState(null); const [savedPrice, setSavedPrice] = useState(null); return ( Price Last committed price: {savedPrice ?? 'empty'} ); }; ``` При очистке передаётся `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`. Форматирование отображения отделено от необработанного числового значения, отправляемого формой. Примитив не принуждает к использованию латинских цифр, группировки, точности или шагов модификаторов. **Light** [Форматирование локали и валюты (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--locale-currency\&viewMode=story\&globals=colorScheme:light) **Dark** [Форматирование локали и валюты (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--locale-currency\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--locale-currency) ```tsx theme={null} import { Field, NumberField } from 'twenty-ui/primitives/input'; export const AmountInput = () => ( Amount in euros ); ``` Ввод и вставка используют настроенную локаль и поддерживаемые символы формата. При потере фокуса отображаемый текст нормализуется. Явные параметры точности или округления также могут нормализовать зафиксированное число; без этих параметров одно лишь форматирование не заменяет нетронутое числовое значение округлённым отображаемым текстом. ## Шаг и границы Значение `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`. Активный шаг и границы также применяются к скраббингу. Используйте видимую метку как цель скраббинга, сохраняя доступность поля ввода для редактирования с клавиатуры. **Light** [Скраббинг метки ширины (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--with-scrubbing\&viewMode=story\&globals=colorScheme:light) **Dark** [Скраббинг метки ширины (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--with-scrubbing\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--with-scrubbing) Составьте `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 и настройка | Часть или свойство | Цель DOM и ref по умолчанию | | - | - | | `Root` / `Root.ref` | Внешний `div` | | `Root.inputRef` | Скрытое нативное числовое поле ввода | | `Root.id` | Связывает ID видимого текстового поля ввода | | `Group` / `Group.ref` | Групповой `div` | | `Input` / `Input.ref` | Видимый `input type="text"` | | `Decrement` / `Increment` | Нативные кнопки | | `ScrubArea` | `span` | | `ScrubAreaCursor` | `span`, портализируемый в тело документа в активном состоянии; в противном случае его ref имеет значение null | Нативные атрибуты, `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 **Root.allowOutOfRange** `boolean` (default: false) Allows typed, pasted, and autofilled values outside min and max. Native range validation still applies; step interactions remain bounded. **Root.allowWheelScrub** `boolean` (default: false) Allows wheel adjustments while the visible input is focused and hovered. Defaults to false. **Root.children** `ReactNode` Composed NumberField parts and supporting content. **Root.className** `string | ((state: NumberFieldRootState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Root.defaultValue** `number` (default: empty) Initial uncontrolled number. Omit to start empty; the public type accepts a number. **Root.disabled** `boolean` (default: false) Prevents interaction and excludes the value from form submission. **Root.form** `string` ID of the form owning the hidden native number input. **Root.format** `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. **Root.id** `string` ID associated with the visible input. Generated when omitted. **Root.inputRef** `Ref\` Ref to the hidden native number input used for submission and validation. Use Input.ref to focus the visible text input. **Root.largeStep** `number` (default: 10) Amount used while Shift is held. Defaults to 10. **Root.locale** `LocalesArgument` Locale or locale list used to format and parse numbers. Defaults to the runtime locale. **Root.max** `number` Inclusive maximum for stepping and native range validation. **Root.min** `number` Inclusive minimum for stepping and native range validation. **Root.name** `string` Name of the raw numeric value submitted by the hidden input. **Root.onValueChange** `((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. **Root.onValueCommitted** `((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. **Root.readOnly** `boolean` (default: false) Prevents changes while keeping the visible input focusable. **Root.ref** `Ref\` Ref to the root div, or the element composed through Root.render. **Root.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Root.required** `boolean` (default: false) Requires a numeric value for native form submission. **Root.smallStep** `number` (default: 0.1) Amount used while Alt is held. Defaults to 0.1. **Root.snapOnStep** `boolean` (default: false) Snaps step interactions to multiples of the active step. Defaults to false. **Root.step** `number | "any"` (default: 1) Base amount for buttons, arrow keys, wheel, and scrubbing. Use any to disable native step validation while stepping by 1. **Root.style** `CSSProperties | ((state: NumberFieldRootState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. **Root.value** `number | null` Controlled raw numeric value. Use null for an empty field. ### NumberField.Group **Group.children** `ReactNode` The visible input and any increment or decrement controls. **Group.className** `string | ((state: NumberFieldGroupState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Group.ref** `Ref\` Ref to the group div, or the element composed through Group.render. **Group.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Group.style** `CSSProperties | ((state: NumberFieldGroupState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Input **Input.aria-roledescription** `string` (default: Number field) Describes the role to assistive technology. Defaults to Number field; use Field.Label, aria-label, or aria-labelledby for the accessible name. **Input.className** `string | ((state: NumberFieldInputState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Input.ref** `Ref\` Ref to the visible native text input. **Input.render** `ReactElement\\> | ComponentRenderFn\, 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. **Input.size** `number` Native input size attribute. Use styles to customize visual dimensions. **Input.style** `CSSProperties | ((state: NumberFieldInputState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Increment **Increment.children** `ReactNode` Visible content for the increment control. Supply its accessible name. **Increment.className** `string | ((state: NumberFieldIncrementState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Increment.nativeButton** `boolean` (default: true) Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction. **Increment.ref** `Ref\` Ref to the increment button, or the element composed through render. **Increment.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Increment.style** `CSSProperties | ((state: NumberFieldIncrementState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Decrement **Decrement.children** `ReactNode` Visible content for the decrement control. Supply its accessible name. **Decrement.className** `string | ((state: NumberFieldDecrementState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Decrement.nativeButton** `boolean` (default: true) Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction. **Decrement.ref** `Ref\` Ref to the decrement button, or the element composed through render. **Decrement.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Decrement.style** `CSSProperties | ((state: NumberFieldDecrementState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.ScrubArea **ScrubArea.children** `ReactNode` Content the user can drag to adjust the number, plus an optional ScrubAreaCursor. **ScrubArea.className** `string | ((state: NumberFieldScrubAreaState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **ScrubArea.direction** `"horizontal" | "vertical"` (default: horizontal) Pointer movement direction used for scrubbing. **ScrubArea.pixelSensitivity** `number` (default: 2) Pixels of pointer movement needed for a step. Larger values reduce sensitivity. **ScrubArea.ref** `Ref\` Ref to the scrub area span, or the element composed through render. **ScrubArea.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **ScrubArea.style** `CSSProperties | ((state: NumberFieldScrubAreaState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. **ScrubArea.teleportDistance** `number` Optional distance from the scrub area center at which the pointer loops around. ### NumberField.ScrubAreaCursor **ScrubAreaCursor.children** `ReactNode` Custom cursor content shown during supported pointer-lock scrubbing. **ScrubAreaCursor.className** `string | ((state: NumberFieldScrubAreaCursorState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **ScrubAreaCursor.ref** `Ref\` Ref to the cursor span portaled to the document body while active. Null while absent. **ScrubAreaCursor.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **ScrubAreaCursor.style** `CSSProperties | ((state: NumberFieldScrubAreaCursorState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.