Поле title в Vega

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

Структура поля title

В Vega поле title может быть задано как строка или как объект конфигурации. Простая форма применяется для быстрого задания текста:

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

Объектная форма используется при необходимости тонкой настройки визуального оформления:

"title": {
  "text": "Продажи по регионам",
  "anchor": "start",
  "orient": "top",
  "offset": 10
}

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

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

text

Поле text задаёт строку заголовка или массив строк для многострочного заголовка.

"text": "Динамика выручки"

Многострочный вариант:

"text": ["Динамика выручки", "за 2024 год"]

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

anchor

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

Возможные значения:

  • start — выравнивание по левому краю
  • middle — центрирование
  • end — выравнивание по правому краю

Пример:

"anchor": "middle"

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

orient

orient управляет расположением заголовка относительно области визуализации:

  • top — над графиком
  • bottom — под графиком
  • left — слева, вертикальная ориентация
  • right — справа, вертикальная ориентация
"orient": "top"

При вертикальном размещении (left/right) заголовок обычно поворачивается на 90 градусов.

offset

offset задаёт расстояние между заголовком и основным графическим содержимым.

"offset": 15

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

Типографика заголовка

Vega предоставляет набор свойств для управления текстовым оформлением.

font и fontSize

"font": "Arial",
"fontSize": 18

font задаёт семейство шрифта, fontSize — размер в пикселях. Эти параметры влияют на визуальную иерархию графика.

fontWeight и fontStyle

"fontWeight": "bold",
"fontStyle": "italic"

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

color

"color": "#333333"

Определяет цвет текста заголовка. Часто используется для согласования с общей палитрой визуализации.

Подзаголовок (subtitle)

В Vega поддерживается дополнительное поле subtitle, расширяющее семантику заголовка.

{
  "title": {
    "text": "Продажи",
    "subtitle": "Сравнение по кварталам"
  }
}

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

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

"subtitleFontSize": 12,
"subtitleColor": "#666666",
"subtitlePadding": 4

Выравнивание и компоновка

Заголовок в Vega участвует в системе layout, влияя на доступное пространство для визуальных элементов. Он рассматривается как часть верхнего уровня сцены и может изменять внутренние отступы сигнала padding.

Пример влияния:

  • увеличение fontSize приводит к увеличению верхнего отступа
  • длинный subtitle может расширять высоту canvas
  • orient: left/right влияет на ширину доступной области графика

Стилизация через конфигурацию

Помимо локального задания title, Vega позволяет задавать глобальные стили через config:

"config": {
  "title": {
    "font": "Inter",
    "fontSize": 20,
    "anchor": "start",
    "color": "#111111"
  }
}

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

Сравнение с Vega-Lite

В Vega-Lite поле title имеет более упрощённую форму и чаще используется как строка или минимальный объект. Основное отличие заключается в уровне абстракции:

  • Vega: полная кастомизация, управление layout и стилями
  • Vega-Lite: декларативное описание с ограниченным набором параметров

В Vega-Lite:

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

или:

"title": {
  "text": "Продажи по регионам",
  "anchor": "middle"
}

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

Динамическое управление через сигналы

В Vega title может зависеть от сигналов (signals), что позволяет изменять заголовок в интерактивных сценариях.

"title": {
  "signal": "datumTitle"
}

Или с выражением:

"title": {
  "text": {
    "signal": "'Выбор: ' + selection"
  }
}

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

Многоуровневые заголовки

В сложных визуализациях title может представлять собой иерархическую структуру:

"title": {
  "text": "Финансовые показатели",
  "subtitle": [
    "Q1–Q4",
    "в разбивке по регионам"
  ]
}

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

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

title интегрируется в общую структуру Vega-spec вместе с:

  • axes
  • legends
  • marks
  • signals

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

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

  • длинные строки могут автоматически переноситься или обрезаться в зависимости от конфигурации
  • вертикальные заголовки (left, right) требуют учёта ширины padding
  • многострочные заголовки влияют на высоту всего layout
  • при отсутствии явного title заголовок не резервирует пространство
Оглавление