Легенды

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

Свойства легенды

Легенде можно передать одну или несколько шкал. Обязательно укажите хотя бы одно из свойств size, shape, fill, stroke, strokeDash или opacity. Если задано несколько шкал, у них должна быть одинаковая область определения входных значений. Иначе поведение легенды не определено.

Свойства доступности ≥ 5.11

При выводе SVG эти свойства определяют атрибуты ARIA, которые помогают вспомогательным технологиям описывать легенду.

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

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

Расположение легенды

Допустимые значения параметра orient.

Несколько легенд. Легенды с расположением left или right по умолчанию выстраиваются вертикально, а с расположением top или bottom — горизонтально. При других значениях несколько легенд в одном месте накладываются друг на друга. Размещение можно изменить в конфигурации легенд.

Смещение легенды. Для расположений left, right, top и bottom параметр offset задаёт расстояние до остальной части диаграммы. При none он игнорируется. При остальных значениях задаёт сдвиг легенды от угла области данных внутрь диаграммы.

Пользовательские кодировки легенды

С помощью параметра encode можно настраивать свойства примитивов всех элементов легенды:

• legend — группа легенды;
• title — текстовый примитив заголовка;
• labels — текстовые примитивы подписей;
• symbols — примитивы условных знаков;
• entries — группы элементов легенды, каждая из которых содержит условный знак и подпись;
• gradient — примитивы прямоугольников: один прямоугольник с градиентной заливкой для непрерывной легенды или несколько прямоугольников со сплошной заливкой для ступенчатой.

Каждый элемент принимает набор правил визуального кодирования, сгруппированных в объекты enter, update, exit и другие, как описано в разделе «Примитивы». Для оформления можно использовать стандартные ссылки на значения.

Каждый блок encode также может содержать строковое свойство name для уникального имени набора примитивов, логическое interactive для обработки событий ввода и строковое свойство style (или массив строк) для применения значений свойств по умолчанию. Если не указано иное, для заголовка используется стиль "guide-title", а для подписей — "guide-label".

Каждому условному знаку и подписи легенды соответствует объект данных со следующими полями. Их можно использовать в пользовательских правилах визуального кодирования:

• index — целочисленный индекс;
• label — текст подписи;
• value — значение данных;
• size — размер условного знака (только для легенд условных знаков).

В примере ниже показано, как задать собственные шрифты и рамку легенды для шкалы цвета заливки. Блок labels также делает подписи чувствительными к событиям ввода и меняет цвет текста при наведении указателя.

"legends": [
  {
    "fill": "color",
    "encode": {
      "title": {
        "update": {
          "fontSize": {"value": 14}
        }
      },
      "labels": {
        "interactive": true,
        "update": {
          "fontSize": {"value": 12},
          "fill": {"value": "black"}
        },
        "hover": {
          "fill": {"value": "firebrick"}
        }
      },
      "symbols": {
        "update": {
          "stroke": {"value": "transparent"}
        }
      },
      "legend": {
        "update": {
          "stroke": {"value": "#ccc"},
          "strokeWidth": {"value": 1.5}
        }
      }
    }
  }
]

Для labels можно задать собственный текст через свойство text. Например, порядковая шкала может служить таблицей соответствия между базовым value и текстом подписи легенды. Чтобы вручную расположить легенду с orient равным none, используйте свойства верхнего уровня legendX и legendY, а не свойства x и y в пользовательском блоке кодировки.