Если календарю нужно поле ввода, берите готовый CdsDateInput — он собирает то же самое из поля, меню и этого календаря, добавляя ручной ввод и время. Для выбора одного только времени есть CdsTimePicker.

Анатомия

Календарь состоит из необязательной шапки с итогом выбора, навигации по месяцу и году, сетки дней и зоны действий. Шапку включает header, кнопку «Сегодня» — today-btn, а действия добавляются в слот по умолчанию.

Storybook

Вариации

Значение и формат

Выбранная дата приходит в v-model строкой в формате mask — по умолчанию DD.MM.YYYY. Повторный клик по выбранному дню снимает выбор; no-unset запрещает такой сброс, а hide-sibling-month скрывает дни соседних месяцев.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" />

    <span class="text-200 text-content-secondary">Значение: {{ value ?? '—' }}</span>
  </div>
</template>

Шапка

header включает шапку с итогом выбора: заголовок показывает дату или число выбранных дней, описание — год. Тексты заменяются пропсами title и description либо одноимёнными слотами. today-btn добавляет кнопку возврата к текущему дню.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" header today-btn />
  </div>
</template>

Диапазон дат

range переключает календарь на выбор периода: первый клик фиксирует начало (событие range-start), второй — конец (range-end), значение приходит объектом { from, to }. В паре с multiple можно выбрать несколько периодов.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<{ from: string; to: string } | string | null>(null);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" range header />

    <span class="text-200 text-content-secondary">Значение: {{ value ? JSON.stringify(value) : '—' }}</span>
  </div>
</template>

Несколько дат

multiple разрешает отмечать отдельные даты — модель становится массивом строк.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string[]>([]);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" multiple header />

    <span class="text-200 text-content-secondary">Значение: {{ JSON.stringify(value) }}</span>
  </div>
</template>

События

events отмечает даты точками: принимает массив дат в формате YYYY/MM/DD или функцию-предикат. Цвет точки задаёт events-color — строкой либо функцией от даты, если типов событий несколько.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
const now = new Date();
const ym = `${now.getFullYear()}/${String(now.getMonth() + 1).padStart(2, '0')}`;
const events = [`${ym}/05`, `${ym}/12`, `${ym}/20`];
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :events="events" events-color="success" />
  </div>
</template>

Доступные даты

allowed-dates ограничивает выбор: массив дат либо функция, которая получает дату YYYY/MM/DD и возвращает, можно ли её выбрать. Остальные дни отключаются.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
// Разрешаем выбирать только будни.
const allowedDates = (date: string) => {
  const [y, m, d] = date.split('/').map(Number);
  const day = new Date(y, m - 1, d).getDay();
  return day !== 0 && day !== 6;
};
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :allowed-dates="allowedDates" />
  </div>
</template>

Границы навигации

min-year-month и max-year-month (формат YYYY/MM) не дают уйти за пределы диапазона — стрелки на границе отключаются. За переходами между месяцами следите по событию navigation.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
const year = new Date().getFullYear();
const min = `${year}/01`;
const max = `${year}/12`;
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :min-year-month="min" :max-year-month="max" />
  </div>
</template>

Стартовый вид

view открывает календарь сразу со списка месяцев (Months) или лет (Years) — удобно для дат, далёких от текущей. default-year-month задаёт стартовый месяц, когда модель пуста.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" view="Months" />
  </div>
</template>

Локализация

locale принимает имя локали (ru | en) или собственный объект переводов; без пропа используется локаль приложения. first-day-of-week задаёт первый день недели — для en это обычно воскресенье.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" locale="en" :first-day-of-week="0" header />
  </div>
</template>

Состояния

disabled отключает календарь и приглушает его, readonly сохраняет обычный вид, но блокирует и выбор, и навигацию.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const now = new Date();
const value = ref(`15.${String(now.getMonth() + 1).padStart(2, '0')}.${now.getFullYear()}`);
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <div class="w-fit">
      <CdsDatePicker v-model="value" disabled header />
    </div>

    <div class="w-fit">
      <CdsDatePicker v-model="value" readonly header />
    </div>
  </div>
</template>

Рекомендации

Storybook

Сценарии использования

Поле с датой

