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

Объект legend в Vega-Lite описывает правила отображения легенды — вспомогательного визуального элемента, который связывает визуальные переменные графика (цвет, форму, размер и др.) с исходными данными. Легенда формируется автоматически на основе шкал (scale), но может быть полностью переопределена через конфигурацию.

В Vega (низкоуровневый слой) легенда является частью спецификации legends, тогда как в Vega-Lite она чаще задаётся внутри encoding или глобального блока config. Несмотря на различия уровней абстракции, структура остаётся концептуально схожей: легенда представляет собой набор свойств, управляющих отображением символов, подписей и заголовков.

Базовая структура объекта legend

В Vega-Lite легенда может быть определена как объект со следующей общей структурой:

{
  "legend": {
    "orient": "right",
    "title": "Категория",
    "type": "symbol",
    "format": "s",
    "direction": "vertical",
    "symbolType": "circle",
    "labelFontSize": 12
  }
}

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

Связь легенды с каналами encoding

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

  • color
  • fill
  • stroke
  • size
  • shape
  • opacity

Пример:

{
  "mark": "point",
  "encoding": {
    "color": {
      "field": "category",
      "type": "nominal",
      "legend": {
        "title": "Тип категории"
      }
    }
  }
}

В этом случае объект legend становится частью описания канала color, а его структура определяет отображение соответствующей шкалы.

Позиционирование легенды

orient

Поле orient задаёт расположение легенды относительно графика:

  • "left"
  • "right"
  • "top"
  • "bottom"
  • "none" — отключение отображения
{
  "legend": {
    "orient": "bottom"
  }
}

direction

Управляет направлением элементов внутри легенды:

  • "vertical"
  • "horizontal"
{
  "legend": {
    "direction": "horizontal"
  }
}

Заголовок легенды

Поле title определяет текст заголовка, который визуально связывает легенду с данными.

{
  "legend": {
    "title": "Продажи по регионам"
  }
}

Дополнительные свойства заголовка:

  • titleFont
  • titleFontSize
  • titleFontWeight
  • titleColor
  • titleLimit — обрезка текста

Пример расширенной настройки:

{
  "legend": {
    "title": "Категория товаров",
    "titleFontSize": 14,
    "titleFontWeight": "bold",
    "titleColor": "#333"
  }
}

Тип легенды (type)

Поле type определяет визуальную природу легенды и зависит от шкалы:

  • "symbol" — для категориальных данных
  • "gradient" — для непрерывных шкал
  • "discrete" — дискретные значения
{
  "legend": {
    "type": "gradient"
  }
}

В Vega-Lite тип часто выводится автоматически, но его можно переопределить для точного контроля.

Форматирование значений шкалы

format

Определяет формат отображения значений:

{
  "legend": {
    "format": ".2f"
  }
}

Применяется для числовых шкал, поддерживает d3-format синтаксис.

formatType

Указывает способ интерпретации формата:

  • "number"
  • "time"
  • "string"
{
  "legend": {
    "formatType": "time",
    "format": "%Y-%m"
  }
}

Символы легенды

symbolType

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

  • "circle"
  • "square"
  • "triangle"
  • "diamond"
  • "stroke" (линия)
{
  "legend": {
    "symbolType": "square"
  }
}

symbolSize

Контролирует размер маркеров:

{
  "legend": {
    "symbolSize": 100
  }
}

symbolStrokeColor / symbolFillColor

Позволяют явно задать стили символов:

{
  "legend": {
    "symbolStrokeColor": "#000",
    "symbolFillColor": "#ffcc00"
  }
}

Настройка меток (label)

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

Основные свойства:

  • labelFont
  • labelFontSize
  • labelColor
  • labelAngle
  • labelAlign
  • labelLimit

Пример:

{
  "legend": {
    "labelFontSize": 11,
    "labelColor": "#666",
    "labelLimit": 120
  }
}

Область значений и фильтрация

values

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

{
  "legend": {
    "values": ["A", "B", "C"]
  }
}

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

  • ограничения категорий
  • ручного порядка отображения
  • фильтрации шкалы легенды

Стилизация контейнера легенды

Легенда также имеет свойства контейнера:

  • padding
  • cornerRadius
  • strokeColor
  • fillColor
  • offset
{
  "legend": {
    "padding": 10,
    "strokeColor": "#ddd",
    "cornerRadius": 4
  }
}

Управление направлением и сеткой

Для сложных легенд применяются параметры разметки:

  • columns — число колонок
  • rowPadding — отступ между строками
  • columnPadding — отступ между колонками
{
  "legend": {
    "columns": 2,
    "rowPadding": 6,
    "columnPadding": 12
  }
}

Взаимодействие с scale

Легенда напрямую связана с объектом scale. Поведение определяется типом шкалы:

  • quantitative scale → градиентная легенда
  • ordinal scale → символическая легенда
  • nominal scale → категориальная легенда

Пример:

{
  "encoding": {
    "color": {
      "field": "value",
      "type": "quantitative",
      "scale": {
        "scheme": "blues"
      },
      "legend": {
        "type": "gradient"
      }
    }
  }
}

Полная структура объекта legend

Обобщённая структура включает группы свойств:

{
  "legend": {
    "orient": "",
    "direction": "",
    "type": "",
    "title": "",
    "format": "",
    "formatType": "",

    "symbolType": "",
    "symbolSize": "",

    "labelFont": "",
    "labelFontSize": "",
    "labelColor": "",

    "titleFont": "",
    "titleFontSize": "",
    "titleColor": "",

    "values": [],

    "columns": "",
    "rowPadding": "",
    "columnPadding": "",

    "padding": "",
    "offset": ""
  }
}

Отличия реализации legend в Vega и Vega-Lite

Vega-Lite

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

Vega

  • легенда задаётся в массиве legends
  • требуется явное связывание со шкалами
  • более гибкая система сигналов (signals)
  • поддержка сложных кастомных рендерингов

Пример Vega:

{
  "legends": [
    {
      "fill": "colorScale",
      "title": "Категории"
    }
  ]
}

Иерархия переопределений

Свойства legend могут задаваться на разных уровнях:

  1. encoding.<channel>.legend — локально
  2. config.legend — глобально
  3. Автоматически из scale

Приоритет:

локальный legend > config.legend > auto-scale

Поведение при отключении legend

Если задано:

{
  "legend": null
}

или

{
  "legend": {
    "orient": "none"
  }
}

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

Оглавление