Метод gotoMonth

Pikaday представляет собой компактный календарный компонент, ориентированный на работу с чистым JavaScript и минимальной зависимостью от внешних библиотек. Репозиторий проекта доступен на GitHub Pikaday, где также фиксируется поведение методов экземпляра, включая навигацию по месяцам и управление текущим отображением календаря.

Метод gotoMonth относится к группе API, отвечающих за программное управление состоянием отображаемого месяца в календаре. Он изменяет текущий месяц, который отображается в UI, не затрагивая выбранную дату напрямую, если только дополнительная логика приложения не синхронизирует эти состояния.

Метод вызывается на экземпляре календаря:

picker.gotoMonth(monthIndex, [suppressOnChange]);

Параметры

monthIndex (Number) Индекс месяца в диапазоне от 0 до 11, где:

  • 0 — январь
  • 11 — декабрь

Индексирование соответствует стандарту JavaScript Date.

suppressOnChange (Boolean, optional) Флаг подавления вызова события onChangeMonth (или внутренних обновлений UI-обработчиков в зависимости от конфигурации). Используется для программной навигации без побочных эффектов.

Поведение метода в системе Pikaday

При вызове gotoMonth происходит изменение внутреннего состояния объекта календаря:

  • обновляется текущий отображаемый месяц (currentMonth)
  • при необходимости пересчитывается год (currentYear)
  • выполняется перерисовка календарной сетки
  • обновляются элементы навигации (стрелки, заголовок месяца)

При этом выбранная дата (selectedDate) не изменяется, что делает метод строго UI-ориентированным.

Взаимодействие с внутренними полями состояния

Внутренняя модель состояния календаря включает ключевые поля:

  • currentMonth
  • currentYear
  • draw() — метод перерисовки интерфейса

gotoMonth фактически является обёрткой над изменением currentMonth с последующим вызовом рендера:

this.currentMonth = monthIndex;
this.draw();

При выходе за границы года выполняется автоматическая нормализация:

  • переход с декабря (11) на январь следующего года
  • переход с января (0) на декабрь предыдущего года

Пример базового использования

const picker = new Pikaday({
    field: document.getElementById('input'),
    onSelect: function(date) {
        console.log(date);
    }
});

// Перейти к марту текущего года
picker.gotoMonth(2);

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

Переключение с учётом года

Хотя метод напрямую принимает только месяц, изменение года происходит косвенно при выходе за диапазон:

picker.gotoMonth(13);

Результат интерпретируется как:

  • месяц: февраль (1)
  • год: увеличивается на 1

Аналогично:

picker.gotoMonth(-1);

Приводит к:

  • месяц: декабрь (11)
  • год: уменьшается на 1

Такое поведение обеспечивает непрерывную навигацию по календарю.

Синхронизация с выбранной датой

При наличии выбранной даты возможны три сценария:

1. Дата находится в пределах нового месяца

Отображение просто переключается без изменения selection.

2. Дата вне диапазона отображения

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

3. Использование совместно с setDate

Часто применяется связка:

picker.setDate(new Date(2026, 2, 15));
picker.gotoMonth(2);

В этом случае UI и состояние синхронизируются.

suppressOnChange и оптимизация событий

Параметр suppressOnChange используется для предотвращения каскада событий:

picker.gotoMonth(5, true);

В этом случае:

  • не вызываются обработчики изменения месяца
  • не инициируются внешние подписки
  • выполняется только обновление UI

Это критично при массовых обновлениях состояния, например:

  • загрузка сохранённого состояния календаря
  • программная синхронизация нескольких календарей
  • восстановление UI после навигации

Внутренняя логика перерисовки

После изменения месяца вызывается метод draw(), который:

  • формирует сетку дней месяца
  • учитывает firstDay (первый день недели)
  • применяет настройки локализации
  • пересчитывает диапазоны доступных дат (minDate, maxDate)

gotoMonth не выполняет расчётов дат напрямую, а делегирует их системе рендера.

Влияние minDate и maxDate

При наличии ограничений:

minDate: new Date(2026, 0, 1),
maxDate: new Date(2026, 11, 31)

gotoMonth может приводить к частично заблокированному UI:

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

Важно, что сам метод не блокирует переход, а только влияет на отображение.

Использование в пользовательских интерфейсах

Типичные сценарии применения:

Кнопки быстрого перехода

document.getElementById('to-may').addEventListener('click', function () {
    picker.gotoMonth(4);
});

Синхронизация с внешними селекторами

monthSelect.oncha nge = function () {
    picker.gotoMonth(parseInt(this.value, 10));
};

Программная навигация по датасету

function showReportMonth(index) {
    picker.gotoMonth(index, true);
}

Поведение при повторных вызовах

Многократные вызовы gotoMonth подряд:

picker.gotoMonth(1);
picker.gotoMonth(2);
picker.gotoMonth(3);

приводят к последовательной перерисовке, если не используется подавление событий. Это может быть оптимизировано через:

  • batching вызовов
  • использование suppressOnChange
  • временное отключение рендера (если расширяется библиотека)

Отличие от setDate и gotoDate

  • setDate — изменяет выбранную дату
  • gotoDate — переключает отображение к конкретной дате
  • gotoMonth — изменяет только месяц отображения

Таким образом gotoMonth является наиболее «лёгким» методом навигации, не влияющим на выбор.

Особенности поведения при локализации

При использовании локализации (i18n):

  • заголовок месяца обновляется автоматически
  • названия месяцев берутся из конфигурации
  • gotoMonth работает независимо от языка интерфейса

Побочные эффекты и ограничения

Метод имеет предсказуемое поведение, однако:

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

Архитектурно он предназначен исключительно для управления текущим «окном просмотра» календаря.

Оглавление