Система пропсов: обязательные и опциональные

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

Обязательные пропсы — это минимальный набор входных данных, без которых компонент визуализации не может быть построен. Их отсутствие приводит либо к ошибке рендера, либо к пустому состоянию графика.

data

Главный обязательный пропс практически для всех визуализаций Nivo — data.

Он определяет источник данных и его структуру. В зависимости от типа графика формат различается:

  • для линейных графиков — массив точек с временными или числовыми значениями;
  • для столбчатых диаграмм — массив объектов с ключами категорий и значениями;
  • для круговых диаграмм — массив сегментов с полями id, value, label.

Пример концептуальной структуры:

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

Ключевой момент: Nivo не нормализует данные автоматически. Структура должна соответствовать ожидаемой схеме конкретного компонента.

keys

В многосерийных визуализациях (stacked bar chart, grouped bar chart, heatmap) обязательным становится пропс keys.

Он определяет, какие поля объекта данных будут использоваться как серии.

keys: ['sales', 'revenue', 'profit']

Если keys не совпадает с фактической структурой data, визуализация будет частично или полностью некорректной.

Важно: keys выступает как декларативный контракт между данными и визуальным представлением.

indexBy

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

indexBy: 'country'

Этот пропс определяет, как группируются данные по оси X или по категориальному признаку.

Без indexBy библиотека не сможет корректно построить шкалу категорий.

width и height (или Responsive контейнер)

Для базовых компонентов обязательными являются width и height, если не используется responsive-обёртка:

width: 600,
height: 400

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

Суть: Nivo не работает с “автоматическим размером” без контекста — всегда требуется явная или контейнерная геометрия.

Опциональные пропсы

Опциональные пропсы формируют основную силу Nivo: именно они отвечают за кастомизацию, стилизацию и поведение графиков. Их отсутствие не ломает рендеринг, но влияет на внешний вид и функциональность.

margin

margin: { top: 40, right: 40, bottom: 50, left: 60 }

Определяет внутренние отступы графика.

Если не задан, используется стандартный preset компонента.

Особенность: margin влияет не только на внешний вид, но и на область отрисовки осей и подписей.

colors

Пропс colors управляет цветовой схемой:

colors: { scheme: 'nivo' }

или

colors: ['#ff0000', '#00ff00', '#0000ff']

Он может принимать:

  • массив цветов
  • встроенную палитру
  • функцию генерации цвета

Важно: Nivo применяет цвета на уровне серии, а не отдельных точек (за исключением scatter/heatmap).

theme

Пропс theme позволяет полностью переопределить визуальный стиль:

theme: {
  axis: {
    ticks: {
      text: {
        fill: '#999'
      }
    }
  },
  grid: {
    line: {
      stroke: '#eee'
    }
  }
}

Он влияет на:

  • шрифты
  • цвета осей
  • сетку
  • легенды
  • tooltip

Ключевая особенность: theme наследуется глубоко, но не полностью заменяет дефолт — происходит merge объектов.

axis

Пропсы осей являются опциональными, но критически важными для читаемости:

axisBottom: {
  tickSize: 5,
  tickPadding: 5,
  tickRotation: 0,
  legend: 'Дата',
  legendOffset: 36
}

Доступны отдельные конфигурации:

  • axisTop
  • axisBottom
  • axisLeft
  • axisRight

Если пропс не задан, ось может отображаться в упрощённом виде или скрываться полностью.

legends

Легенды управляются через массив конфигураций:

legends: [
  {
    anchor: 'bottom-right',
    direction: 'column',
    itemsSpacing: 2,
    itemWidth: 100,
    itemHeight: 20
  }
]

Легенды полностью опциональны, но часто используются для многосерийных данных.

tooltip

Tooltip в Nivo может быть:

  • отключён
  • заменён на кастомный React-компонент
  • стилизован через пропсы
tooltip: ({ id, value, color }) => (
  <div style={{ color }}>
    {id}: {value}
  </div>
)

Особенность: tooltip не является частью DOM графика, он рендерится в отдельном overlay-слое.

animate и motionConfig

Анимации управляются двумя связанными пропсами:

animate: true,
motionConfig: 'gentle'

или кастомной конфигурацией:

motionConfig: {
  mass: 1,
  tension: 170,
  friction: 26
}

Если animate отключён, все motion-эффекты игнорируются.

Пропсы поведения данных

enableSlices

Используется в линейных графиках для группировки данных:

enableSlices: 'x'

Включает логическое разбиение области графика для tooltip и взаимодействия.

enableStacking

В bar chart:

enableStacking: true

Определяет, будут ли серии складываться друг на друга.

Важно: влияет на трансформацию данных перед отрисовкой.

curve

Для line charts:

curve: 'monotoneX'

Определяет алгоритм интерполяции линий:

  • linear
  • monotoneX
  • basis
  • step

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

Пропсы интерактивности

onClick

onClick: (node) => {
  console.log(node)
}

Обрабатывает клики по элементам графика.

Передаваемый объект зависит от типа визуализации и содержит метаданные узла.

onMouseEnter / onMouseLeave

Позволяют реализовать кастомные hover-эффекты:

onMouseEnter: (node) => {
  // выделение
}

isInteractive

isInteractive: true

Если отключить, график становится полностью статическим: без tooltip, без событий, без hover-эффектов.

Пропсы форматирования значений

formatValue

Nivo позволяет форматировать отображаемые значения:

valueFormat: value => `${value}%`

Или с использованием библиотек форматирования чисел:

valueFormat: new Intl.NumberFormat('ru-RU').format

Особенность: форматирование применяется только к отображению, но не к исходным данным.

Пропсы ключевой структуры компонентов

role-based props

Некоторые компоненты Nivo используют внутреннюю модель ролей:

  • axis role
  • bar role
  • line role
  • point role

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

Пропсы в этом контексте становятся декларацией поведения, а не просто параметрами.

layers

В продвинутых визуализациях используется система слоёв:

layers: [
  'grid',
  'axes',
  'bars',
  'markers',
  'legends'
]

Каждый слой можно заменить кастомным React-компонентом.

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

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

Система пропсов в Nivo построена по принципу декларативной зависимости:

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

Изменение обязательных пропсов приводит к перестроению модели данных и пересчёту визуальных элементов. Опциональные пропсы чаще влияют только на этап рендеринга.

Пример различия:

  • изменение data → полная переработка сцены
  • изменение colors → только перекраска элементов
  • изменение theme → переопределение стилей без изменения структуры

Типизация и контракт пропсов

В TypeScript-окружении Nivo строго типизирует пропсы через generics:

<BarDatum, ExtraProps>

Это обеспечивает:

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

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

Дефолтные значения и их роль

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

Однако дефолты не являются “нулевыми настройками”, они представляют собой заранее оптимизированный визуальный профиль:

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

Это означает, что отсутствие пропса — это не отсутствие поведения, а выбор встроенного сценария рендеринга.

Конфликт пропсов и приоритеты

При пересечении нескольких уровней конфигурации применяется следующая иерархия:

  1. локальные пропсы компонента
  2. theme overrides
  3. внутренние дефолты библиотеки

Например, цвет текста может быть переопределён:

  • через theme
  • через прямой пропс оси
  • через кастомный слой

Приоритет всегда отдаётся более конкретной декларации.

Оглавление