DateInput

Компонент для поля даты и времени. Позволяет пользователю вводить дату как вручную, так и выбирать значение через календарь.

Загружается...

Применение компонента

Данный компонент представляет собой поле формы с возможностью вызова календаря.

Если вам нужно поле ввода диапазона дат (со всплывающим календарём), то используйте компонент DateRangeInput.

Если вам нужен отдельный компонент календаря для выбора даты и времени, то используйте Calendar.

Режим работы

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение React-компонентов, прочитать про это можно в документации React ↗.

Для использования неконтролируемого режима достаточно просто не передавать value или передавать defaultValue, если требуется задать значение по умолчанию. Для контролируемого режима используйте связку свойств value/onChange для задания значения и его изменения.

// Неконтролируемое состояние
<DateInput defaultValue={new Date()} accessible />;
 
// Контролируемое состояние
const [date, setDate] = React.useState(new Date());
 
<DateInput value={date} onChange={setDate} accessible />;

Состояния

`disabled`

Свойство disabled блокирует взаимодействие с компонентом и добавляет визуальную индикацию недоступности.

Загружается...

Валидация

Свойство status используется для визуализации валидации компонента - некорректности заполненного поля (значение "error") или успешной валидации (значение "valid").

Загружается...

Тестирование (e2e)

Для тестирования компонента можно использовать следующие свойство определяющие data-testid атрибуты:

dayFieldTestId — поле ввода дня;
monthFieldTestId — поле ввода месяца;
yearFieldTestId — поле ввода года;
hourFieldTestId — поле ввода часа;
minuteFieldTestId — поле ввода минут.

Подробности смотри в Свойства и методы.

Компонент обеспечивает базовую доступность, но по умолчанию компонент всё ещё сложно использовать пользователям ассистивных технологий. Мы доработали компонент так, чтобы сделать его доступным, но это потребовало ломающих изменений в визуальном поведении компонента.

Новое, доступное поведение можно включить с помощью нового свойства accessible.

Вот список изменений которые отличают поведение со свойством accessible от поведения по умолчанию:

иконка календаря видна постоянно (раньше она была видна, только если в DateInput нет значения);
календарь открывается только по клику по иконке календаря, по клику на поле ввода и нажатию клавиши <Space>, если DateInput в фокусе (раньше он открывался сразу при фокусе на DateInput);
при открытии календарь получает фокус. При закрытии календаря фокус возвращается на DateInput. Если нужно отключить это поведение, используйте свойство disableFocusTrap. Если нужно больше контроля над тем, куда возвращать фокус, используйте свойство restoreFocus.

Из-за особенности реализации DateInput, если вкладывать его внутрь label, или связывать label и DateInput через htmlFor, то по клику на label фокус будет попадать на DateInput, но текст label скринридером зачитываться в момент фокуса не будет. Рекомендуем дублировать текст label в DateInput, передавая в DateInput текст через свойство aria-label.

<label>
  День рождения
  <DateInput aria-label="День рождения" accessible />
</label>

<label htmlFor="date"> День рождения</label>
<DateInput id="date" aria-label="День рождения" accessible />

<FormItem top="День рождения" htmlFor="date">
  <DateInput id="date" aria-label="День рождения" accessible />
</FormItem>

Интернационализация (i18n)

Формат дат и их перевод задаётся с помощью средств браузера Intl.DateTimeFormat ↗. Тем не менее компонент, в том числе и календарь, имеют большое количество внутренних интерактивных элементов, которые должны иметь описание. Особенно важно для доступности (a11y), так как большинство подписей зрячему пользователю не видны, но критически важны пользователям скринридеров.

Ниже приведён список свойств, которые стоит использовать, если требуется перевести компонент на другой язык. Полный список ищите в таблице свойств компонента ниже.

changeHoursLabel;
changeMinutsLabel;
changeDayLabel;
changeMonthLabel;
changeYearLabel;
prevMonthLabel;
nextMonthLabel;
clearFieldLabel;
showCalendarLabel;
calendarLabel.

