Перейти к содержимому
v2.5.0
English
Русский
Документация

DateField

DateField — составной компонент для ввода одной даты, который объединяет ввод с клавиатуры, необязательный выбор в календаре и ограничения на уровне поля в одном элементе управления.
StorybookИсходники

Паттерны

Поле даты с календарём в поповере

Когда использовать:

  • Обычное поле формы должно позволять и вводить, и выбирать дату.
  • Календарь должен появляться по запросу, а не быть видимым постоянно.

Заметки о композиции:

  • Оставьте DateFieldInput основной поверхностью и дайте ему подпись.
  • Смонтируйте DateFieldCalendar внутри PopoverContent и используйте DateFieldTriggerIconButton с aria-label в качестве триггера.

Компромиссы:

  • Экономит место в раскладке.
  • Требует проверки оверлея внутри диалогов, выдвижных панелей и прокручиваемых контейнеров.
en-US
ru-RU
ar-EG
he-IL
typed-date-with-a-calendar-popover.tsx · 75 строк
import {
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,
  CalendarViewButton,
  CalendarViewButtonGroup,

Поле даты в формах с насыщенной валидацией

Когда использовать:

  • Дата должна участвовать в валидации при отправке.
  • Тексты ошибок и подсказок важнее визуального просмотра календаря.

Заметки о композиции:

  • Используйте нативные required и pattern на DateFieldInput для проверки наличия и полноты; min и max уже соблюдаются при вводе.
  • disabledDates соблюдается только в календаре, поэтому повторите это правило в валидации при отправке.
  • Показывайте ошибку через error на корне и HelperText error, связанный через aria-describedby.

Компромиссы:

  • Нативная валидация ограничений без дополнительных библиотек.
  • name на input отправляет введённый текст; чтобы отправить ISO-день, копируйте onChangeValue в скрытый input, как в разделе Форма/интеграция.
required-and-incomplete-dates.tsx · 104 строки
import { FormEvent, useState } from 'react';
import {
  Button,
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,

Поле даты в модальных сценариях

Когда использовать:

  • Сценарии планирования или проверки находятся внутри Dialog, Drawer или Sheet.
  • Календарь по-прежнему должен открываться по запросу.

Заметки о композиции:

  • Проверьте фокус, закрытие и наложение слоёв вместе с родительским оверлеем.
  • Календарь должен быть достаточно компактным для родительского контейнера.

Компромиссы:

  • Сохраняет существующий модальный сценарий.
  • Усложняет координацию оверлеев.
date-field-inside-a-dialog.tsx · 106 строк
import { CSSProperties } from 'react';
import { XIcon } from '@vega-ui/icons';
import {
  Button,
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,

Поле даты в негригорианском календаре

Когда использовать:

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

Заметки о композиции:

  • Создайте календарь один раз с помощью createCalendarSystem вне компонента (см. Даты и календарные системы) и передайте его в проп calendar корня вместе с locale.
  • Ввод проверяется в этом календаре, например 31-й день 6-го персидского месяца или 13-й еврейский месяц; min и max остаются ISO-строками YYYY-MM-DD.

Компромиссы:

  • Нативная длина месяцев и високосные месяцы без изменения хранимого значения.
  • Длина месяцев и эры берутся из данных Intl среды выполнения.
date-field-in-a-non-gregorian-calendar.tsx · 91 строка
import { useState } from 'react';
import { createCalendarSystem } from '@vega-ui/i18n';
import {
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,

Сравнение

Быстрое правило выбора

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

DateField или DateRangeField

Используйте DateField, когда хранится одна дата.

Используйте DateRangeField, когда начальная и конечная даты должны оставаться связанными в одном элементе управления.

Главный компромисс: DateField проще подписать и провалидировать, а DateRangeField уменьшает ошибки согласования двух связанных значений.

DateField или DateTimeField

Используйте DateField, когда время не важно для хранимого значения.

Используйте DateTimeField, когда итоговое значение определяют дата и время вместе.

Главный компромисс: DateField проще вводить и проверять, а DateTimeField фиксирует полную временну́ю метку.

DateField или Calendar

Используйте DateField, когда пользователям нужен ввод с клавиатуры и поле в духе формы.

Используйте Calendar, когда интерфейс в первую очередь про визуальный выбор даты без ввода текста в поле.

Главный компромисс: DateField лучше вписывается в формы, а Calendar сильнее при постоянно видимом выборе даты.

Выбирайте этот компонент, когда

  • Значение — одна дата.
  • Пользователи могут вводить дату напрямую.
  • Элемент управления находится в строке формы или в панели настроек.
  • Календарь — необязательная поддержка, а не вся модель взаимодействия.

Не выбирайте этот компонент, когда

  • Функции нужна пара из начальной и конечной даты.
  • Хранимое значение должно включать время.
  • Интерфейс должен показывать полностью видимый календарь вместо поля ввода.

Решение проблем

Кнопка календаря ничего не открывает

Симптом

Иконка-кнопка триггера рендерится, но по клику календарь не появляется.

Вероятная причина

DateFieldTriggerIconButton отрендерен без окружающего Popover или без DateFieldCalendar внутри оверлея.

Как проверить

  • Проверьте, обёрнут ли триггер в PopoverTrigger.
  • Проверьте, содержит ли PopoverContent компонент DateFieldCalendar.

Исправление

Скомпонуйте триггер и календарь через Popover внутри DateField.

minimal-composition.tsx · 67 строк
import {
  CalendarContent,
  CalendarDay,
  CalendarDays,
  CalendarHeader,
  CalendarMonth,
  CalendarMonthLabel,
  CalendarMonths,
  CalendarNextButton,
  CalendarPrevButton,
  CalendarViewButton,
  CalendarViewButtonGroup,

Введённое значение выглядит неправильно

Симптом

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

Вероятная причина

format или separator не совпадает с форматом даты в подписях, подсказках и сообщениях валидации.

Как проверить

  • Сравните заданный format с видимой подсказкой формы.
  • Введите типичное значение и проверьте, как оно интерпретируется.

Исправление

Согласуйте видимые подсказки, правила разбора и тексты валидации вокруг одного и того же формата.

Отправляемое значение — не ISO-дата

Симптом

Форма отправляет 15.01.2026 вместо 2026-01-15.

Вероятная причина

DateFieldInput — нативный input, и с name отправляется введённый в него текст.

Как проверить

  • Прочитайте поле из FormData в обработчике отправки.

Исправление

Берите ISO-день из onChangeValue на корне, а не текст. Чтобы отправить его с формой, уберите name у input и задайте его скрытому input с этим днём, как в разделе Форма/интеграция.

Отключённые даты всё ещё можно ввести

Симптом

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

Вероятная причина

min и max ограничивают введённые даты, но disabledDates действует только на календарь.

Как проверить

  • Введите отключённый день и отправьте форму.

Исправление

Проверяйте то же правило disabledDates в валидации при отправке и на сервере.