Поле columns: многоколоночная легенда

Параметр columns в легенде используется для управления многоколоночным отображением элементов легенды в декларативных спецификациях визуализаций, построенных на базе Vega-Lite. Он становится особенно важным при работе с категориальными шкалами, когда количество значений превышает вертикальное или горизонтальное пространство одного столбца.

Легенда в Vega-Lite описывается через объект legend, который может быть задан внутри encoding или в глобальной конфигурации config.legend.

Базовая структура:

{
  "mark": "point",
  "encoding": {
    "color": {
      "field": "category",
      "type": "nominal",
      "legend": {
        "columns": 3
      }
    }
  }
}

Значение columns определяет, на сколько вертикальных колонок будет разбит список категорий в легенде.

Поведение многоколоночной легенды

При задании columns Vega-Lite переключает алгоритм компоновки легенды:

  • категории распределяются по колонкам слева направо и сверху вниз;
  • высота каждой колонки выравнивается автоматически;
  • ширина легенды увеличивается пропорционально количеству колонок;
  • порядок элементов сохраняется в соответствии с исходными данными.

Пример распределения при columns: 2:

A   D
B   E
C   F

При этом важно, что логика не группирует данные семантически — только визуально перераспределяет их.

Типичные сценарии использования columns

1. Большое количество категорий

При 10–30 уникальных значениях одномерная легенда становится перегруженной. columns позволяет:

  • уменьшить высоту визуализации;
  • повысить читаемость;
  • избежать чрезмерного скроллинга (в некоторых контейнерах).
"legend": {
  "columns": 4
}

2. Ограниченное вертикальное пространство

При встраивании графиков в панели управления (dashboards) вертикальный размер часто фиксирован. В этом случае:

  • одна колонка создаёт длинную легенду;
  • несколько колонок оптимизируют плотность размещения.

3. Категориальные палитры высокой мощности

При использовании сложных наборов данных (например, временные срезы, группы пользователей, географические регионы) число категорий быстро растёт. columns стабилизирует визуальную структуру.

Взаимодействие columns с другими параметрами легенды

direction

Параметр direction определяет ориентацию символов и текста:

  • "vertical" — стандартное поведение;
  • "horizontal" — символ и текст располагаются в строку.

При использовании columns:

  • direction: "horizontal" усиливает компактность;
  • direction: "vertical" сохраняет классическую структуру списка.
"legend": {
  "columns": 3,
  "direction": "horizontal"
}

symbolLimit

Если задан symbolLimit, часть категорий может быть скрыта с агрегацией в “others”.

При сочетании:

  • сначала применяется ограничение symbolLimit;
  • затем оставшиеся элементы раскладываются по колонкам.

labelLimit

Ограничение длины текста влияет на читаемость колонок:

  • длинные подписи могут ломать выравнивание;
  • в многоколоночном режиме особенно критично;
  • часто используется совместно с columns.

orient

Расположение легенды (right, left, top, bottom) влияет на доступную ширину:

  • при right или left число колонок обычно ограничивают 1–2;
  • при bottom можно использовать больше колонок.

Алгоритм распределения элементов

Внутренняя логика Vega-Lite при наличии columns:

  1. берётся список категорий;

  2. вычисляется количество строк:

    rows = ceil(total_items / columns)

  3. элементы заполняются по столбцам;

  4. каждая колонка выравнивается по максимальной высоте.

Таким образом, columns не меняет данные, а только задаёт форму отображения.

Пример с цветовой шкалой

{
  "data": {
    "values": [
      {"type": "A", "value": 28},
      {"type": "B", "value": 55},
      {"type": "C", "value": 43},
      {"type": "D", "value": 91},
      {"type": "E", "value": 81},
      {"type": "F", "value": 53}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "type", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"},
    "color": {
      "field": "type",
      "type": "nominal",
      "legend": {
        "columns": 2
      }
    }
  }
}

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

Поведение при динамических данных

При изменении количества категорий columns адаптируется автоматически:

  • добавление новых значений увеличивает количество строк;
  • уменьшение — сокращает визуальную высоту;
  • перерасчёт выполняется на этапе компоновки, а не рендеринга данных.

Это делает параметр устойчивым в интерактивных дашбордах.

Ограничения и особенности

1. Отсутствие интеллектуальной группировки

columns не учитывает смысловые связи между категориями. Даже если данные имеют иерархию, она не сохраняется.

2. Фиксированная структура

После задания числа колонок:

  • Vega-Lite не оптимизирует расположение под “красивую сетку”;
  • возможны визуальные пустоты в последней строке.

3. Ограничения ширины контейнера

При слишком большом columns:

  • легенда выходит за пределы контейнера;
  • происходит обрезка или перенос в зависимости от окружения (например, Vega View или браузерный контейнер).

Практические шаблоны конфигурации

Компактная легенда для панелей

"legend": {
  "columns": 2,
  "symbolLimit": 12
}

Плотная сетка категорий

"legend": {
  "columns": 4,
  "direction": "horizontal",
  "labelLimit": 80
}

Минимальная высота легенды

"legend": {
  "columns": 1
}

Сочетание с глобальной конфигурацией

Через config.legend параметр можно задать глобально:

{
  "config": {
    "legend": {
      "columns": 3
    }
  }
}

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

Роль в архитектуре Vega-Lite

Модель компоновки Vega-Lite разделяет:

  • вычисление данных;
  • декларацию визуальных каналов;
  • layout-слой (включая легенды).

columns относится именно к layout-уровню, не затрагивая семантику данных или шкал. Это делает параметр чисто визуальным, но критически важным для плотных интерфейсов.

Оглавление