Чаще всего календарь живёт не на странице, а в меню у текстового поля. Для этого есть CdsDateInput — он уже собран из поля, меню и календаря, разбирает ручной ввод и принимает все свойства календаря напрямую. Собирайте контрол сами, только если нужна нестандартная схема: из CdsTextInput, CdsMenu с activator="parent" и календаря — так вам остаются доступны все свойства и слоты поля и меню. Маску ввода в этом случае добавьте сами: рекомендуем лёгкую (2,5 КБ) библиотеку Maska.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker, CdsMenu, CdsTextInput } from '@central-design-system/components';
import { vMaska } from 'maska/vue';
import { ref } from 'vue';

const date = ref('22.02.2022');
</script>

<template>
  <div class="w-[250px] m-auto">
    <CdsTextInput
      v-model="date"
      v-maska="'##.##.####'"
      label="Дата"
      placeholder="Выберите дату"
      append-inner-icon="calendar"
    >
      <CdsMenu activator="parent" :close-on-content-click="false">
        <CdsDatePicker v-model="date" />
      </CdsMenu>
    </CdsTextInput>
  </div>
</template>

Отчётный период

Слот по умолчанию добавляет действия под календарём. Здесь выбранный диапазон — черновик: в отчёт он попадает только после кнопки «Применить», а «Сбросить» возвращает календарь к исходному состоянию.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsCard, CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

type TRange = { from: string; to: string };

const draft = ref<TRange | string | null>(null);
const period = ref<string | null>(null);

function apply() {
  if (!draft.value) {
    period.value = null;
  } else if (typeof draft.value === 'string') {
    period.value = draft.value;
  } else {
    period.value = `${draft.value.from} — ${draft.value.to}`;
  }
}

function reset() {
  draft.value = null;
  period.value = null;
}
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="w-fit">
      <CdsDatePicker v-model="draft" range header>
        <div class="flex justify-end gap-2">
          <CdsButton variant="soft" color="neutral" size="sm" text="Сбросить" @click="reset" />
          <CdsButton size="sm" text="Принять" @click="apply" />
        </div>
      </CdsDatePicker>
    </CdsCard>

    <span class="text-200 text-content-secondary">Период отчёта: {{ period ?? 'не выбран' }}</span>
  </div>
</template>

Дата доставки

Ограничения работают вместе: allowed-dates оставляет только будни, а min-year-month и max-year-month не выпускают за пределы ближайших двух месяцев — недоступные варианты даже не приходится объяснять.

Sandbox Storybook

