Отключение легенды

В библиотеке Vega легенды являются отдельными визуальными компонентами, связанными со шкалами (scales) и отображающими соответствие между данными и визуальными свойствами: цветом, размером, формой, прозрачностью и другими каналами кодирования. Управление их отображением критично при построении интерфейсов визуализации, где требуется либо полная минималистичность, либо вынос объяснений в отдельные элементы UI.

В экосистеме Vega-Lite отключение легенды реализуется декларативно через описание encoding или конфигурацию масштаба отображения. Подход отличается от императивных библиотек: вместо вызова функций управления DOM изменяется описание спецификации графика.

Основной способ отключения легенды — явное указание legend: null внутри канала кодирования.

Пример отключения легенды для цветового канала

{
  "mark": "bar",
  "encoding": {
    "x": { "field": "category", "type": "nominal" },
    "y": { "field": "value", "type": "quantitative" },
    "color": {
      "field": "category",
      "type": "nominal",
      "legend": null
    }
  }
}

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

Отключение легенды для нескольких каналов

Легенда управляется отдельно для каждого канала:

{
  "mark": "point",
  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "y", "type": "quantitative" },
    "size": {
      "field": "group",
      "type": "nominal",
      "legend": null
    },
    "color": {
      "field": "group",
      "type": "nominal",
      "legend": null
    }
  }
}

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

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

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

Vega-Lite config

{
  "config": {
    "legend": null
  },
  "mark": "line",
  "encoding": {
    "x": { "field": "date", "type": "temporal" },
    "y": { "field": "value", "type": "quantitative" },
    "color": { "field": "series", "type": "nominal" }
  }
}

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

Отключение легенды в Vega (низкоуровневый API)

В Vega легенды описываются в секции legends и привязываются к шкалам.

Удаление легенды через удаление определения

{
  "scales": [
    {
      "name": "color",
      "type": "ordinal",
      "domain": ["A", "B", "C"],
      "range": ["red", "blue", "green"]
    }
  ],
  "legends": []
}

Пустой массив legends полностью отключает отображение всех легенд.

Управление легендой через signal (Vega)

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

{
  "signals": [
    {
      "name": "showLegend",
      "value": false
    }
  ],
  "legends": [
    {
      "fill": "color",
      "encode": {
        "labels": {
          "update": {
            "opacity": { "signal": "showLegend ? 1 : 0" }
          }
        }
      }
    }
  ]
}

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

Частичное отключение элементов легенды

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

Скрытие легенды только для шкалы цвета

{
  "encoding": {
    "color": {
      "field": "type",
      "type": "nominal",
      "legend": null
    }
  }
}

Сохранение легенды для size, отключение для color

{
  "encoding": {
    "size": {
      "field": "value",
      "type": "quantitative"
    },
    "color": {
      "field": "group",
      "type": "nominal",
      "legend": null
    }
  }
}

Отключение легенды через условное управление (Vega-Lite transform approach)

В сложных интерфейсах иногда используется переключение через параметры (params).

{
  "params": [
    {
      "name": "showLegend",
      "value": false
    }
  ],
  "mark": "area",
  "encoding": {
    "color": {
      "field": "category",
      "type": "nominal",
      "legend": {
        "condition": {
          "param": "showLegend",
          "value": true
        },
        "value": null
      }
    }
  }
}

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

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

При использовании агрегированных данных Vega-Lite может автоматически генерировать легенды даже без явного указания. Это связано с тем, что шкала считается дискретной.

Пример автоматической легенды

{
  "mark": "bar",
  "encoding": {
    "x": { "aggregate": "sum", "field": "value", "type": "quantitative" },
    "color": { "field": "category", "type": "nominal" }
  }
}

Чтобы гарантированно отключить легенду:

{
  "encoding": {
    "color": {
      "field": "category",
      "type": "nominal",
      "legend": null
    }
  }
}

Стилизация вместо легенды

Отключение легенды часто сопровождается переносом информации в альтернативные каналы:

  • подписи осей (axis.label)
  • tooltips
  • кастомные HTML-легенды вне Vega/Vega-Lite
  • аннотации (text mark)

В Vega-Lite это выглядит как замена визуального компонента:

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

Типовые ошибки при отключении легенды

1. Использование несуществующего параметра legend: false

Некорректный вариант:

"legend": false

Правильный вариант:

"legend": null

2. Ожидание глобального эффекта без config

Указание:

"legend": null

влияет только на конкретный encoding-канал, если не задан config.

3. Конфликт с повторяющимися шкалами

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

Поведение при трансляции Vega-Lite → Vega

Vega-Lite компилируется в Vega, и при этом:

  • legend: null преобразуется в отсутствие legend component
  • глобальные config-правила превращаются в свойства scale/guide
  • автоматические легенды становятся явными legends блоками

Это означает, что отключение легенды в Vega-Lite всегда детерминированно приводит к удалению соответствующего элемента в Vega runtime.

Отключение легенды в сложных многослойных графиках

В layered charts каждая серия может иметь собственную легенду.

{
  "layer": [
    {
      "mark": "line",
      "encoding": {
        "x": { "field": "x", "type": "quantitative" },
        "y": { "field": "y1", "type": "quantitative" },
        "color": {
          "value": "steelblue",
          "legend": null
        }
      }
    },
    {
      "mark": "line",
      "encoding": {
        "y": { "field": "y2", "type": "quantitative" },
        "color": {
          "value": "orange",
          "legend": null
        }
      }
    }
  ]
}

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

Практическая модель управления легендами

Логика отключения легенд в Vega/Vega-Lite строится по иерархии:

  1. encoding-level legend: null
  2. config-level legend: null
  3. удаление legends (Vega)
  4. реактивное скрытие через signals (Vega)
  5. трансляция в отсутствие guide component

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

Оглавление