Условное оформление меток: labelExpr

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

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

Ключевая особенность заключается в том, что значение метки не фиксировано, а вычисляется как выражение:

  • доступ к полям данных через datum
  • доступ к масштабированным значениям через x, y, datum.field
  • использование условных конструкций
  • строковая конкатенация
  • математические и логические функции Vega Expression Language

Базовый синтаксис выражений

Выражение в labelExpr всегда является строкой:

"labelExpr": "datum.value"

или более сложный вариант:

"labelExpr": "datum.category + ': ' + datum.value"

Внутри выражения доступен контекст текущего элемента данных.

Доступ к данным через datum

Основной источник информации — объект datum, содержащий текущую строку данных.

Пример:

"labelExpr": "datum.name"

Если требуется объединение нескольких полей:

"labelExpr": "datum.name + ' (' + datum.count + ')'"

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

Условное формирование текста

Одно из ключевых применений labelExpr — условная логика.

В Vega Expression Language используется тернарный оператор:

"labelExpr": "datum.value > 100 ? 'Высокое значение' : 'Низкое значение'"

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

Более сложные условия:

"labelExpr": "datum.value == null ? 'нет данных' : datum.value > 50 ? 'выше среднего' : 'ниже среднего'"

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

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

Vega Expression Language предоставляет функции форматирования.

Один из распространённых вариантов:

"labelExpr": "format(datum.value, '.2f')"

Использование вместе с текстом:

"labelExpr": "datum.name + ': ' + format(datum.value, '.1f')"

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

Условное скрытие меток

Хотя labelExpr возвращает текст, можно управлять видимостью через пустую строку:

"labelExpr": "datum.value < 10 ? '' : datum.value"

Это распространённый приём фильтрации слабозначимых подписей без изменения слоя данных.

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

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

  • && — и
  • || — или
  • ! — отрицание

Пример комбинированной логики:

"labelExpr": "datum.value > 0 && datum.value < 10 ? 'диапазон A' : 'другой диапазон'"

Работа с текстовыми преобразованиями

В выражениях можно применять строковые функции:

"labelExpr": "upper(datum.category)"

или:

"labelExpr": "lower(datum.category)"

Комбинирование функций:

"labelExpr": "upper(substring(datum.name, 0, 3))"

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

Использование арифметики в labelExpr

Выражения могут включать вычисления:

"labelExpr": "datum.value * 100"

или форматирование результата:

"labelExpr": "format(datum.value * 100, '.0f') + '%'"

Это позволяет отображать производные метрики без изменения исходного датасета.

Контекст масштаба и координат

В некоторых типах визуализаций доступны значения после масштабирования.

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

"labelExpr": "x + ', ' + y"

или условная логика на основе позиции:

"labelExpr": "y > 200 ? 'верхняя зона' : 'нижняя зона'"

Условное форматирование категорий

Одно из наиболее практичных применений — стилизация текста в зависимости от категории:

"labelExpr": "datum.type == 'error' ? 'Ошибка' : datum.type == 'warning' ? 'Предупреждение' : 'ОК'"

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

Вложенные условия и читаемость

При усложнении логики выражения становятся длинными, но сохраняют линейную структуру:

"labelExpr": "datum.value > 80 ? 'высокий' : datum.value > 50 ? 'средний' : datum.value > 20 ? 'низкий' : 'критический'"

Такая форма заменяет полноценные switch-конструкции.

Работа с null и undefined

Обработка отсутствующих значений обязательна при реальных данных:

"labelExpr": "datum.value == null ? 'N/A' : datum.value"

или более строго:

"labelExpr": "isValid(datum.value) ? datum.value : 'нет данных'"

Комбинирование labelExpr с визуальными слоями

labelExpr часто используется вместе с mark types:

  • text marks
  • point annotations
  • rule labels
  • bar labels

Пример:

{
  "mark": "text",
  "encoding": {
    "text": {
      "field": "value",
      "type": "quantitative",
      "labelExpr": "datum.value > 0 ? '+' + datum.value : datum.value"
    }
  }
}

Динамическая семантика подписей

Главная ценность labelExpr заключается в возможности создавать семантически насыщенные подписи:

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

Это превращает метки из статического текста в вычисляемый слой представления.

Ограничения выражений

Несмотря на гибкость, существуют важные ограничения:

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

Эти ограничения обеспечивают предсказуемость рендеринга.

Практика проектирования выражений

При проектировании labelExpr важно учитывать:

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

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

Расширенные сценарии использования

labelExpr активно применяется в:

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

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

Оглавление