В библиотеке Nivo аннотации представляют собой слой визуальных подсказок, накладываемых поверх графика для выделения отдельных значений, диапазонов или областей данных. Они не участвуют в расчётах и не изменяют набор данных, но значительно расширяют выразительность визуализации, позволяя акцентировать внимание на ключевых точках и закономерностях.
В системе аннотаций используются три базовых геометрических типа: точечные, прямоугольные и круговые. Каждый тип ориентирован на свой сценарий выделения данных и имеет собственный набор параметров, влияющих на позиционирование, внешний вид и поведение.
Точечная аннотация применяется для выделения конкретной точки данных на графике. Она используется, когда необходимо акцентировать внимание на отдельном значении, например пике, аномалии или контрольной точке.
Основой точечной аннотации является сопоставление с конкретным
элементом данных через match. Обычно match
задаётся как фильтр по серии и значению осей.
Типичная структура включает следующие элементы:
Пример конфигурации:
const annotations = [
{
type: 'dot',
match: {
serieId: 'temperature',
x: '2024-01-10',
y: 18
},
note: 'Локальный максимум',
noteX: 10,
noteY: -20,
offset: 5,
size: 12,
borderWidth: 2,
borderColor: '#ff0000'
}
]Точечная аннотация часто используется в линейных графиках и scatter-плотах. Важной особенностью является то, что позиция аннотации строго привязана к координате данных, поэтому любое изменение масштаба осей автоматически обновляет её положение.
Внутренне dot-аннотация рассчитывает экранные координаты через систему координат графика, после чего поверх точки накладывается SVG-элемент. Это делает её чувствительной к изменению масштаба, но стабильной при ресайзе контейнера.
Прямоугольная аннотация используется для выделения диапазона значений. Она применяется, когда необходимо обозначить область интереса: временной интервал, диапазон значений по оси Y или зону допустимых отклонений.
Ключевой особенностью rect-аннотации является работа не с одной точкой, а с двумя границами, которые определяют область.
Структура обычно включает:
Пример:
const annotations = [
{
type: 'rect',
xMin: '2024-01-05',
xMax: '2024-01-15',
yMin: 10,
yMax: 25,
note: 'Период аномальной активности',
fill: 'rgba(255, 0, 0, 0.1)',
borderWidth: 1,
borderColor: '#ff0000'
}
]Rect-аннотации особенно полезны в временных рядах, где требуется выделить фазы поведения системы. В отличие от точечной аннотации, они формируют визуальный фон, а не локальный маркер.
При рендеринге вычисляется прямоугольник в экранных координатах, который затем накладывается поверх графика. Если диапазон выходит за пределы видимой области, аннотация автоматически обрезается по границам viewport.
Дополнительная особенность заключается в возможности перекрытия нескольких rect-аннотаций, что позволяет формировать сложные визуальные сегментации данных.
Круговая аннотация используется для выделения области вокруг точки с заданным радиусом. Она представляет собой компромисс между точечным и зональным выделением: фиксирует центр, но расширяет область влияния.
Основные параметры circle-аннотации:
Пример конфигурации:
const annotations = [
{
type: 'circle',
match: {
serieId: 'pressure',
x: '2024-02-01',
y: 101.3
},
radius: 20,
note: 'Нестабильное измерение',
strokeWidth: 2,
strokeColor: '#ffa500',
fill: 'rgba(255, 165, 0, 0.15)'
}
]Circle-аннотации часто применяются для обозначения зон неопределённости, погрешностей измерений или кластеров значений вокруг ключевой точки. В отличие от dot, который фиксирует строгое значение, circle задаёт область влияния.
При отрисовке радиус пересчитывается в экранные единицы, что обеспечивает корректное отображение при изменении масштаба. Если используется динамическое масштабирование, круг сохраняет визуальную пропорцию относительно осей.
Dot, rect и circle различаются не только геометрией, но и семантикой использования.
Dot фиксирует конкретное событие в данных. Его задача — указать на точку.
Rect фиксирует интервал и работает как инструмент сегментации. Его задача — обозначить область.
Circle вводит понятие радиуса влияния, формируя мягкую границу вокруг точки.
Эти различия влияют на выбор типа аннотации в зависимости от характера данных. В дискретных наборах предпочтение часто отдаётся dot. В временных рядах с фазами поведения — rect. В измерениях с погрешностями и шумом — circle.
Во всех трёх типах аннотаций центральную роль играет механизм сопоставления данных. Он определяет, к какой именно точке или области будет применена аннотация.
Сопоставление может быть строгим, когда указываются конкретные значения осей, или более гибким, когда используются частичные условия, например только серия или диапазон X.
При построении графика Nivo проходит по отрендеренным элементам и сравнивает их с условиями match, после чего добавляет соответствующий слой аннотаций поверх уже рассчитанной сцены.
Аннотации всегда отрисовываются поверх базовых графических элементов. Это достигается за счёт отдельного SVG-слоя, который размещается после отрисовки линий, баров или точек данных.
Порядок наложения имеет значение: сначала рендерится основная визуализация, затем добавляются dot, rect и circle-аннотации. При перекрытии нескольких аннотаций приоритет определяется порядком их объявления в конфигурации.
Каждый тип аннотаций поддерживает независимую стилизацию. Цвета, прозрачность, толщины линий и радиусы могут адаптироваться под общую тему графика.
Часто используется полупрозрачная заливка для rect и circle, чтобы не перекрывать основные данные, а лишь подчеркивать их структуру. Dot-аннотации, напротив, часто выделяются контрастным цветом, так как они обозначают конкретные значения.
Все типы аннотаций зависят от текущего масштаба осей. При изменении zoom или ресайзе контейнера происходит пересчёт координат.
Dot сохраняет привязку к конкретной точке.
Rect пересчитывает границы диапазона.
Circle сохраняет центр и радиус в относительных координатах, преобразуя их в пиксели.
Такая модель обеспечивает стабильность визуального слоя независимо от динамики отображения данных.