Компонент Calendar: годовое представление

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

Модель данных и структура входных значений

Календарь опирается на простой формат данных, где каждый элемент соответствует одному дню:

const data = [
  { day: '2026-01-01', value: 12 },
  { day: '2026-01-02', value: 8 },
  { day: '2026-01-03', value: 0 }
];

Ключевые требования к данным:

  • day — строка в формате ISO 8601 (YYYY-MM-DD)
  • value — числовое значение, определяющее интенсивность цвета
  • отсутствие значения интерпретируется как ноль или “нет данных” в зависимости от конфигурации

Допускается передача неполных наборов данных: календарь автоматически заполняет пропущенные дни нулевыми значениями при необходимости визуализации полного диапазона.

Определение годового диапазона

Годовое представление задаётся через параметры from и to:

from="2026-01-01"
to="2026-12-31"

Особенности обработки диапазона:

  • данные вне диапазона игнорируются
  • недостающие дни внутри диапазона создаются автоматически
  • отображение всегда выравнивается по неделям (начало недели может быть настроено)

При изменении диапазона происходит полная переразметка сетки, включая перераспределение недель и месяцев.

Базовая конфигурация компонента

Стандартная настройка годового календаря включает минимальный набор параметров:

import { ResponsiveCalendar } from '@nivo/calendar'

<ResponsiveCalendar
  data={data}
  from="2026-01-01"
  to="2026-12-31"
  emptyColor="#eeeeee"
  colors={['#d0e1ff', '#7aa6ff', '#3b6cff', '#1d3cff']}
  margin={{ top: 50, right: 30, bottom: 40, left: 30 }}
/>

Основные параметры:

  • data — массив значений по дням
  • from, to — временной диапазон
  • emptyColor — цвет отсутствующих значений
  • colors — шкала интенсивности
  • margin — отступы контейнера

Принципы построения годовой сетки

Годовая визуализация формируется на основе недельной структуры:

  • каждая колонка соответствует неделе
  • каждая строка — день недели
  • месяцы накладываются как визуальные группы
  • февраль и високосные годы корректно пересчитываются автоматически

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

Цветовые шкалы и интерпретация значений

Цветовая интерполяция в календаре задаётся через массив colors, который определяет дискретные уровни интенсивности.

Принцип работы:

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

Пример расширенной шкалы:

colors={[
  '#edf8fb',
  '#b3cde3',
  '#8c96c6',
  '#8856a7',
  '#810f7c'
]}

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

Настройка дней и отображения ячеек

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

  • размер ячейки зависит от плотности сетки
  • форма по умолчанию — прямоугольник с закруглениями
  • расстояние между ячейками задаётся автоматически

Дополнительно можно управлять:

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

Подсказки (tooltip) и интерактивность

Tooltip формируется на основе значения дня и даты:

tooltip={({ day, value }) => (
  <div>
    <strong>{day}</strong>
    <div>{value}</div>
  </div>
)}

Интерактивные особенности:

  • hover по ячейке
  • выделение активного дня
  • динамическая подстановка значений в tooltip
  • возможность кастомной логики отображения

При больших наборах данных hover-логика оптимизирована через делегирование событий на SVG-слой.

Отображение месяцев и подписей

Годовой календарь автоматически добавляет:

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

Настройки текстовых элементов:

  • monthSpacing — расстояние между месяцами
  • monthBorderColor — цвет разделителя
  • dayBorderWidth — толщина границ дней

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

Настройка дней недели и ориентации

Компонент поддерживает различные варианты ориентации недель:

  • начало недели с понедельника
  • начало недели с воскресенья

Это влияет на распределение строк в сетке и визуальное смещение всей структуры календаря.

Также возможно скрытие подписей дней недели для компактного отображения в дашбордах.

Производительность при больших диапазонах

Годовое представление охватывает до 365–366 ячеек, что само по себе не является тяжёлой нагрузкой, однако оптимизация важна при:

  • множественных календарях на странице
  • динамическом обновлении данных
  • анимациях переходов

Оптимизационные механизмы:

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

Адаптивное поведение и масштабирование

Компонент использует контейнерный подход:

  • ширина и высота вычисляются от родителя
  • сетка пересчитывается при resize
  • пропорции ячеек сохраняются

Важная особенность: при изменении размера не происходит пересоздание данных, только перерасчёт координат.

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

Глобальная стилизация осуществляется через объект theme:

theme={{
  textColor: '#333',
  fontSize: 12,
  tooltip: {
    container: {
      background: '#fff',
      color: '#000'
    }
  }
}}

Поддерживаемые элементы:

  • шрифты подписей месяцев
  • цвет текста
  • оформление tooltip
  • сеточные линии

Обработка отсутствующих значений

Отсутствующие данные могут трактоваться по-разному:

  • как ноль (default behavior)
  • как отдельная категория “no data”
  • как прозрачные ячейки без интерактивности

Визуально такие дни выделяются отдельным цветом emptyColor, что позволяет отделить их от минимальных значений.

Работа с временными зонами

Дата day интерпретируется как локальная или UTC-зависимая строка в зависимости от источника данных. При построении календаря важно учитывать:

  • смещение даты при сериализации
  • возможные расхождения суток при UTC-конвертации
  • нормализацию строкового формата до ISO

Интеграция в дашборды

Годовой календарь часто используется как компонент аналитических панелей:

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

Комбинирование с другими графиками Nivo позволяет связывать календарную динамику с агрегированными метриками по месяцам и неделям.

Поведение при частичном обновлении данных

При изменении входного массива:

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

Это позволяет использовать календарь в потоковых сценариях обновления данных без полной перерисовки.

Оглавление