Типы данных и форматы входных данных

Nivo построена вокруг строгой модели входных данных, где каждый тип визуализации требует предсказуемой структуры JavaScript-объектов. Архитектура библиотеки ориентирована на декларативное описание графиков, поэтому данные не «рисуются», а интерпретируются через заранее определённые схемы. Это накладывает требования к форме массивов, ключам объектов и типам значений.

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

Типичный формат:

const data = [
  { id: 'A', value: 12 },
  { id: 'B', value: 19 },
  { id: 'C', value: 7 }
]

Ключевые характеристики:

  • id — идентификатор элемента
  • value — числовое значение, используемое для вычислений
  • дополнительные поля — произвольные метаданные

Такая структура характерна для простых графиков: pie, bar, radar.

Серийные данные и многомерные структуры

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

const data = [
  {
    id: 'series-1',
    data: [
      { x: '2024-01', y: 10 },
      { x: '2024-02', y: 15 }
    ]
  }
]

Особенности:

  • внешний уровень — серии
  • внутренний уровень — точки (x/y пары)
  • допускается любое значение x: число, строка, дата
  • y всегда числовой

Такая структура активно используется в line charts и area charts.

Временные ряды и форматирование дат

Для временных данных используется расширенная модель, где x интерпретируется как дата или временная метка.

const data = [
  {
    id: 'temperature',
    data: [
      { x: new Date('2024-01-01'), y: 5 },
      { x: new Date('2024-01-02'), y: 7 }
    ]
  }
]

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

  • поддерживаются объекты Date
  • допускаются ISO-строки
  • возможна работа с Unix timestamp
  • библиотека применяет временные шкалы при рендеринге осей

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

Категориальные данные

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

const data = [
  { country: 'Kazakhstan', apples: 40, bananas: 30 },
  { country: 'Russia', apples: 55, bananas: 20 }
]

Здесь:

  • каждая строка — категория
  • ключи (apples, bananas) становятся сериями
  • поле категории задаётся через indexBy

Такая модель требует явного указания ключей при конфигурации компонента.

Плоские и развернутые структуры

Nivo поддерживает два подхода:

Плоская структура

Используется в pie, radial, bullet charts.

const data = [
  { id: 'Chrome', value: 60 },
  { id: 'Firefox', value: 25 }
]

Развернутая структура

Используется в grouped bar charts.

const data = [
  { group: 'A', type: 'x', value: 10 },
  { group: 'A', type: 'y', value: 20 }
]

Иерархические данные

Tree, treemap и sunburst визуализации используют рекурсивную структуру.

const data = {
  name: 'root',
  children: [
    {
      name: 'branch-1',
      children: [
        { name: 'leaf-1', value: 10 }
      ]
    }
  ]
}

Характеристики:

  • корневой объект
  • поле children задаёт вложенность
  • листья содержат value
  • промежуточные узлы могут не иметь значения

Такая модель требует строгой консистентности структуры.

Матрицы и сеточные данные

Heatmap и calendar charts используют двумерную модель.

const data = [
  { x: 0, y: 0, value: 5 },
  { x: 0, y: 1, value: 10 },
  { x: 1, y: 0, value: 3 }
]

Особенности:

  • x и y формируют координатную сетку
  • value определяет интенсивность
  • отсутствующие значения трактуются как пустые ячейки

Географические данные

Для геовизуализаций применяется GeoJSON-совместимая структура.

const data = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      properties: { name: 'Region A' },
      geometry: {
        type: 'Polygon',
        coordinates: [...]
      }
    }
  ]
}

Используются:

  • FeatureCollection
  • Feature
  • геометрии: Point, LineString, Polygon

Типизация значений

Внутри моделей данных выделяются следующие типы:

  • числовые (value, y, size)
  • строковые (id, категории)
  • временные (Date, ISO)
  • булевые (флаги визуальных состояний)
  • вложенные структуры (children, data)

Особое значение имеет стабильность типов: одна и та же серия должна сохранять формат на протяжении всего жизненного цикла компонента.

Привязка данных к визуальным шкалам

Данные в Nivo не используются напрямую, а проходят через слой доступа (accessors):

  • xScale и yScale
  • indexBy
  • keys
  • valueFormat

Пример:

<Bar
  data={data}
  indexBy="country"
  keys={['apples', 'bananas']}
/>

Здесь ключи не выводятся автоматически — они задаются явно, что делает модель детерминированной.

Нормализация и предобработка данных

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

  • сортировка по x
  • группировка по id
  • заполнение пропусков
  • агрегация значений

Пример агрегации:

const grouped = data.reduce((acc, item) => {
  acc[item.category] = (acc[item.category] || 0) + item.value
  return acc
}, {})

Взаимодействие с TypeScript-моделями

В экосистеме React и Nivo часто используются строгие типы:

type Point = {
  x: number | string | Date
  y: number
}

Типизация обеспечивает:

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

Обобщённые паттерны входных данных

Несмотря на разнообразие графиков, можно выделить общие шаблоны:

  • Series-based: массив серий с вложенными точками
  • Key-value: объект с полями-метриками
  • Hierarchy-based: дерево с children
  • Grid-based: координатная матрица
  • Geo-based: FeatureCollection

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

Оглавление