Структура объекта legend

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

Структурно конфигурация выглядит как вложенный объект:

options → plugins → legend

На уровне архитектуры legend делится на несколько крупных блоков: базовые параметры отображения, блок labels, блок title, а также обработчики событий и функции генерации.

Ключевые свойства верхнего уровня отвечают за поведение всей легенды как UI-компонента.

display Определяет, будет ли легенда отображаться вообще. Тип: boolean Значение по умолчанию: true При установке false легенда полностью исключается из рендера, включая DOM-слой canvas-интерфейса.

position Определяет расположение легенды относительно графика. Возможные значения:

  • top
  • bottom
  • left
  • right

Выбор позиции влияет не только на визуальное расположение, но и на перерасчёт доступного пространства области графика.

align Управляет выравниванием легенды вдоль выбранной стороны.

  • start
  • center
  • end

При горизонтальных позициях (top, bottom) влияет на горизонтальное распределение, при вертикальных (left, right) — на вертикальное.

fullSize Логический параметр, определяющий, занимает ли легенда всю доступную ширину/высоту контейнера.

  • true — легенда растягивается на всю линию
  • false — занимает только необходимое пространство

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

rtl Определяет направление текста и элементов в режиме right-to-left. Используется в локализациях с арабским или ивритским письмом.

Блок labels: структура элементов легенды

Наиболее сложная часть конфигурации legend — это объект labels, отвечающий за генерацию и стилизацию каждого элемента легенды.

options: {
  plugins: {
    legend: {
      labels: {
        // параметры
      }
    }
  }
}

boxWidth и boxHeight

boxWidth Ширина цветового маркера рядом с текстом. Тип: number По умолчанию: 40

boxHeight Высота маркера. Если не задан, рассчитывается автоматически на основе шрифта.

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

padding

Отступ между элементами легенды. Тип: number По умолчанию: 10

Управляет внутренними промежутками между строками легенды и влияет на читаемость при большом количестве datasets.

color

Задает цвет текста легенды. Может быть строкой ("#000") или функцией, возвращающей значение на основе контекста.

font

Объект, описывающий шрифт текста легенды:

font: {
  size: 12,
  family: "'Helvetica', 'Arial'",
  style: "normal",
  weight: "normal",
  lineHeight: 1.2
}

Шрифт наследуется от глобальных настроек, но может быть переопределён локально.

usePointStyle

Определяет, будет ли использоваться стиль точки вместо прямоугольного цветового блока.

  • true — круги, точки, кастомные формы
  • false — стандартные прямоугольники

Этот параметр особенно важен для линейных и точечных графиков.

pointStyle

Определяет форму маркера:

  • circle
  • rect
  • triangle
  • cross
  • star
  • rectRounded
  • rectRot

Также может принимать изображение или canvas pattern, что позволяет создавать сложные кастомные легенды.

textAlign

Выравнивание текста внутри элемента легенды:

  • left
  • center
  • right

Используется редко, но важно при кастомных layout-решениях.

generateLabels: механизм построения легенды

Функция generateLabels является ядром логики legend. Она формирует массив объектов, каждый из которых описывает отдельный элемент легенды.

Сигнатура:

generateLabels(chart)

Возвращаемое значение: массив объектов вида:

{
  text: string,
  fillStyle: string,
  strokeStyle: string,
  hidden: boolean,
  datasetIndex: number
}

Каждый объект соответствует одному dataset или элементу внутри dataset.

Структура label-item

Основные поля:

text Отображаемый текст легенды (обычно label dataset).

fillStyle Цвет заливки маркера.

strokeStyle Цвет обводки маркера.

hidden Флаг видимости dataset.

datasetIndex Индекс набора данных, к которому относится элемент.

Поведение generateLabels

При отсутствии пользовательской реализации Chart.js автоматически генерирует labels на основе:

  • dataset.label
  • типа графика
  • текущего состояния скрытия dataset

Переопределение generateLabels позволяет:

  • группировать datasets
  • фильтровать элементы
  • изменять порядок отображения
  • создавать мультиуровневые легенды

filter и sort: управление составом легенды

filter Функция фильтрации элементов легенды.

filter: (legendItem, chartData) => {}

Позволяет исключать элементы без удаления dataset.

Применяется для:

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

sort Функция сортировки элементов легенды.

sort: (a, b) => {}

Позволяет полностью контролировать порядок отображения.

Часто используется для:

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

title: заголовок легенды

Объект title добавляет текстовый заголовок над легендой.

Структура:

title: {
  display: true,
  text: "Заголовок",
  color: "#666",
  font: {
    size: 14,
    weight: "bold"
  },
  padding: 6
}

display — включает или отключает заголовок text — строка или массив строк padding — отступ между заголовком и элементами legend

onClick: взаимодействие с легендой

Функция onClick определяет поведение при нажатии на элемент легенды.

onClick: function(e, legendItem, legend) {}

По умолчанию реализует переключение видимости dataset:

  • скрывает dataset при повторном клике
  • показывает dataset при повторном включении

Переопределение позволяет:

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

onHover и onLeave

Дополнительные события взаимодействия:

onHover Вызывается при наведении на элемент легенды.

onLeave Вызывается при уходе курсора.

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

  • подсветки связанных элементов графика
  • динамического изменения tooltip
  • синхронизации с UI-компонентами

Поведение скрытия dataset

Legend тесно связана с системой visibility datasets.

Каждый элемент легенды хранит состояние:

  • hidden: true/false

При клике происходит переключение:

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

Это поведение можно отключить или изменить через onClick.

Кастомизация через внешнюю легенду

В сложных интерфейсах legend может быть полностью вынесена за пределы canvas.

Подход включает:

  • отключение встроенной legend (display: false)
  • использование generateLabels для получения данных
  • рендер HTML-элементов вручную

Это позволяет:

  • создавать интерактивные панели управления
  • добавлять чекбоксы, переключатели, фильтры
  • интегрировать legend в UI-фреймворки

Взаимодействие legend с типами графиков

Разные типы графиков по-разному используют legend:

  • линейные графики — по dataset
  • pie/doughnut — по сегментам
  • radar — по осям категорий

Функция generateLabels адаптируется под тип визуализации, формируя соответствующую структуру элементов.

Переопределение поведения legend на уровне dataset

Некоторые свойства dataset влияют на legend напрямую:

  • label — текст
  • hidden — начальная видимость
  • pointStyle — форма маркера

Таким образом, legend является отражением структуры данных, а не независимым слоем интерфейса.

Оглавление