DateTimeField

DateTimeField — составной компонент для совместного ввода даты и времени, который согласует ввод с клавиатуры, необязательный выбор в календаре и правила метки времени в одном поле.

Storybook Исходники

Пропсы корня

Проп	Тип	По умолчанию
`value`	`string`	—
Контролируемые дата и время в виде строки `YYYY-MM-DDTHH:mm` (с `:ss`, когда формат содержит секунды); `''`, пока в поле нет полного значения.
`defaultValue`	`string`	`''`
Начальные дата и время для неконтролируемого использования, как у `value`. По умолчанию `''` — пустое поле.
`onChangeValue`	`(value: string) => void`	—
Вызывается с датой и временем при их изменении и с `''`, когда текст очищен или не заполнен до конца.
`dateFormat`обязательный	`string`	—
Шаблон формата даты для маски ввода и разбора. Определяет порядок сегментов даты. Примеры: "dd.MM.yyyy"; "MM/dd/yyyy"; "yyyy-MM-dd"
`timeFormat`	`'HH:mm' \| 'HH:mm:ss'`	`'HH:mm'`
Шаблон формата времени для маски ввода и разбора в нотации `dateFormat` (шаблоны дат Unicode). Определяет, какие сегменты времени доступны в поле. Примеры: "HH:mm" — часы и минуты. "HH:mm:ss" — часы, минуты и секунды.
`timeStep`	`number`	`1`
Шаг ArrowUp / ArrowDown для минут или секунд под кареткой, с переходом по кругу в пределах диапазона сегмента. Как у нативного поля `datetime-local` со `step`, часы всегда меняются на один. `0` отключает шаг стрелками. Введённые значения к шагу не привязываются.
`separator`	`string`	`', '`
Символ-разделитель сегментов (даты и времени) в поле. Примеры: ","; "-"
`dateSeparator`	`string`	`'.'`
Символ-разделитель сегментов даты в поле. Примеры: ","; "-"
`min`	`string`	—
Минимально допустимые дата и время в виде строки `YYYY-MM-DDTHH:mm[:ss]`. Даты раньше этого значения нельзя выбрать; при разборе ввода они ограничиваются или отклоняются.
`max`	`string`	—
Максимально допустимые дата и время в виде строки `YYYY-MM-DDTHH:mm[:ss]`. Даты позже этого значения нельзя выбрать; при разборе ввода они ограничиваются или отклоняются.
`disabledDates`	`CalendarDatesDisabled`	—
Правила отключения отдельных дат в календаре. Можно использовать, чтобы блокировать диапазоны, дни недели или собственные условия.
`disabled`	`boolean`	—
Отключает поле. Запрещает ввод и взаимодействие и применяет визуальное отключённое состояние.
`calendar`	`CalendarSystem`	`gregorianCalendar`
Календарная система, в которой дата вводится и выбирается. Значение остаётся строкой `YYYY-MM-DDTHH:mm[:ss]`. По умолчанию — григорианский календарь.
`locale`	`string`	—
Локаль BCP 47 всплывающего календаря (названия месяцев и дней, первый день недели), например `de-DE`. Формат ввода по-прежнему задаётся `format`. По умолчанию — локаль среды выполнения, как у `Intl`.
`size`	`TextFieldSize`	—
Визуальный размер текстового поля. Влияет на отступы, размер шрифта и общую высоту. 'sm': компактное поле; 'md': по умолчанию; 'lg': просторная раскладка
`ref`	`Ref<HTMLDivElement>`	—
Ref, передаваемый на элемент-обёртку. Полезен для программного управления, фокуса или интеграции.
`error`	`boolean`	—
Показывает поле ввода в состоянии ошибки.

Также принимает все атрибуты <div>.

Дочерние части

DateTimeFieldInput: поле для ввода метки времени с клавиатуры.
DateTimeFieldTriggerIconButton: необязательная кнопка-триггер календаря.
DateTimeFieldCalendar: содержимое календаря, синхронизированное со значением поля.

`DateTimeFieldInput`

Проп	Тип	По умолчанию
`ref`	`Ref<HTMLInputElement>`	—
Ref, передаваемый на нижележащий нативный элемент `<input>`.

Также принимает все атрибуты <input>.

`DateTimeFieldCalendar`

