﻿---
description: Компонент для выбора даты и времени, поддерживает различные режимы работы, настройку ограничений по датам и локализацию.
tags: forms
---

# Calendar \[tag:component]

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

```jsx
<Calendar />
```

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

> Старайтесь использовать на мобильных устройствах уменьшенную версию компонента (свойство `size="s"`).

Это календарь — встраивайте его в нужные части приложения.

Если вам нужно поле ввода даты и времени (со всплывающим календарём), то используйте компонент [`DateInput`](/components/date-input).

Если вам нужен компонент для задания диапазона дат и времени, то используйте [`CalendarRange`](/components/calendar-range).

## Режим работы

Компонент поддерживает работу как в неконтролируемом режиме, так и контролируемом. Это стандартное поведение
React-компонентов, прочитать про это можно в [документации React](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable).

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

```jsx
// Неконтролируемое состояние
<Calendar defaultValue={new Date()} />;

// Контролируемое состояние
const [date, setDate] = React.useState(new Date());

<Calendar value={date} onChange={setDate} />;
```

## Выбор времени

Для включения выбора времени используйте свойство `enableTime`.

> Выбор времени недоступен при `size="s"`.

```jsx
<Calendar defaultValue={new Date()} enableTime />
```

## Часовые пояса

Компонент поддерживает работу с часовыми поясами через свойство `timezone`
(принимает строку в [IANA](https://data.iana.org/time-zones/tzdb-2021a/zone1970.tab)).
При указании часового пояса все даты автоматически конвертируются в указанный часовой пояс.

## Локализация

Компонент поддерживает настройку текстов через `changeDayLabel`, `changeHoursLabel` и остальные `*Label` свойства.

> Название месяцев и дней недели определяется исходя из значения `locale` в `ConfigProvider`.

### Поддержка локалей

Названия месяцев и дней недели формируются с помощью [`Intl.DateTimeFormat`](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
В некоторых окружениях (например, в [Chromium](https://issues.chromium.org/issues/40075497)) для локалей `kk` (казахский) и `ka` (грузинский)
данные отсутствуют, из-за чего даты отображаются на языке по умолчанию.

Чтобы добавить поддержку этих локалей, используйте полифил [`@formatjs/intl-datetimeformat`](https://www.npmjs.com/package/@formatjs/intl-datetimeformat).

Импортируйте полифил и данные нужных локалей до рендеринга приложения:

```js
import "@formatjs/intl-datetimeformat/polyfill.js";
import "@formatjs/intl-datetimeformat/locale-data/kk.js";
import "@formatjs/intl-datetimeformat/locale-data/ka.js";
```

> Подробнее о настройке полифила читайте в [его документации](https://formatjs.github.io/docs/polyfills/intl-datetimeformat/).

## Доступность (a11y) \[#a11y]

Компонент обеспечивает базовую доступность через:

* корректную семантическую разметку;
* поддержку клавиатурной навигации;
* `aria`-атрибуты для всех интерактивных элементов.

При использовании компонента убедитесь, что все текстовые метки
(`changeDayLabel`, `changeHoursLabel` и остальные `*Label` свойства) корректно описывают действия для пользователей скринридеров.

## Свойства и методы \[#api]

| Свойство                    | Тип                                          | По умолчанию       | Описание                                                                                                                                                                                                                                                |
| --------------------------- | -------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `changeDayLabel`            | `string`                                     | `-`                | **Deprecated**: Будет удалено в **VKUI v9**. Использовалось для задания aria-label для контейнера дней в календаре. Теперь этот контейнер является таблицей (с помощью role="grid") и в aria-label рендерится текущий открытый в календаре месяц и год. |
| `changeHoursLabel`          | `string`                                     | `Изменить час`     | Текст выпадающего списка с выбором часов. Делает его доступным для ассистивных технологий.                                                                                                                                                              |
| `changeMinutesLabel`        | `string`                                     | `Изменить минуту`  | Текст выпадающего списка с выбором минут. Делает его доступным для ассистивных технологий.                                                                                                                                                              |
| `changeMonthLabel`          | `string`                                     | `Изменить месяц`   | `aria-label` для селектора месяца.                                                                                                                                                                                                                      |
| `changeYearLabel`           | `string`                                     | `Изменить год`     | `aria-label` для селектора года.                                                                                                                                                                                                                        |
| `dayProps`                  | `CalendarDayElementProps`                    | `-`                | Дополнительные свойства для элементов дней.                                                                                                                                                                                                             |
| `dayTestId`                 | `string \| ((day: Date) => string)`          | `-`                | Передает атрибут `data-testid` для дня в календаре.                                                                                                                                                                                                     |
| `defaultValue`              | `Date \| null`                               | `-`                | Начальная дата при монтировании.                                                                                                                                                                                                                        |
| `disableFuture`             | `boolean`                                    | `-`                | Запрещает выбор даты в будущем. Применяется, если не задано `shouldDisableDate`.                                                                                                                                                                        |
| `disablePast`               | `boolean`                                    | `-`                | Запрещает выбор даты в прошлом. Применяется, если не заданы `shouldDisableDate` и `disableFuture`.                                                                                                                                                      |
| `disablePickers`            | `boolean`                                    | `-`                | Отключает селекторы выбора месяца/года.                                                                                                                                                                                                                 |
| `DoneButton`                | `ComponentType<ButtonProps>`                 | `-`                | Кастомное отображение кнопки `"Done"`.                                                                                                                                                                                                                  |
| `doneButtonDisabled`        | `boolean`                                    | `-`                | Блокировка взаимодействия с кнопкой "Done".                                                                                                                                                                                                             |
| `doneButtonShow`            | `boolean`                                    | `-`                | Управление отображением кнопки `"Done"`.                                                                                                                                                                                                                |
| `doneButtonTestId`          | `string`                                     | `-`                | Передает атрибут `data-testid` для кнопки "Готово" в календаре.                                                                                                                                                                                         |
| `doneButtonText`            | `string`                                     | `-`                | Текст отображаемый в кнопке `"Done"`.                                                                                                                                                                                                                   |
| `enableTime`                | `boolean`                                    | `false`            | Включает выбор времени.                                                                                                                                                                                                                                 |
| `getRootRef`                | `Ref<HTMLDivElement>`                        | `-`                |                                                                                                                                                                                                                                                         |
| `hoursTestId`               | `string`                                     | `-`                | Передает атрибут `data-testid` для дропдауна выбора часа в календаре.                                                                                                                                                                                   |
| `listenDayChangesForUpdate` | `boolean`                                    | `-`                | Следить за изменениями дней для обновления UI.                                                                                                                                                                                                          |
| `maxDateTime`               | `Date`                                       | `-`                | Максимальные дата и время, которые можно выбрать. Применяется, если не заданы `shouldDisableDate` и `disablePast`/`disableFuture`.                                                                                                                      |
| `minDateTime`               | `Date`                                       | `-`                | Минимальные дата и время, которые можно выбрать. Применяется, если не заданы `shouldDisableDate` и `disablePast`/`disableFuture`.                                                                                                                       |
| `minutesTestId`             | `string`                                     | `-`                | Передает атрибут `data-testid` для дропдауна выбора минут в календаре.                                                                                                                                                                                  |
| `monthDropdownTestId`       | `string \| ((monthIndex: number) => string)` | `-`                | Передает атрибут `data-testid` для дропдауна выбора месяца в заголовке календаря.                                                                                                                                                                       |
| `nextMonthButtonTestId`     | `string`                                     | `-`                | Передает атрибут `data-testid` для кнопки перехода к следующему месяцу в заголовке календаря.                                                                                                                                                           |
| `nextMonthIcon`             | `ReactNode`                                  | `-`                | Кастомная иконка для кнопки следующего месяца.                                                                                                                                                                                                          |
| `nextMonthLabel`            | `string`                                     | `Следующий месяц`  | `aria-label` для кнопки следующего месяца.                                                                                                                                                                                                              |
| `nextMonthProps`            | `ArrowMonthProps`                            | `-`                | Дополнительные свойства для кнопки следующего месяца.                                                                                                                                                                                                   |
| `onChange`                  | `((value: Date) => void)`                    | `-`                | Обработчик изменения выбранной даты.                                                                                                                                                                                                                    |
| `onDoneButtonClick`         | `(() => void)`                               | `-`                | Обработки нажатия на кнопку `"Done"`.                                                                                                                                                                                                                   |
| `onHeaderChange`            | `((value: Date) => void)`                    | `-`                | Обработчик изменения даты в шапке календаря.                                                                                                                                                                                                            |
| `onNextMonth`               | `(() => void)`                               | `-`                | Нажатие на кнопку переключения на следующий месяц.                                                                                                                                                                                                      |
| `onPrevMonth`               | `(() => void)`                               | `-`                | Нажатие на кнопку переключения на предыдущий месяц.                                                                                                                                                                                                     |
| `prevMonthButtonTestId`     | `string`                                     | `-`                | Передает атрибут `data-testid` для кнопки перехода к предыдущему месяцу в заголовке календаря.                                                                                                                                                          |
| `prevMonthIcon`             | `ReactNode`                                  | `-`                | Кастомная иконка для кнопки предыдущего месяца.                                                                                                                                                                                                         |
| `prevMonthLabel`            | `string`                                     | `Предыдущий месяц` | `aria-label` для кнопки предыдущего месяца.                                                                                                                                                                                                             |
| `prevMonthProps`            | `ArrowMonthProps`                            | `-`                | Дополнительные свойства для кнопки предыдущего месяца.                                                                                                                                                                                                  |
| `ref`                       | `Ref<HTMLDivElement>`                        | `-`                |                                                                                                                                                                                                                                                         |
| `renderDayContent`          | `((day: Date) => ReactNode)`                 | `-`                | Кастомизация отображения содержимого дня.                                                                                                                                                                                                               |
| `shouldDisableDate`         | `((value: Date) => boolean)`                 | `-`                | Функция для проверки запрета выбора даты.                                                                                                                                                                                                               |
| `showNeighboringMonth`      | `boolean`                                    | `-`                | Показывать дни соседних месяцев.                                                                                                                                                                                                                        |
| `size`                      | `"s" \| "m"`                                 | `m`                | Размер календаря.                                                                                                                                                                                                                                       |
| `timezone`                  | `string`                                     | `-`                | Часовой пояс для отображения даты.                                                                                                                                                                                                                      |
| `value`                     | `Date \| null`                               | `-`                | Текущая выбранная дата.                                                                                                                                                                                                                                 |
| `viewDate`                  | `Date`                                       | `-`                | Дата отображаемого месяца. При использовании обновление даты должно происходить вне компонента.                                                                                                                                                         |
| `weekStartsOn`              | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`            | `1`                | День недели, с которого начинается неделя.                                                                                                                                                                                                              |
| `yearDropdownTestId`        | `string \| ((year: number) => string)`       | `-`                | Передает атрибут `data-testid` для дропдауна выбора года в заголовке календаря.                                                                                                                                                                         |
