Тип text

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

Vega-Lite предоставляет упрощённый слой над Vega, где текстовые подписи чаще всего генерируются через mark: "text" или через производные конструкции (label, tooltip, encoding.text). Несмотря на упрощение, базовая модель остаётся идентичной: каждая строка текста — результат отображения одной или нескольких строк данных.

Текстовый маркер в Vega/Vega-Lite представляет собой объект, который:

  • привязывается к данным (datum)
  • вычисляет текстовое значение через encode
  • размещается в координатной системе (x, y)
  • визуализируется с заданным стилем (font, size, alignment)

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

Базовая структура text mark в Vega

В Vega описание текстового маркера включает type: "text" внутри массива marks:

{
  "marks": [
    {
      "type": "text",
      "from": { "data": "table" },
      "encode": {
        "enter": {
          "x": { "scale": "xscale", "field": "x" },
          "y": { "scale": "yscale", "field": "y" },
          "text": { "field": "label" },
          "fill": { "value": "black" }
        }
      }
    }
  ]
}

Основные компоненты

  • from.data — источник данных
  • encode.enter — начальные параметры отображения
  • text field — ключевой канал текста
  • scales — преобразование данных в координаты

Канал text и его вычисление

Канал text определяет содержимое, отображаемое на экране. Он может быть:

1. Прямым полем данных

"text": { "field": "name" }

2. Вычисляемым выражением

"text": { "expr": "datum.value + ' units'" }

3. Форматированным числом

"text": { "field": "value", "format": ".2f" }

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

Позиционирование текста

Текстовый маркер всегда привязан к координатам:

  • x, y — базовые координаты
  • dx, dy — смещение
  • align — горизонтальное выравнивание
  • baseline — вертикальное выравнивание

Горизонтальное выравнивание

"align": { "value": "center" }

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

  • left
  • center
  • right

Вертикальное выравнивание

"baseline": { "value": "middle" }
  • top
  • middle
  • bottom
  • alphabetic

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

Стилизация текста

Текстовый маркер поддерживает широкий набор визуальных свойств:

Шрифт и размер

"font": { "value": "Arial" },
"fontSize": { "value": 14 }

Толщина и стиль

"fontWeight": { "value": "bold" },
"fontStyle": { "value": "italic" }

Цвет и прозрачность

"fill": { "value": "#333" },
"opacity": { "value": 0.8 }

Поворот текста

"angle": { "value": 45 }

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

Vega-Lite: текст через encoding

В Vega-Lite текстовые элементы чаще всего задаются декларативно:

{
  "mark": "text",
  "encoding": {
    "x": { "field": "category", "type": "ordinal" },
    "y": { "field": "value", "type": "quantitative" },
    "text": { "field": "label" }
  }
}

Здесь отсутствует низкоуровневая структура encode.enter, но логика остаётся той же.

Автоматическое размещение подписей

Vega-Lite способен автоматически рассчитывать позиции текста при использовании композитных визуализаций.

Пример: подписи на столбчатой диаграмме

{
  "data": { "values": [
    {"cat": "A", "val": 10},
    {"cat": "B", "val": 20}
  ]},
  "mark": "bar",
  "encoding": {
    "x": {"field": "cat", "type": "nominal"},
    "y": {"field": "val", "type": "quantitative"}
  },
  "layer": [
    {
      "mark": "bar"
    },
    {
      "mark": "text",
      "encoding": {
        "x": {"field": "cat"},
        "y": {"field": "val"},
        "text": {"field": "val"}
      }
    }
  ]
}

Текстовая прослойка (layer) используется для наложения подписей поверх графических объектов.

Многострочный текст и перенос

В Vega/Vega-Lite перенос строк задаётся символом \n:

"text": { "value": "Первая строка\nВторая строка" }

Для динамических данных:

"text": {
  "expr": "datum.title + '\\n' + datum.subtitle"
}

Ограничения:

  • автоматический перенос отсутствует
  • длина строки управляется вручную или через трансформации данных

Динамическое форматирование текста

Текст может зависеть от вычислений:

Выражения signal

"text": { "signal": "datum.value > 10 ? 'high' : 'low'" }

Форматирование чисел

"text": { "field": "value", "format": ".1%" }

Используется D3-style форматирование.

Текст как часть интерактивных сигналов

Vega поддерживает реактивные сигналы:

"signals": [
  {
    "name": "threshold",
    "value": 50
  }
]
"text": {
  "expr": "datum.value > threshold ? 'OK' : 'LOW'"
}

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

Трансформации данных для текста

Часто текстовые значения формируются через трансформации:

Calculate transform

"transform": [
  {
    "type": "formula",
    "as": "label",
    "expr": "datum.name + ': ' + datum.value"
  }
]

Затем:

"text": { "field": "label" }

Aggregate для подписей

"transform": [
  {
    "type": "aggregate",
    "groupby": ["category"],
    "fields": ["value"],
    "ops": ["sum"],
    "as": ["total"]
  }
]

Текст в многослойных визуализациях

В сложных сценах текст используется как слой аннотаций:

  • подписи точек
  • значения баров
  • осевые метки
  • аннотации событий

Пример структуры:

"layer": [
  { "mark": "line" },
  { "mark": "point" },
  { "mark": "text" }
]

Порядок слоёв определяет перекрытие.

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

Текстовый рендеринг в Vega зависит от SVG или Canvas:

  • SVG: высокая точность, но медленнее при больших объёмах
  • Canvas: выше производительность, но меньше контроля над типографикой

Ограничения:

  • нет полноценного word wrapping
  • ограниченная поддержка кернинга
  • производительность падает при тысячах текстовых узлов

Различия Vega и Vega-Lite в работе с текстом

Характеристика Vega Vega-Lite
Уровень контроля низкоуровневый декларативный
encode полный доступ скрыт
layer вручную автоматизирован
форматирование выражения сокращённые опции
интерактивность полная ограниченная

Использование текста как визуального кода данных

Текст в Vega часто выполняет роль не просто подписи, а самостоятельного канала информации:

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

Это делает text mark равноправным элементом визуальной грамматики, а не вспомогательным слоем.

Композиция текстовых элементов

Сложные интерфейсы формируются через комбинации:

  • text + symbol
  • text + line annotation
  • text + background rect

Пример:

{
  "mark": {
    "type": "text",
    "dx": 5,
    "dy": -5
  }
}

Такая композиция используется для смещения подписей относительно точек данных.

Производительность при работе с текстом

Основные факторы влияния:

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

Оптимизации:

  • предвычисление строк в transform
  • минимизация expr
  • агрегация данных перед рендерингом
  • использование limit через фильтрацию данных

Текст как инструмент аннотации данных

Аннотационные системы строятся на текстовых маркерах:

  • выделение максимумов/минимумов
  • пояснение событий на временных рядах
  • подписи ключевых точек распределений
  • динамические комментарии к данным

Такие элементы создаются через отдельные datasets и фильтрацию:

"transform": [
  { "type": "filter", "expr": "datum.value > 100" }
]

Итоговая роль text mark в архитектуре Vega

Текстовый маркер интегрирован в общую систему визуальных каналов:

  • координатные каналы (x, y)
  • эстетические каналы (цвет, шрифт)
  • семантический канал (text)

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

Оглавление