Поле labelFlush и labelPadding

Vega-Lite использует систему декларативных спецификаций, в которой каждая деталь визуализации описывается через JSON-структуру. Подписи осей (axis labels) в этой модели являются частью описания масштаба и отображения данных, а их поведение определяется набором параметров форматирования, среди которых важное место занимают labelFlush и labelPadding.

Визуальные подписи осей выполняют функцию интерпретации числовых или категориальных значений. В терминах Vega и Vega-Lite подписи являются частью компонента axis, который связывает scale и visual encoding.

Подписи формируют визуальную границу между областью данных (data rectangle) и внешним пространством графика. Их размещение напрямую влияет на:

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

Именно в этой зоне управления появляются параметры labelFlush и labelPadding, регулирующие геометрию текстовых элементов относительно края визуализации.

Поведение labelFlush

Параметр labelFlush управляет выравниванием крайних подписей оси относительно границ визуальной области. Его основная задача — устранение ситуаций, когда первая или последняя подпись выходит за пределы контейнера или визуально «прилипает» к краю.

Основной принцип работы

При включённом labelFlush система пытается:

  • сдвинуть крайние подписи внутрь области отображения;
  • выровнять их так, чтобы текст полностью помещался в пределах view;
  • уменьшить вероятность обрезки (clipping).

Если ось горизонтальная (X), то корректируется поведение первой и последней метки по ширине. Если вертикальная (Y), то корректируются верхняя и нижняя подписи.

Логика принятия решения

Алгоритм поведения можно описать следующим образом:

  • определяется bounding box каждой крайней подписи;
  • проверяется пересечение с границей viewport;
  • при обнаружении пересечения подпись смещается внутрь;
  • перераспределение происходит только для крайних элементов, а не для всех меток.

Особенности применения

labelFlush особенно заметен в следующих случаях:

  • категориальные оси с длинными строками;
  • временные шкалы с форматированием дат;
  • диаграммы с плотной компоновкой и малым padding контейнера;
  • случаи, где axis title отсутствует, и подписи являются единственным текстовым ориентиром.

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

Поведение labelPadding

Параметр labelPadding определяет расстояние между подписью оси и её визуальной линией (axis line) или делениями (ticks). В отличие от labelFlush, он не связан с логикой обрезки, а отвечает за визуальный комфорт и читаемость.

Геометрический смысл

labelPadding задаёт фиксированное смещение текста относительно базовой линии оси:

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

Поведение при разных масштабах

При изменении масштаба (scale):

  • абсолютное значение padding остаётся постоянным в пикселях;
  • визуальная плотность может изменяться;
  • при малых размерах графика padding становится доминирующим фактором компоновки.

Влияние на читаемость

Увеличение labelPadding приводит к:

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

Слишком большое значение вызывает:

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

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

Оба параметра действуют на разные уровни системы отображения, но их совместное использование влияет на итоговую геометрию axis-компонента.

Приоритеты обработки

Внутренний порядок формирования оси можно представить так:

  1. расчёт scale и распределение tick values;
  2. генерация label текстов;
  3. применение labelPadding как фиксированного смещения;
  4. проверка границ viewport;
  5. применение labelFlush при необходимости корректировки крайних элементов.

Возможные эффекты взаимодействия

При разных комбинациях значений наблюдаются следующие паттерны:

  • малый padding + включённый flush крайние подписи корректируются минимально, плотность высокая;

  • большой padding + включённый flush увеличивается вероятность смещения оси внутрь, особенно при длинных метках;

  • flush отключён + большой padding возможен выход текста за пределы контейнера без корректировки;

  • flush включён + нулевой padding подписи максимально прижаты к оси, но остаются в пределах view.

Поведение в различных типах осей

Ось X (категориальная)

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

  • длинных строках категорий;
  • небольшом количестве категорий;
  • фиксированной ширине графика.

labelPadding в этом случае управляет вертикальным «отрывом» текста от оси, формируя базовую читаемость.

Ось Y (числовая)

На вертикальной оси:

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

Особенно критично это в случаях:

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

Временные шкалы

Для temporal-осей:

  • labelFlush предотвращает обрезку дат в начале и конце временного интервала;
  • labelPadding стабилизирует расстояние при изменении формата даты (например, от YYYY к DD MMM).

Компоновка и влияние на layout

Оси в Vega-Lite являются частью layout-движка, где каждый элемент влияет на общий размер визуализации.

Влияние labelPadding

labelPadding напрямую участвует в расчёте:

  • внутреннего отступа plot area;
  • минимальной ширины/высоты canvas;
  • расстояния между multiple views при facet-композиции.

Влияние labelFlush

labelFlush не увеличивает layout напрямую, но:

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

Примеры конфигурации

Базовая ось с padding

{
  "mark": "bar",
  "encoding": {
    "x": { "field": "category", "type": "nominal" },
    "y": { "field": "value", "type": "quantitative" }
  },
  "config": {
    "axis": {
      "labelPadding": 8
    }
  }
}

Ось с включённым labelFlush

{
  "config": {
    "axisX": {
      "labelFlush": true,
      "labelPadding": 4
    }
  }
}

Комбинированное поведение

{
  "config": {
    "axisY": {
      "labelFlush": true,
      "labelPadding": 12
    }
  }
}

Типичные сценарии настройки

  • компактные дашборды: минимальный labelPadding, labelFlush включён для предотвращения обрезки;
  • аналитические отчёты: увеличенный labelPadding для читаемости, labelFlush используется выборочно;
  • плотные временные ряды: баланс между параметрами для сохранения структуры шкалы;
  • интерактивные визуализации: динамическая адаптация padding в зависимости от масштаба и zoom.

Поведение при масштабировании контейнера

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

  • labelPadding остаётся фиксированным и может изменять пропорции композиции;
  • labelFlush пересчитывается на основе новых границ viewport;
  • комбинация параметров может приводить к перераспределению пространства между plot area и axis band.

Влияние на многоосевые композиции

В сложных графиках с несколькими осями:

  • padding каждой оси суммируется в общий layout budget;
  • flush может вызывать асимметричное смещение осей;
  • конфликт параметров часто возникает при overlay-диаграммах и dual-axis charts.

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

Оглавление