Calendar

Компонент Calendar в библиотеке Element Plus предназначен для отображения календаря с возможностью выбора даты или диапазона дат. Он поддерживает кастомизацию внешнего вида, работу с событиями, локализацию и интеграцию с другими элементами интерфейса. Основной принцип работы строится вокруг передачи пропсов, обработки событий и использования слотов для настройки контента.

Импорт и регистрация компонента

Для использования Calendar необходимо импортировать компонент в Vue-проект:

import { ElCalendar } from 'element-plus';
import 'element-plus/dist/index.css';

export default {
  components: {
    ElCalendar
  }
};

Базовое использование

Простейший календарь создается с помощью базового шаблона:

<template>
  <el-calendar v-model="selectedDate"></el-calendar>
</template>

<script>
export default {
  data() {
    return {
      selectedDate: new Date() // текущая дата по умолчанию
    };
  }
};
</script>

Здесь используется директива v-model, которая связывает выбранную дату с переменной selectedDate. Любое изменение даты в календаре автоматически обновляет значение переменной.

Основные пропсы

  • value / v-model – дата, отображаемая и выбранная в календаре. Принимает объект Date.
  • readonly – делает календарь только для чтения.
  • first-day-of-week – устанавливает первый день недели (0 = воскресенье, 1 = понедельник и т.д.).
  • range – позволяет выбрать диапазон дат (если требуется использовать выбор периода).

Пример использования диапазона:

<el-calendar
  v-model="selectedRange"
  :range="true"
></el-calendar>

<script>
export default {
  data() {
    return {
      selectedRange: [new Date('2026-03-01'), new Date('2026-03-07')]
    };
  }
};
</script>

Работа с событиями

Компонент Calendar поддерживает несколько событий:

  • date-change – срабатывает при выборе новой даты.
  • panel-change – срабатывает при переключении месяца или года.

Пример:

<el-calendar
  v-model="selectedDate"
  @date-change="handleDateChange"
></el-calendar>

<script>
export default {
  data() {
    return {
      selectedDate: new Date()
    };
  },
  methods: {
    handleDateChange(date) {
      console.log('Выбрана дата:', date);
    }
  }
};
</script>

Кастомизация внешнего вида через слоты

Calendar предоставляет возможность кастомизации содержимого через слот date-cell. Это позволяет выводить дополнительные данные, например события на конкретные дни:

<el-calendar
  v-model="selectedDate"
>
  <template #date-cell="{ date }">
    <div class="custom-cell">
      <span>{{ date.getDate() }}</span>
      <span v-if="events[date.toDateString()]">●</span>
    </div>
  </template>
</el-calendar>

<script>
export default {
  data() {
    return {
      selectedDate: new Date(),
      events: {
        'Wed Mar 18 2026': true,
        'Thu Mar 19 2026': true
      }
    };
  }
};
</script>

<style>
.custom-cell {
  display: flex;
  flex-direction: column;
  align-items: center;
}
.custom-cell span:last-child {
  color: red;
}
</style>

Локализация

Calendar поддерживает локализацию через глобальные настройки Element Plus:

import { ElCalendar, locale } from 'element-plus';
import ru from 'element-plus/es/locale/lang/ru';

locale.use(ru);

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

Выбор диапазона и ограничение дат

Для выбора диапазона используется массив из двух дат. Ограничение возможных дат осуществляется через пропсы disabled-date и min-date / max-date.

Пример ограничения выбора:

<el-calendar
  v-model="selectedDate"
  :disabled-date="disabledDates"
></el-calendar>

<script>
export default {
  data() {
    return {
      selectedDate: new Date()
    };
  },
  methods: {
    disabledDates(date) {
      const today = new Date();
      return date < today; // запрет выбора прошлых дат
    }
  }
};
</script>

Интеграция с другими компонентами

Calendar часто используется совместно с компонентами Popover, Dialog или формами для выбора даты в интерфейсах:

<el-popover placement="bottom">
  <template #reference>
    <el-input v-model="selectedDateString" placeholder="Выберите дату" readonly />
  </template>
  <el-calendar v-model="selectedDate"></el-calendar>
</el-popover>

<script>
export default {
  data() {
    return {
      selectedDate: new Date(),
      selectedDateString: ''
    };
  },
  watch: {
    selectedDate(val) {
      this.selectedDateString = val.toLocaleDateString();
    }
  }
};
</script>

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

Рекомендации по производительности

  • Избегать глубоких вычислений внутри слота date-cell.
  • Для больших календарей с большим количеством событий использовать оптимизацию через вычисляемые свойства.
  • Минимизировать перерисовку календаря, особенно при обновлении событий.

Итоговая структура данных

Для работы с Calendar рекомендуется использовать объекты Date или массивы Date для диапазонов. Все методы и события работают с этими объектами напрямую, что упрощает интеграцию с внешними сервисами и форматирование дат.

Оглавление