Поле orient: расположение легенды

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

Поле orient задаётся внутри блока legend и влияет на общий макет визуализации, перераспределяя доступное пространство между графиком и вспомогательными элементами.

Семантика orient

Параметр orient управляет геометрическим размещением легенды. Его значение определяет, с какой стороны от графика будет отображаться легенда, либо будет ли она скрыта.

Поддерживаемые значения:

  • left — легенда размещается слева от области построения
  • right — легенда размещается справа
  • top — легенда располагается над графиком
  • bottom — легенда располагается под графиком
  • none — легенда отключается (не отображается)

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

Логика компоновки

Система компоновки Vega-Lite рассматривает легенду как элемент layout-модели. При задании orient происходит перерасчёт:

  • ширины и высоты viewport
  • доступной области для осей
  • поведения шкал при ограничении пространства

Легенда не является «накладываемым» элементом в классическом смысле, а участвует в раскладке сцены.

Горизонтальное размещение: top и bottom

При значениях:

"orient": "top"

или

"orient": "bottom"

легенда растягивается по горизонтали и занимает полную ширину графика.

Особенности поведения:

  • элементы легенды выстраиваются в строку (в зависимости от direction)
  • график смещается вниз или вверх
  • возможны изменения плотности элементов легенды при нехватке места

Пример:

{
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"},
    "color": {"field": "group", "type": "nominal",
      "legend": {
        "orient": "top"
      }
    }
  }
}

Вертикальное размещение: left и right

Значения:

"orient": "left"
"orient": "right"

переносят легенду в вертикальную колонку.

Поведение:

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

Пример:

{
  "mark": "line",
  "encoding": {
    "x": {"field": "date", "type": "temporal"},
    "y": {"field": "value", "type": "quantitative"},
    "color": {
      "field": "series",
      "type": "nominal",
      "legend": {
        "orient": "right"
      }
    }
  }
}

Отключение легенды через none

Значение:

"orient": "none"

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

Особенности:

  • визуальные каналы продолжают работать (цвета, размеры и т.д.)
  • интерпретация данных становится зависимой от других аннотаций
  • часто применяется при кастомной верстке пояснений вне Vega-Lite

Пример:

{
  "mark": "point",
  "encoding": {
    "x": {"field": "x", "type": "quantitative"},
    "y": {"field": "y", "type": "quantitative"},
    "color": {
      "field": "type",
      "legend": {
        "orient": "none"
      }
    }
  }
}

Влияние на layout и масштабирование

При изменении orient перерасчёт компоновки происходит на уровне layout-движка Vega.

Ключевые эффекты:

1. Изменение доступной области графика

Легенда вычитает пространство из основной области визуализации.

2. Перераспределение осей

Оси могут сдвигаться или масштабироваться, особенно при left и right.

3. Поведение при переполнении

При большом количестве категорий:

  • вертикальные легенды могут обрезаться
  • горизонтальные — переноситься или сжиматься
  • возможна активация scroll-режимов (в зависимости от renderer)

Связь с direction

Поле orient часто используется совместно с:

  • legend.direction

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

  • vertical
  • horizontal

Комбинации:

  • orient: "top" + direction: "horizontal" — классическая строка цветов
  • orient: "right" + direction: "vertical" — стандартный список категорий

Поведение при автоматической раскладке

При отсутствии явного orient Vega-Lite использует эвристику:

  • при большом числе серий — чаще выбирается right
  • при компактных графиках — top или bottom
  • при ограниченной ширине — предпочтение вертикальным легендам

Автоматический выбор может меняться в зависимости от:

  • типа mark (line, bar, area)
  • числа уникальных значений
  • доступного viewport

Практика композиции интерфейса

orient фактически является инструментом управления балансом между:

  • читаемостью легенды
  • плотностью данных
  • использованием пространства

Вертикальные легенды эффективны при:

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

Горизонтальные легенды эффективны при:

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

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

  • orient не влияет на порядок элементов — только на позицию
  • не изменяет визуальный стиль маркеров
  • может конфликтовать с ручными настройками legend.labelLimit
  • поведение зависит от renderer (canvas / SVG)

В системах, основанных на Vega, компоновка легенд является частью общего layout graph pipeline, поэтому изменения orient приводят к пересборке сцены, а не к локальному смещению элемента.

Типовые конфигурационные шаблоны

Вертикальная легенда справа:

"legend": {
  "orient": "right"
}

Горизонтальная легенда снизу:

"legend": {
  "orient": "bottom"
}

Отключение легенды:

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

Взаимодействие с плотностью данных

При росте количества категорий влияние orient усиливается:

  • горизонтальные легенды начинают занимать значительную высоту
  • вертикальные легенды становятся доминирующим элементом по ширине

В таких случаях часто используется комбинация:

  • сокращённых подписей
  • интерактивных подсказок
  • фильтрации данных

Роль в адаптивной визуализации

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

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