Адаптер дат: date-fns, Luxon, Moment.js

Визуализация временных рядов в Chart.js опирается на систему адаптеров дат, поскольку сам движок библиотеки не включает полноценный парсер и форматировщик дат. Архитектура временной шкалы (time scale) построена таким образом, что обработка дат делегируется внешним библиотекам, обеспечивающим разбор, форматирование и арифметику времени.

Ключевой слой взаимодействия — адаптер (date adapter), который связывает Chart.js с конкретной библиотекой дат. В экосистеме используются три основных варианта: date-fns, Luxon и Moment.js.

Архитектура адаптеров дат в Chart.js

Временная шкала time в Chart.js не работает напрямую с Date-объектами для всех операций. Вместо этого используется слой абстракции:

  • парсинг входных значений (строки, timestamp, Date)
  • нормализация дат
  • форматирование меток оси
  • вычисление интервалов (минуты, часы, дни, месяцы)
  • локализация

Эти операции вынесены в адаптеры:

  • chartjs-adapter-date-fns
  • chartjs-adapter-luxon
  • chartjs-adapter-moment

Каждый адаптер реализует единый интерфейс, ожидаемый Chart.js, но использует свою внутреннюю модель времени.

Подключение временной шкалы

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

import {
  Chart,
  TimeScale,
  LinearScale,
  LineElement,
  PointElement,
  LineController
} from 'chart.js';

Chart.register(TimeScale, LinearScale, LineElement, PointElement, LineController);

Без регистрации TimeScale адаптеры не будут применяться, и ось времени не активируется.

Адаптер date-fns

Особенности подхода

date-fns строится на принципе функциональной модульности. В отличие от объектных библиотек, каждая операция реализована как отдельная функция. Это влияет на поведение адаптера:

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

Установка и подключение

npm install chartjs-adapter-date-fns date-fns
import 'chartjs-adapter-date-fns';

После подключения адаптер автоматически регистрируется в Chart.js.

Конфигурация шкалы

const config = {
  type: 'line',
  data: {
    datasets: [{
      label: 'Температура',
      data: [
        { x: '2026-01-01', y: 10 },
        { x: '2026-01-02', y: 12 }
      ]
    }]
  },
  options: {
    scales: {
      x: {
        type: 'time',
        time: {
          unit: 'day'
        }
      }
    }
  }
};

Локализация

date-fns использует явный импорт локалей:

import { ru } from 'date-fns/locale';

options: {
  scales: {
    x: {
      adapters: {
        date: {
          locale: ru
        }
      }
    }
  }
}

Поведение парсинга

Поддерживаются:

  • ISO строки (2026-05-17)
  • Unix timestamp
  • объекты Date

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

Адаптер Luxon

Концепция временной модели

Luxon основан на неизменяемых объектах DateTime, что обеспечивает строгую работу с временными зонами и локалями.

Ключевая особенность — встроенная поддержка:

  • time zone
  • internationalization
  • duration arithmetic

Установка

npm install chartjs-adapter-luxon luxon
import 'chartjs-adapter-luxon';

Пример конфигурации

const config = {
  type: 'line',
  data: {
    datasets: [{
      label: 'Посещаемость',
      data: [
        { x: '2026-01-01T10:00:00+06:00', y: 120 },
        { x: '2026-01-01T11:00:00+06:00', y: 150 }
      ]
    }]
  },
  options: {
    scales: {
      x: {
        type: 'time',
        time: {
          tooltipFormat: 'DD T'
        }
      }
    }
  }
};

Работа с часовыми поясами

Luxon позволяет задавать глобальную или локальную зону:

import { Settings } from 'luxon';

Settings.defaultZone = 'Asia/Almaty';

Это влияет на отображение осей и tooltip.

Форматирование дат

В Luxon используется синтаксис токенов:

  • DD — дата
  • T — время
  • LLLL — полная дата

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

Адаптер Moment.js

Историческая модель

Moment.js долгое время был стандартом де-факто для работы с датами в JavaScript. Несмотря на статус legacy-библиотеки, он до сих пор используется в существующих проектах.

Установка

npm install chartjs-adapter-moment moment
import 'chartjs-adapter-moment';

Поведение временной шкалы

Moment.js использует мутабельные объекты moment(), что влияет на:

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

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

const config = {
  type: 'line',
  data: {
    datasets: [{
      label: 'Трафик',
      data: [
        { x: '2026-01-01', y: 200 },
        { x: '2026-01-02', y: 250 }
      ]
    }]
  },
  options: {
    scales: {
      x: {
        type: 'time',
        time: {
          unit: 'day',
          displayFormats: {
            day: 'DD.MM'
          }
        }
      }
    }
  }
};

Ограничения Moment.js

  • отсутствие tree-shaking
  • большой размер библиотеки
  • режим maintenance-only
  • слабая поддержка современных подходов к immutable data

Сравнение адаптеров

Подход к архитектуре

  • date-fns: функциональный, модульный
  • Luxon: объектный, immutable
  • Moment.js: объектный, mutable

Производительность

  • date-fns: минимальный overhead
  • Luxon: средний overhead, оптимизированная работа с зонами
  • Moment.js: наибольшие накладные расходы

Работа с часовыми поясами

  • date-fns: ограниченная нативная поддержка
  • Luxon: полноценная модель time zone
  • Moment.js: поддержка через moment-timezone

Размер бандла

  • date-fns: минимальный при tree-shaking
  • Luxon: средний
  • Moment.js: крупный без возможности оптимизации

Поведение time scale в Chart.js

Time scale в Chart.js включает несколько режимов интервалов:

  • millisecond
  • second
  • minute
  • hour
  • day
  • week
  • month
  • quarter
  • year

Адаптер отвечает за корректное агрегирование точек и генерацию тиков.

Формат входных данных

Поддерживаемые форматы:

  • { x: Date, y: number }
  • { x: timestamp, y: number }
  • { x: ISO string, y: number }

Chart.js передаёт значение в адаптер, который нормализует его в внутреннее представление выбранной библиотеки.

Локали и форматирование осей

Форматирование осей зависит от адаптера:

  • date-fns: через locale-объекты
  • Luxon: через Intl и токены
  • Moment.js: через locale registry

Пример настройки:

options: {
  scales: {
    x: {
      type: 'time',
      ticks: {
        maxRotation: 0,
        autoSkip: true
      }
    }
  }
}

Поведение tooltip с временными данными

Tooltip получает уже отформатированное значение от адаптера. В Luxon и Moment.js форматирование часто выполняется на уровне строки, тогда как date-fns может возвращать результат через отдельные функции форматирования.

Интеграция с большими наборами данных

При работе с тысячами точек:

  • date-fns показывает лучшую масштабируемость
  • Luxon остаётся стабильным при сложной локализации
  • Moment.js может создавать узкие места из-за мутабельности

Особенности миграции между адаптерами

При смене адаптера важно учитывать:

  • различие форматов локалей
  • различие форматирования tooltip
  • различие интерпретации time zone
  • необходимость пересмотра displayFormats

Chart.js не требует изменения dataset, но поведение отображения может измениться.

Внутренний контракт адаптера

Любой адаптер обязан реализовывать набор методов:

  • parse
  • format
  • add
  • diff
  • startOf
  • endOf
  • startOfWeek
  • endOfWeek

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

Оглавление