Формат входных данных для оси времени

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

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

Строковое представление даты

Наиболее распространённый вариант — строки, совместимые с форматом даты JavaScript или стандартизированными представлениями времени.

Поддерживаемые варианты включают:

  • ISO 8601: "2026-05-17", "2026-05-17T14:30:00Z"
  • Упрощённые даты: "2026/05/17", "May 17 2026"

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

Пример структуры данных:

const data = {
  datasets: [{
    label: 'Продажи',
    data: [
      { x: '2026-05-10', y: 120 },
      { x: '2026-05-11', y: 150 },
      { x: '2026-05-12', y: 90 }
    ]
  }]
};

Строка преобразуется в объект даты через встроенный или подключённый адаптер.

Объект Date

Второй по важности формат — нативный объект JavaScript Date. Он обеспечивает максимальную совместимость с внутренними механизмами времени браузера.

data: [
  { x: new Date(2026, 4, 10), y: 120 },
  { x: new Date(2026, 4, 11), y: 150 }
]

Особенность использования Date заключается в том, что месяц передаётся с нуля (январь = 0), что часто становится источником ошибок при ручной генерации данных.

Преимущество данного формата — отсутствие необходимости парсинга строк, что снижает накладные расходы при больших наборах данных.

Unix timestamp

Третий тип — числовые временные метки Unix. Они могут быть представлены в двух вариантах:

  • секунды (10 цифр): 1715932800
  • миллисекунды (13 цифр): 1715932800000

Chart.js по умолчанию ожидает миллисекунды, что критично при работе с API, возвращающими секунды.

Пример:

data: [
  { x: 1715300000000, y: 120 },
  { x: 1715386400000, y: 150 }
]

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

x: timestamp * 1000

Объекты с ключами x и y

Наиболее гибкий и рекомендуемый формат — структура объектов {x, y}. Она позволяет явно связывать временную координату и значение.

data: [
  { x: '2026-05-10T10:00:00Z', y: 120 },
  { x: '2026-05-10T12:00:00Z', y: 135 }
]

Преимущество данного подхода заключается в независимости от порядка массива и возможности объединять разнородные источники данных.

Массивы пар значений

Помимо объектов, поддерживается формат массивов вида [x, y], где первая позиция — время, вторая — значение.

data: [
  ['2026-05-10', 120],
  ['2026-05-11', 150]
]

Этот формат часто используется при трансформации данных из табличных источников или CSV.

Режим категориальной интерпретации времени

При отсутствии временной шкалы Chart.js может интерпретировать данные как категориальные. Однако при включении временной оси поведение полностью меняется: значения x проходят через парсер дат.

Конфигурация оси:

scales: {
  x: {
    type: 'time'
  }
}

Без корректного формата входных данных временная шкала автоматически переключается в некорректный режим отображения или выдаёт пустые графики.

Адаптеры дат и их влияние на входные данные

Временная шкала не содержит собственного полноценного парсера дат и опирается на внешние адаптеры:

  • date-fns
  • moment.js (устаревающий подход)
  • luxon
  • dayjs (через плагины)

Каждый адаптер определяет:

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

Например, с Luxon возможна строгая работа с UTC:

import { DateTime } from 'luxon';

dat a: [
  { x: DateTime.utc(2026, 5, 10).toISO(), y: 120 }
]

Часовые пояса и смещение времени

При работе с временными данными критическим фактором становится зона времени. Основные источники ошибок:

  • локальная интерпретация строки без указания Z
  • смешивание UTC и локального времени
  • использование Date без нормализации

ISO-строки с суффиксом Z фиксируют время в UTC:

'2026-05-10T10:00:00Z'

Без Z интерпретация зависит от локальной системы.

Форматирование и предобработка данных

Перед передачей в Chart.js часто требуется нормализация:

  • преобразование строк API в ISO
  • унификация timestamp (секунды → миллисекунды)
  • сортировка по времени

Пример нормализации:

const normalized = apiData.map(item => ({
  x: new Date(item.date).toISOString(),
  y: item.value
}));

Важно учитывать, что временная шкала предполагает хронологическую упорядоченность, и несортированные данные могут приводить к визуальным артефактам.

Обработка плотных временных рядов

При большом количестве точек входной формат влияет на производительность:

  • строки требуют парсинга
  • Date требует преобразования объектов
  • timestamp обрабатывается быстрее всего

Поэтому при потоковых данных предпочтителен числовой формат:

{ x: 1715386400000, y: 150 }

Множественные наборы данных с общей временной осью

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

datasets: [
  {
    label: 'A',
    data: [
      { x: 1715300000000, y: 10 }
    ]
  },
  {
    label: 'B',
    data: [
      { x: 1715300000000, y: 20 }
    ]
  }
]

Смешивание форматов (строки + числа + Date) приводит к неоднозначной интерпретации и деградации шкалы.

Настройка парсинга входных данных

В конфигурации временной шкалы доступен параметр parsing, который управляет интерпретацией входных значений:

scales: {
  x: {
    type: 'time',
    parsing: {
      xAxisKey: 'x'
    }
  }
}

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

parsing: false

Это критично при работе с уже нормализованными timestamp-значениями.

Оптимальные стратегии выбора формата

Разные сценарии требуют разных входных форматов:

  • API и потоковые данные → Unix timestamp (ms)
  • статические наборы → ISO 8601
  • интеграция с UI формами → Date
  • импорт CSV → массивы [x, y]
  • сложные структуры → объекты {x, y}

Унификация формата внутри проекта снижает количество ошибок и упрощает масштабирование визуализаций.

Оглавление