Проп	Тип	По умолчанию
`max`	`string`	—
Самая поздняя доступная для выбора дата в виде строки `YYYY-MM-DD`. Месяцы и годы после этой даты становятся недоступны. Пикеры дней, месяцев и годов используют её, чтобы отключать или ограничивать навигацию.
`min`	`string`	—
Самая ранняя доступная для выбора дата в виде строки `YYYY-MM-DD`. Месяцы и годы до этой даты становятся недоступны. Все пикеры учитывают это ограничение при вычислении активных диапазонов.
`selection`	`"single"`	—
Режим выбора. Определяет форму `value`, все даты — строки `YYYY-MM-DD`: 'single' — строка, `''`, когда ничего не выбрано; 'multiple' — массив строк; 'range' — кортеж `[start, end]`, где `start` не позже `end`, а `''` обозначает незаданную границу. По умолчанию: `'single'`
`view`	`CalendarView`	—
Контролируемый видимый вид: 'day' — дни видимого месяца (`CalendarDays`); 'month' — месяцы видимого года (`CalendarMonths`); 'year' — страницы годов (`CalendarYears`)
`value`	`string`	—
Контролируемое значение выбора, форма которого зависит от режима `selection`. Некорректные или несуществующие даты считаются невыбранными.
`defaultValue`	`string`	—
Неконтролируемое начальное значение выбора, форма которого зависит от режима `selection`.
`defaultView`	`CalendarView`	—
Начальный вид для неконтролируемого использования. По умолчанию: `'day'`
`disabled`	`boolean`	—
Отключает весь календарь: ни одну дату нельзя выбрать, навигация выключена.
`disabledDates`	`CalendarDatesDisabled`	—
Даты, которые нельзя выбрать, в виде строк `YYYY-MM-DD`: одна дата; массив дат; предикат `(date: string) => boolean`
`onChangeValue`	`(value: CalendarValue<S>) => void`	—
Вызывается, когда пользователь меняет выбор. Форма значения зависит от режима `selection`.
`onChangeView`	`(view: CalendarView) => void`	—
Вызывается при изменении видимого вида.
`month`	`string`	—
Контролируемый видимый месяц — строка `YYYY-MM-DD` любого дня этого месяца.
`defaultMonth`	`string`	—
Начальный видимый месяц для неконтролируемого использования — строка `YYYY-MM-DD` любого дня этого месяца. По умолчанию: месяц выбранной даты, иначе текущий месяц
`onChangeMonth`	`(month: string) => void`	—
Вызывается с первым днём видимого месяца в виде строки `YYYY-MM-DD`, когда видимый месяц меняется (например, при прокрутке или через пикеры месяца и года). Это событие отражает навигацию по виду, а не выбор.
`calendar`	`CalendarSystem`	—
Календарная система, в которой показывается календарь. Значения остаются днями в формате `YYYY-MM-DD`. По умолчанию — григорианский календарь.
`locale`	`string`	—
Локаль BCP 47 для названий месяцев и дней и первого дня недели, например `de-DE`. Применяется ко всем частям календаря и задаёт `lang` на корне. По умолчанию — локаль среды выполнения, как у `Intl`.
`size`	`CalendarBaseSize`	—
Общая шкала размера календаря. Через `CalendarBaseContext` влияет на вложенные элементы управления: кнопки навигации, триггеры пикеров и подписи дней недели.
`variant`	`CalendarBaseVariant`	—
Визуальный вариант календаря. Передаётся через `CalendarBaseContext` и используется вложенными элементами управления (кнопками, подписями и т. д.) для единообразной стилизации.
`compact`	`boolean`	—
Флаг плотности для более компактных раскладок. При `true` корневой элемент получает `data-compact="true"`, чтобы стили могли уменьшить отступы, промежутки и высоту элементов управления для более плотного календаря. При `false` или `undefined` календарь использует обычные интервалы.

Также принимает все атрибуты <div>.

`DateTimeFieldTriggerIconButton`

Проп	Тип	По умолчанию
`size`	`IconButtonSize`	—
Размер контейнера кнопки. Управляет отступами и общей кликабельной областью.
`asChild`	`boolean`	—
Если true, рендерит кнопку как дочерний компонент через `Slot` (например, из Radix UI). Включает полиморфный рендер — полезно, чтобы кнопка работала как ссылка или собственный тег.
`variant`	`ButtonBaseVariant`	—
Определяет визуальный стиль кнопки: цветовую схему и акцент.
`appearance`	`ButtonBaseAppearance`	—
Настраивает структурный внешний вид кнопки (фон, рамка и т. д.).
`disabled`	`boolean`	—
Отключает кнопку при true. Запрещает взаимодействие и применяет визуальное отключённое состояние. Не применяется с `asChild`: отключённым состоянием владеет дочерний элемент, например через `aria-disabled` или ссылку без `href`.
`className`	`string`	—
Необязательный собственный CSS-класс для элемента кнопки. Полезен для переопределений дизайн-системы или локальных стилей.
`children`	`ReactNode`	—
Содержимое кнопки — текст, иконка или любой React-узел.
`ref`	`Ref<HTMLButtonElement>`	—
Ref, передаваемый на нативный элемент `<button>`. Даёт прямой доступ к DOM для управления фокусом или измерений.

Также принимает все атрибуты <button>.

Типы

DateTimeFieldProps
DateTimeFieldInputProps
DateTimeFieldTriggerIconButtonProps
DateTimeFieldCalendarProps

Модель состояния

Корень владеет одной общей моделью метки времени.
Разбор даты и разбор времени настраиваются отдельно через dateFormat, dateSeparator, timeFormat и timeStep.
Частичные значения во время редактирования — обычное дело, и их не стоит слишком рано считать валидной итоговой меткой времени.
Корень принимает value, defaultValue и onChangeValue как метку времени YYYY-MM-DDTHH:mm (с :ss, если формат содержит секунды), как нативный datetime-local; DateTimeFieldInput показывает её в заданном формате и по-прежнему вызывает собственные onChange и onInput. Пока текст пуст или неполон, значение равно '', и в календаре ничего не выбрано. Сброс формы восстанавливает defaultValue, если поле не контролируемое.
При изменении min или max введённый текст снова ограничивается так же, как при вводе, с событием input.
Нормализация часового пояса по-прежнему остаётся на стороне потребителя.