Канал text

Визуализация на основе текста в Vega-Lite строится вокруг специального типа примитива — текстового маркера (mark: "text"), который позволяет отображать значения данных не в виде геометрических фигур, а в виде строковых подписей, чисел, вычисленных выражений или агрегированных результатов. Центральным элементом управления выводом текста выступает канал text, который определяет содержимое отображаемой надписи.

Базовая структура текстовой визуализации

Текстовая визуализация в Vega-Lite описывается через стандартную структуру спецификации:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
    "values": [
      { "category": "A", "value": 10 },
      { "category": "B", "value": 25 }
    ]
  },
  "mark": "text",
  "encoding": {
    "x": { "field": "category", "type": "nominal" },
    "y": { "field": "value", "type": "quantitative" },
    "text": { "field": "value", "type": "quantitative" }
  }
}

Ключевой момент заключается в том, что канал text отвечает исключительно за содержимое подписи, в то время как координатные каналы (x, y) определяют позиционирование текста на графике.

Канал text как механизм отображения данных

Канал text в Vega-Lite представляет собой универсальный механизм преобразования значений данных в строковое представление. Он может принимать:

  • прямое поле данных (field)
  • агрегированное значение (aggregate)
  • вычисленное выражение (calculate)
  • форматированное значение (format через format и formatType)
  • результат трансформаций (transform)

Использование прямого поля

"text": { "field": "value", "type": "quantitative" }

В этом случае значение отображается без изменения. Vega-Lite автоматически приводит число к строке.

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

Канал text поддерживает форматирование через параметр format, который особенно важен при работе с количественными данными.

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

Формат .2f задаёт отображение числа с двумя знаками после запятой. Форматирование основано на спецификации форматирования чисел D3-format.

Примеры распространённых форматов:

  • .0f — целое число
  • .2f — два знака после запятой
  • .2% — процентное отображение
  • , — разделение тысяч

Текст как результат агрегации

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

"text": {
  "aggregate": "mean",
  "field": "value",
  "type": "quantitative"
}

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

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

  • count
  • sum
  • average / mean
  • min
  • max
  • median

Группировка и текстовые подписи

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

{
  "mark": "text",
  "encoding": {
    "x": { "field": "category", "type": "nominal" },
    "text": { "aggregate": "sum", "field": "value" }
  }
}

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

Вычисляемые значения в text через calculate

Для более гибких сценариев используется трансформация calculate, позволяющая формировать строковые выражения.

{
  "transform": [
    {
      "calculate": "'Значение: ' + datum.value",
      "as": "label"
    }
  ],
  "mark": "text",
  "encoding": {
    "text": { "field": "label", "type": "nominal" }
  }
}

В этом случае канал text отображает уже подготовленное строковое поле.

Различие между field и expr в text

Vega-Lite поддерживает два подхода:

  • field — обращение к данным
  • calculate — вычисление нового поля

В более низкоуровневом Vega можно использовать выражения напрямую в text, но в Vega-Lite это реализуется через трансформации.

Использование условных выражений

Через calculate можно реализовывать условное форматирование текста:

{
  "transform": [
    {
      "calculate": "datum.value > 20 ? 'high' : 'low'",
      "as": "level"
    }
  ],
  "mark": "text",
  "encoding": {
    "text": { "field": "level", "type": "nominal" }
  }
}

Канал text в данном случае отображает категориальное значение, вычисленное на основе условий.

Совмещение text с другими mark-слоями

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

{
  "layer": [
    {
      "mark": "bar",
      "encoding": {
        "x": { "field": "category", "type": "nominal" },
        "y": { "field": "value", "type": "quantitative" }
      }
    },
    {
      "mark": "text",
      "encoding": {
        "x": { "field": "category", "type": "nominal" },
        "y": { "field": "value", "type": "quantitative" },
        "text": { "field": "value", "type": "quantitative" }
      }
    }
  ]
}

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

Выравнивание и позиционирование текста

Помимо канала text, важную роль играют параметры визуального размещения:

  • align — горизонтальное выравнивание (left, center, right)
  • baseline — вертикальное выравнивание (top, middle, bottom)
  • dx, dy — смещение
"mark": {
  "type": "text",
  "align": "center",
  "baseline": "middle"
}

Эти параметры не влияют на содержимое text, но определяют его читаемость.

Работа с пустыми значениями

Если поле содержит null, канал text может отображать пустую строку или быть заменён через transform:

{
  "transform": [
    {
      "calculate": "isValid(datum.value) ? datum.value : 'N/A'",
      "as": "label"
    }
  ]
}

Таким образом обеспечивается устойчивость визуализации.

Форматирование дат в text

Для временных данных используется форматирование через timeUnit и format:

"text": {
  "field": "date",
  "type": "temporal",
  "timeUnit": "yearmonth"
}

Или более детально:

"text": {
  "field": "date",
  "type": "temporal",
  "format": "%Y-%m-%d"
}

Текстовый канал в этом случае превращает временные значения в читаемые строки.

Использование text в KPI-индикаторах

Типичный сценарий — отображение метрик:

{
  "mark": "text",
  "encoding": {
    "text": {
      "aggregate": "sum",
      "field": "revenue",
      "type": "quantitative",
      "format": "$,.0f"
    }
  }
}

Такой подход применяется в дашбордах для вывода ключевых показателей без дополнительных графических элементов.

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

В Vega (низкоуровневой спецификации) текст задаётся через прямые выражения:

{
  "type": "text",
  "encode": {
    "enter": {
      "text": { "signal": "datum.value" }
    }
  }
}

В Vega-Lite канал text абстрагирует этот механизм, предоставляя декларативное описание без необходимости работы с сигналами.

Типичные ошибки при использовании text

  • попытка передать объект вместо строки или поля
  • отсутствие позиционирующих каналов (x, y) при использовании mark: text
  • несоответствие типов данных и формата
  • использование агрегатов без группировки
  • попытка сложного форматирования без transform

Комбинирование text с условной стилизацией

Хотя канал text отвечает только за содержимое, визуальный контекст можно дополнять:

"mark": {
  "type": "text",
  "color": "black",
  "fontSize": 14
}

При необходимости цвет текста может зависеть от данных через encoding:

"color": { "field": "category", "type": "nominal" }

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

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

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

где label может содержать \n.

Роль text в построении информационных слоёв

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

Оглавление