<script setup lang="ts">
import { CdsCard, CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const date = ref<string | null>(null);

const pad = (value: number) => String(value).padStart(2, '0');

// Доставка доступна по будням в ближайшие два месяца.
const now = new Date();
const firstDay = new Date(now.getFullYear(), now.getMonth(), now.getDate());
const lastDay = new Date(now.getFullYear(), now.getMonth() + 2, 0);

const min = `${firstDay.getFullYear()}/${pad(firstDay.getMonth() + 1)}`;
const max = `${lastDay.getFullYear()}/${pad(lastDay.getMonth() + 1)}`;

const allowedDates = (hash: string) => {
  const [year, month, day] = hash.split('/').map(Number);
  const candidate = new Date(year, month - 1, day);
  const weekday = candidate.getDay();

  return weekday !== 0 && weekday !== 6 && candidate >= firstDay && candidate <= lastDay;
};
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="w-fit">
      <CdsDatePicker v-model="date" :allowed-dates="allowedDates" :min-year-month="min" :max-year-month="max" />
    </CdsCard>

    <span class="text-200 text-content-secondary">
      {{ date ? `Привезём ${date} с 10:00 до 18:00` : 'Выберите дату доставки' }}
    </span>
  </div>
</template>

Дата и время

Календарь не выбирает время — поставьте рядом CdsTimePicker с общей моделью и одинаковой маской DD.MM.YYYY HH:mm: каждый компонент меняет свою часть строки. В поле ввода то же самое включается одним пропом — with-time у CdsDateInput.

Sandbox Storybook

<script setup lang="ts">
import { CdsCard, CdsDatePicker, CdsDivider, CdsTimePicker } from '@central-design-system/components';
import { ref } from 'vue';

const now = new Date();
const dateTime = ref(`15.${String(now.getMonth() + 1).padStart(2, '0')}.${now.getFullYear()} 12:35`);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="flex w-fit flex-col">
      <CdsDatePicker v-model="dateTime" mask="DD.MM.YYYY HH:mm" header today-btn />
      <CdsDivider />
      <CdsTimePicker v-model="dateTime" mask="DD.MM.YYYY HH:mm" />
    </CdsCard>

    <span class="text-200 text-content-secondary">Значение: {{ dateTime }}</span>
  </div>
</template>

API

Пропсы

Имя	Тип	По умолчанию	Описание
allowedDates	TCalendarAllowedDates | undefined	—	Массив дат, которые будут отображаться в календаре. При использовании функции, функция получает дату в формате YYYY/MM/DD и должна вернуть true или false.
defaultYearMonth	string | undefined	—	Отображаемый год/месяц в формате YYYY/MM. По-умолчанию это текущий год/месяц если не указана v-model.
description	string | undefined	—	Описание календаря. Отображается в шапке календаря.
disabled	boolean | null | undefined	null	Заблокированное состояние
emitImmediately	boolean | undefined	—	Эмитировать событие update:modelValue при смене месяца и года сразу. Недоступно при multiple и range.
events	TCalendarEvents | undefined	—	Список событий, которые будут отображаться в календаре. Формат: YYYY/MM/DD.
eventsColor	TCalendarEventsColor | undefined	'default'	Цвет событий в календаре.
firstDayOfWeek	string | number | undefined	1	Первый день недели (понедельник по-умолчанию).
header	boolean | undefined	—	Отображать шапку календаря
hideSiblingMonth	boolean | undefined	—	Скрыть дни соседних месяцев в календаре.
locale	string | TDateLocale | undefined	—	Локаль для дат. Имя локали ('ru' | 'en') или объект TDateLocale. По умолчанию берётся текущая локаль из useLocale, иначе ru.
mask	string | undefined	'DD.MM.YYYY'	Формат даты/времени
maxYearMonth	string | undefined	—	Запретить навигацию в календаре после указанной максимальной даты в формате YYYY/MM.
minYearMonth	string | undefined	—	Запретить навигацию в календаре до указанной минимальной даты в формате YYYY/MM.
modelValue	string | TDatetimeValueRange | (string | TDatetimeValueRange)[] | null | undefined	null	Значение модели
multiple	boolean | undefined	—	Разрешает множественный выбор дат. v-model должна быть массивом.
noUnset	boolean | undefined	—	Запретить сброс даты в календаре.
range	boolean | undefined	—	Разрешает выбор диапазона дат. v-model должна быть массивом.
readonly	boolean | null | undefined	null	Только для чтения
theme	string | undefined	—	Тема компонента
title	string | undefined	—	Заголовок календаря. Отображается в шапке календаря.
todayBtn	boolean | undefined	—	Отображать кнопку "Сегодня" в шапке календаря
view	"Calendar" | "Years" | "Months" | undefined	'Calendar'	Вид календаря по-умолчанию. Возможные значения: 'Calendar', 'Years', 'Months'.

События

Имя	Тип	Описание
navigation	[payload: { year: number | undefined; month: number | undefined; }]	Переход к другому месяцу или году (срабатывает и при изменении модели извне).
rangeEnd	[payload: { from: Partial<IRawDate>; to: Partial<IRawDate>; }]	Окончание выбора диапазона дат.
rangeStart	[value: Partial<IRawDate>]	Начало выбора диапазона дат.
update:modelValue	[value: string | TDatetimeValueRange | (string | TDatetimeValueRange)[] | null, reason: string, details: Partial<IRawDate>]	Изменение значения (v-model). Передаёт значение, причину изменения и детали даты.

Слоты

Имя	Тип	Описание
default	any	Дополнительные кнопки под календарём.
description	{ year: string | number | undefined; }	Описание заголовка.
title	{ date: string; }	Заголовок календаря.

Exposed

Имя	Тип	Описание
offsetCalendar	(type: "year" | "month", descending: number) => void	Листает календарь на шаг вперёд или назад по месяцам либо годам.
setCalendarTo	(year: number, month: number) => void	Перематывает календарь на указанные год и месяц, не меняя выбранное значение.
setEditingRange	(from: IRawDate, to: IRawDate) => void	Задаёт подсвечиваемый диапазон дат в режиме range без подтверждения выбора.
setToday	() => void	Выбирает сегодняшнюю дату и перематывает календарь на текущий месяц.
setView	(viewMode: "Calendar" | "Years" | "Months") => void	Переключает режим отображения календаря: дни, месяцы или годы.