Свойства и методы

Свойство	Описание
`accessible`	`boolean` Включает режим в котором DateInput доступен для ассистивных технологий. В этом режиме: календарь больше не открывает при фокусе на DateInput; иконка календаря видна всегда, чтобы пользователи ассистивных технологий могли открыть календарь по клику на иконку; календарь при открытии получает фокус, клавиатурный фокус зациклен и не выходит за пределы календаря пока календарь не закрыт. По умолчанию: `-`
`after`	`ReactNode` Добавляет иконку справа. Рекомендации: Используйте следующие размеры иконок `12` \| `16` \| `20` \| `24` \| `28`. Используйте IconButton ↗, если вам нужна иконка, реагируюущая на нажатие. По умолчанию: `-`
`afterAlign`	`FieldIconsAlign` Вертикальное выравнивание иконки справа. По умолчанию: `-`
`before`	`ReactNode` Добавляет иконку слева. Рекомендации: Используйте следующие размеры иконок `12` \| `16` \| `20` \| `24` \| `28`. Используйте IconButton ↗, если вам нужна иконка, реагирующая на нажатие. По умолчанию: `-`
`beforeAlign`	`FieldIconsAlign` Вертикальное выравнивание иконки слева. По умолчанию: `-`
`calendarLabel`	`string` `aria-label` для календаря. По умолчанию: `Календарь`
`calendarPlacement`	`PlacementWithAuto` Расположение календаря относительно поля ввода. По умолчанию: `bottom-start`
`calendarTestsProps`	`CalendarTestsProps` Передает атрибуты `data-testid` для интерактивных элементов в календаре. По умолчанию: `-`
`changeDayLabel`	`string` `aria-label` для поля изменения дня. По умолчанию: `День`
`changeHoursLabel`	`string` Текст выпадающего списка с выбором часов. Делает его доступным для ассистивных технологий. По умолчанию: `Час`
`changeMinutesLabel`	`string` Текст выпадающего списка с выбором минут. Делает его доступным для ассистивных технологий. По умолчанию: `Минута`
`changeMonthLabel`	`string` `aria-label` для селектора месяца. По умолчанию: `Месяц`
`changeYearLabel`	`string` `aria-label` для селектора года. По умолчанию: `Год`
`clearButtonTestId`	`string` Передает атрибут `data-testid` для кнопки очистки даты. По умолчанию: `-`
`clearFieldLabel`	`string` Label для кнопки очистки. Делает доступным для ассистивных технологий. По умолчанию: `Очистить поле`
`closeOnChange`	`boolean` Автоматически закрывать календарь при изменениях. По умолчанию: `true`
`dayFieldTestId`	`string` Передает атрибут `data-testid` для поля ввода дня. По умолчанию: `-`
`defaultValue`	`Date \| null` Начальная дата при монтировании. По умолчанию: `-`
`disableCalendar`	`boolean` Отключение открытия календаря. По умолчанию: `false`
`disableFocusTrap`	`boolean` Позволяет отключить захват фокуса при появлении календаря. По умолчанию: `-`
`disableFuture`	`boolean` Запрещает выбор даты в будущем. Применяется, если не задано `shouldDisableDate`. По умолчанию: `-`
`disablePast`	`boolean` Запрещает выбор даты в прошлом. Применяется, если не заданы `shouldDisableDate` и `disableFuture`. По умолчанию: `-`
`disablePickers`	`boolean` Отключает селекторы выбора месяца/года. По умолчанию: `-`
`DoneButton`	`ComponentType<ButtonProps>` Кастомное отображение кнопки `"Done"`. По умолчанию: `-`
`doneButtonText`	`string` Текст отображаемый в кнопке `"Done"`. По умолчанию: `-`
`enableTime`	`boolean` Включает выбор времени. По умолчанию: `-`
`getRootRef`	`Ref<HTMLDivElement>` По умолчанию: `-`
`hourFieldTestId`	`string` Передает атрибут `data-testid` для поля ввода часа. По умолчанию: `-`
`maxDateTime`	`Date` Максимальные дата и время, которые можно выбрать. Применяется, если не заданы `shouldDisableDate` и `disablePast`/`disableFuture`. По умолчанию: `-`
`minDateTime`	`Date` Минимальные дата и время, которые можно выбрать. Применяется, если не заданы `shouldDisableDate` и `disablePast`/`disableFuture`. По умолчанию: `-`
`minuteFieldTestId`	`string` Передает атрибут `data-testid` для поля ввода минут. По умолчанию: `-`
`mode`	`"default" \| "plain"` Режим отображения. `default` — показывает фон, обводку и, при наличии, текст-подсказку. `plain` — показывает только текст-подсказку. По умолчанию: `-`
`monthFieldTestId`	`string` Передает атрибут `data-testid` для поля ввода месяца. По умолчанию: `-`
`nextMonthIcon`	`ReactNode` Кастомная иконка для кнопки следующего месяца. По умолчанию: `-`
`nextMonthLabel`	`string` `aria-label` для кнопки следующего месяца. По умолчанию: `Следующий месяц`
`onApply`	`((value?: Date) => void) \| undefined` Обработчик нажатия на кнопку `"Done"`. Используется совместно с флагом `enableTime`. По умолчанию: `-`
`onCalendarOpenChanged`	`((opened: boolean) => void)` Обработчик изменения состояния открытия календаря. По умолчанию: `-`
`onChange`	`((value?: Date) => void) \| undefined` Обработчик изменения выбранной даты. По умолчанию: `-`
`onHeaderChange`	`((value: Date) => void)` Обработчик изменения даты в шапке календаря. По умолчанию: `-`
`onNextMonth`	`(() => void)` Нажатие на кнопку переключения на следующий месяц. По умолчанию: `-`
`onPrevMonth`	`(() => void)` Нажатие на кнопку переключения на предыдущий месяц. По умолчанию: `-`
`prevMonthIcon`	`ReactNode` Кастомная иконка для кнопки предыдущего месяца. По умолчанию: `-`
`prevMonthLabel`	`string` `aria-label` для кнопки предыдущего месяца. По умолчанию: `Предыдущий месяц`
`renderCustomValue`	`((date: Date) => ReactNode) \| undefined` Функция для кастомного форматирования отображаемого значения даты. Позволяет переопределить стандартное отображение даты и вернуть собственное представление. По умолчанию: `-`
`renderDayContent`	`((day: Date) => ReactNode)` Кастомизация отображения содержимого дня. По умолчанию: `-`
`restoreFocus`	`boolean \| (() => boolean \| HTMLElement)` По умолчанию: `true`
`shouldDisableDate`	`((value: Date) => boolean)` Функция для проверки запрета выбора даты. По умолчанию: `-`
`showCalendarButtonTestId`	`string` Передает атрибут `data-testid` для кнопки показа календаря. По умолчанию: `-`
`showCalendarLabel`	`string` Label для кнопки открытия календаря. Делает доступным для ассистивных технологий. По умолчанию: `Показать календарь`
`showNeighboringMonth`	`boolean` Показывать дни соседних месяцев. По умолчанию: `-`
`size`	`"s" \| "m"` Размер календаря. По умолчанию: `-`
`status`	`"default" \| "error" \| "valid"` Статус отображения поля в форме. По умолчанию: `-`
`timezone`	`string` Часовой пояс для отображения даты. По умолчанию: `-`
`value`	`Date \| null` Текущая выбранная дата. По умолчанию: `-`
`viewDate`	`Date` Дата отображаемого месяца. При использовании обновление даты должно происходить вне компонента. По умолчанию: `-`
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` День недели, с которого начинается неделя. По умолчанию: `-`
`yearFieldTestId`	`string` Передает атрибут `data-testid` для поля ввода года. По умолчанию: `-`

CalendarRange

DateRangeInput