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

# CalendarRange \[tag:component]

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

```jsx
<CalendarRange defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]} />
```

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

> Данный компонент предназначен для использования на планшетах и десктопах.
> При использовании на мобильных устройствах работа компонента не гарантируется.

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

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

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

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

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

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

```jsx
// Неконтролируемое состояние
<CalendarRange defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 10)]} />;

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

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

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

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

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

## Тестирование (e2e) \[#e2e]

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

```jsx
<CalendarRange
  dayTestId={(day) => format(day, 'dd.MM.yyyy')}
  leftPartHeaderTestsData={{
    monthDropdownTestId: 'left-month-dropdown',
  }}
  rightPartHeaderTestsData={{
    monthDropdownTestId: 'right-month-dropdown',
  }}
/>
```

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

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

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

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

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

| Свойство                    | Тип                                 | По умолчанию       | Описание                                                                                                                                                                                                                                                              |
| --------------------------- | ----------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `changeDayLabel`            | `string`                            | `-`                | **Deprecated**: Since 7.4.0. Будет удалено в **VKUI v9**.  Использовалось для задания aria-label для контейнера дней в календаре. Теперь этот контейнер является таблицей (с помощью role="grid") и в aria-label рендерится текущий открытый в календаре месяц и год. |
| `changeMonthLabel`          | `string`                            | `Изменить месяц`   | `aria-label` для селектора месяца.                                                                                                                                                                                                                                    |
| `changeYearLabel`           | `string`                            | `Изменить год`     | `aria-label` для селектора года.                                                                                                                                                                                                                                      |
| `dayTestId`                 | `string \| ((day: Date) => string)` | `-`                | Передает атрибут `data-testid` для дня в календаре.                                                                                                                                                                                                                   |
| `defaultValue`              | `DateRangeType \| null`             | `-`                | Начальный промежуток при монтировании.                                                                                                                                                                                                                                |
| `disableFuture`             | `boolean`                           | `-`                | Запрещает выбор даты в будущем. Применяется, если не задано `shouldDisableDate`.                                                                                                                                                                                      |
| `disablePast`               | `boolean`                           | `-`                | Запрещает выбор даты в прошлом. Применяется, если не заданы `shouldDisableDate` и `disableFuture`.                                                                                                                                                                    |
| `disablePickers`            | `boolean`                           | `-`                | Отключает селекторы выбора месяца/года.                                                                                                                                                                                                                               |
| `getRootRef`                | `Ref<HTMLDivElement>`               | `-`                |                                                                                                                                                                                                                                                                       |
| `leftPartHeaderTestsData`   | `CalendarHeaderTestsProps`          | `-`                | Передает атрибуты `data-testid` для интерактивных элементов в заголовке календаря в левой части.                                                                                                                                                                      |
| `listenDayChangesForUpdate` | `boolean`                           | `-`                | Следить за изменениями дней для обновления UI.                                                                                                                                                                                                                        |
| `nextMonthIcon`             | `ReactNode`                         | `-`                | Кастомная иконка для кнопки следующего месяца.                                                                                                                                                                                                                        |
| `nextMonthLabel`            | `string`                            | `Следующий месяц`  | `aria-label` для кнопки следующего месяца.                                                                                                                                                                                                                            |
| `onChange`                  | `((value: DateRangeType) => void)`  | `-`                | Обработчик изменения выбранного промежутка.                                                                                                                                                                                                                           |
| `onClose`                   | `(() => void)`                      | `-`                | **Deprecated**: Since 7.3.0. Будет удалено в **VKUI v9**.                                                                                                                                                                                                             |
| `prevMonthIcon`             | `ReactNode`                         | `-`                | Кастомная иконка для кнопки предыдущего месяца.                                                                                                                                                                                                                       |
| `prevMonthLabel`            | `string`                            | `Предыдущий месяц` | `aria-label` для кнопки предыдущего месяца.                                                                                                                                                                                                                           |
| `ref`                       | `Ref<HTMLDivElement>`               | `-`                |                                                                                                                                                                                                                                                                       |
| `renderDayContent`          | `((day: Date) => ReactNode)`        | `-`                | Кастомизация отображения содержимого дня.                                                                                                                                                                                                                             |
| `rightPartHeaderTestsData`  | `CalendarHeaderTestsProps`          | `-`                | Передает атрибуты `data-testid` для интерактивных элементов в заголовке календаря в правой части.                                                                                                                                                                     |
| `shouldDisableDate`         | `((value: Date) => boolean)`        | `-`                | Функция для проверки запрета выбора даты.                                                                                                                                                                                                                             |
| `value`                     | `DateRangeType \| null`             | `-`                | Текущий выбранный промежуток.                                                                                                                                                                                                                                         |
| `weekStartsOn`              | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`   | `1`                | День недели, с которого начинается неделя.                                                                                                                                                                                                                            |
