Поле title и titleAngle

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

title в контексте различных компонентов

В Vega-Lite поле title встречается в нескольких структурах спецификации:

  • оси (axis.title)
  • легенды (legend.title)
  • заголовок всей визуализации (title)
  • фасетные заголовки (header.title)

Несмотря на одинаковое имя, семантика зависит от контекста объекта, в котором оно используется.

Заголовок всей визуализации

На верхнем уровне спецификации title задаёт основной заголовок диаграммы:

{
  "data": {"url": "data.csv"},
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"}
  },
  "title": "Распределение значений по категориям"
}

Этот заголовок является независимым элементом компоновки и не связан с осями или легендами.

axis.title как отдельный тип title

Внутри осей поле title определяет текст подписи оси:

{
  "mark": "line",
  "encoding": {
    "x": {
      "field": "date",
      "type": "temporal",
      "axis": {
        "title": "Дата"
      }
    },
    "y": {
      "field": "price",
      "type": "quantitative",
      "axis": {
        "title": "Цена"
      }
    }
  }
}

В данном случае axis.title выполняет роль семантического описания шкалы. Оно может быть:

  • строкой
  • null (для отключения отображения)
  • объектом с расширенными настройками

titleAngle как параметр ориентации

Поле titleAngle управляет углом поворота текста заголовка. Оно применяется в контексте осей и позволяет контролировать визуальное размещение подписи относительно шкалы.

Базовое поведение

По умолчанию Vega-Lite использует автоматическую ориентацию:

  • горизонтальная ось (x) → заголовок горизонтальный
  • вертикальная ось (y) → заголовок повернут на -90 градусов

titleAngle переопределяет это поведение.

Пример задания угла

{
  "mark": "bar",
  "encoding": {
    "x": {
      "field": "category",
      "type": "nominal",
      "axis": {
        "title": "Категория",
        "titleAngle": 0
      }
    },
    "y": {
      "field": "value",
      "type": "quantitative",
      "axis": {
        "title": "Значение",
        "titleAngle": -45
      }
    }
  }
}

Особенности интерпретации titleAngle

Значение titleAngle задаётся в градусах и интерпретируется по следующим правилам:

  • 0 — горизонтальное расположение текста
  • 90 — вертикальное расположение (снизу вверх)
  • -90 — вертикальное расположение (сверху вниз)
  • произвольные значения — наклон относительно базовой оси

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

Наследование и приоритеты

При наличии нескольких источников конфигурации titleAngle может задаваться на разных уровнях:

  1. глобальная конфигурация (config.axis.titleAngle)
  2. локальная настройка оси (axis.titleAngle)
  3. автоматическая логика Vega-Lite

Приоритет всегда отдается более локальному уровню. Это позволяет гибко управлять визуальным стилем без изменения глобальной конфигурации.

Влияние на компоновку графика

Изменение titleAngle влияет не только на ориентацию текста, но и на геометрию отступов. Vega-Lite автоматически перерасчитывает:

  • padding области графика
  • расстояние между подписью и шкалой
  • ограничивающие рамки (bounding box)

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

Использование в сочетании с titleAlign и titleAnchor

titleAngle часто используется совместно с параметрами выравнивания:

  • titleAlign — горизонтальное выравнивание текста
  • titleBaseline — вертикальное выравнивание
  • titleAnchor — привязка к оси

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

{
  "axis": {
    "title": "Очень длинное название оси",
    "titleAngle": 30,
    "titleAlign": "right",
    "titleAnchor": "end"
  }
}

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

Различия поведения в Vega и Vega-Lite

В Vega-Lite titleAngle является декларативным свойством высокого уровня. В Vega (низкоуровневой спецификации) управление углом текста осуществляется через сигналы (signal) и прямую настройку текста в text или axis.titleAngle внутри axis-компонента.

Пример Vega:

{
  "axes": [
    {
      "orient": "bottom",
      "title": "Категория",
      "titleAngle": 0
    }
  ]
}

В Vega больше контроля над каждым визуальным элементом, но меньше автоматизации, чем в Vega-Lite.

Поведение при длинных заголовках

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

  • наложения текста на соседние элементы
  • выхода за пределы SVG-контейнера
  • ухудшения читаемости шкалы

Типичные стратегии:

  • горизонтальное выравнивание (0) для компактных графиков
  • наклон (-30, -45) при плотных подписях категорий
  • вертикальная ориентация (-90) для стандартных количественных осей

Особенности рендеринга

Рендеринг titleAngle осуществляется на уровне SVG-трансформаций. Текстовый элемент получает трансформацию:

  • rotate(angle)
  • смещение относительно базовой точки привязки

Это означает, что визуальный результат зависит не только от угла, но и от точки anchor, используемой Vega-Lite при расчёте позиции.

Конфигурация по умолчанию

Глобальная конфигурация позволяет задать стандартное поведение:

{
  "config": {
    "axis": {
      "titleAngle": 0
    }
  }
}

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

Оглавление