Конфигурация

Объект config задаёт визуальные свойства по умолчанию и определяет тему оформления.

Парсер Vega принимает конфигурацию JSON с исходными настройками визуального кодирования. Разные конфигурации позволяют оформлять диаграммы в разных темах. Конфигурация — это объект JSON с именованными свойствами, сгруппированными по типам. Передайте его дополнительным аргументом методу разбора:

var runtime = vega.parse(spec, config);

Спецификация Vega также может содержать свойство config верхнего уровня. Настройки из него имеют приоритет над внешней конфигурацией, переданной парсеру.

Например, следующая спецификация по умолчанию показывает светло-серую сетку оси:

{
  "width": 500,
  "height": 200,
  "config": {
    "axis": {
      "grid": true,
      "gridColor": "#dedede"
    }
  },
  ...
}

Справочник конфигурации

• Свойства представления
• Свойства событий
• Свойства примитивов
• Свойства стилей
• Свойства осей
• Свойства легенд
• Свойства заголовков
• Свойства проекций
• Диапазоны шкал
• Сигналы

Свойства представления

Свойства верхнего уровня объекта конфигурации.

Примеры

Зададим цвета фона представления и области построения:

{
  "background": "white",
  "group": {
    "fill": "#dedede"
  }
}

Зададим немецкую локаль для чисел и времени:

{
  "locale": {
    "number": {
      "decimal": ",",
      "thousands": ".",
      "grouping": [3],
      "currency": ["", " €"]
    },
    "time": {
      "dateTime": "%A, der %e. %B %Y, %X",
      "date": "%d.%m.%Y",
      "time": "%H:%M:%S",
      "periods": ["AM", "PM"],
      "days": ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"],
      "shortDays": ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"],
      "months": ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"],
      "shortMonths": [ "Jan", "Feb", "Mrz", "Apr", "Mai", "Jun", "Jul", "Aug", "Sep", "Okt", "Nov", "Dez"]
    }
  }
}

К оглавлению

Свойства событий

Настройки обработки событий в блоке "events".

Примеры

Отключим обработчики внешних элементов DOM с CSS-селектором и разрешим для окна браузера только события mousemove и mouseup:

"events": {
  "selector": false,
  "window": ["mousemove", "mouseup"]
}

Подавим стандартное поведение всех событий внутри представления Vega:

"events": {
  "defaults": {
    "prevent": true
  }
}

Подавим стандартное поведение всех событий внутри представления, кроме wheel:

"events": {
  "defaults": {
    "allow": ["wheel"]
  }
}

К оглавлению

Свойства примитивов

Настройки по умолчанию для каждого типа примитива задаются в блоке с именем типа, например "area", "line" или "rect". Внутри допустимы свойства соответствующего примитива, такие как "fill", "stroke", "size" и "font". Общие значения для всех типов задаются в свойстве "mark".

Важные ограничения:

• Цвет заливки или обводки по умолчанию применяется, только если в спецификации Vega не определены ни "fill", ни "stroke".
• Значения общего свойства "mark" переопределяются настройками конкретного типа, например "rect". Во встроенной конфигурации Vega уже заданы цвета некоторых типов примитивов; они имеют приоритет над цветами, указанными только в общем блоке "mark".

Примеры

Зададим цвет заливки и размер по умолчанию для symbol:

{
  "symbol": {
    "fill": "steelblue",
    "size": 64
  }
}

Зададим общую непрозрачность для всех типов примитивов:

{
  "mark": {
    "opacity": 0.8
  }
}

К оглавлению

Свойства стилей

Помимо свойств примитивов, оформление по умолчанию можно настроить именованными стилями в блоке style конфигурации. Стиль применяется директивой style в определении примитива.

Например, стиль "square" задаёт форму и толщину обводки для символов:

"style": {
  "square": {
    "shape": "square",
    "strokeWidth": 2
  }
}

Помимо пользовательских стилей, Vega предоставляет встроенные:

• guide-label: подписи осей и легенд;
• guide-title: заголовки осей и легенд;
• group-title: заголовки диаграмм и разделов.

Стили имеют приоритет над общими настройками примитивов, но уступают свойствам осей, легенд и заголовков, описанным ниже.

К оглавлению

Свойства осей

Настройки осей по умолчанию задаются в свойстве "axis" объекта конфигурации и применяются ко всем осям.

Дополнительные блоки относятся к осям определённой ориентации ("axisX", "axisY", "axisLeft", "axisTop" и т. д.) либо к полосовым шкалам ("axisBand"). Например, свойства "axisBand" применяются только к осям шкалы "band". Если подходит несколько блоков, настройки типа шкалы имеют приоритет над настройками ориентации, а те — над общими.

Доступность осей

Свойства доступности задают атрибуты ARIA при выводе SVG через Vega.

Пример

Пример задаёт светло-серый цвет подписей всех осей и поворачивает подписи нижней оси.

{
  "axis": {
    "labelColor": "#ccc"
  },
  "axisBottom": {
    "labelAngle": -90
  }
}

К оглавлению

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

Свойства задают настройки легенд по умолчанию. Они указываются в свойстве "legend" объекта конфигурации.

Свойства доступности легенд

Свойства доступности задают атрибуты ARIA (Accessible Rich Internet Applications) при выводе SVG средствами Vega.

Свойства размещения легенд ≥ 5.0

Легенды с одинаковым значением orient размещаются вместе: последовательно по вертикали или горизонтали. Свойство layout настраивает их расположение в представлении Vega. В объекте layout можно задать общие свойства для всех легенд и отдельные наборы свойств для конкретных значений orient.

Помимо общих свойств, layout может содержать вложенные объекты с теми же свойствами для каждого допустимого значения orient легенды, кроме "none": "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right".

Примечание: в конфигурации по умолчанию уже заданы параметры размещения для направлений "left" и "right". Общие свойства верхнего уровня не переопределяют эти более точные настройки. Чтобы изменить размещение таких легенд, задайте вложенный объект для соответствующего направления.

Примеры

В этом примере каждая легенда получает внутренний отступ 10 пикселей и светло-серую границу:

{
  "legend": {
    "padding": 10,
    "strokeColor": "#ccc",
    "strokeWidth": 1
  }
}

В этом примере легенды с orient = "bottom" располагаются вертикально с промежутком 2 пикселя, привязываются по горизонтали к центру области диаграммы и центрируются внутри выделенной им области:

{
  "legend": {
    "layout": {
      "bottom": {
        "anchor": "middle",
        "direction": "vertical",
        "center": true,
        "margin": 2
      }
    }
  }
}

К оглавлению

Свойства заголовка

Свойства задают настройки заголовков по умолчанию. Они указываются в свойстве "title" объекта конфигурации.

Свойства доступности заголовка

Свойства доступности задают атрибуты ARIA (Accessible Rich Internet Applications) при выводе SVG средствами Vega.

Пример

В этом примере для каждого заголовка задаются отступ 10 пикселей и размер шрифта 18 пикселей.

{
  "title": {
    "offset": 10,
    "fontSize": 18
  }
}

К оглавлению

Свойства проекций

Свойства по умолчанию для картографических проекций, если они не заданы явно в исходной JSON-спецификации. Можно указать любое допустимое свойство проекции. Эти свойства помещаются в объект "projection" конфигурации. Часто так задают тип проекции по умолчанию.

Пример

В этом примере проекцией по умолчанию становится "equalEarth":

{
  "projection": {
    "type": "equalEarth"
  }
}

К оглавлению

Свойства диапазонов шкал

Свойства задают именованные массивы диапазонов, которые можно использовать при определении диапазона шкалы, например {"type": "ordinal", "range": "category"}. Они указываются в объекте "range" конфигурации.

Свойства со значением-объектом должны быть допустимыми определениями диапазона шкалы.

Пример

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

{
  "range": {
    "category": [
      "#5079a5",
      "#ef8e3b",
      "#dd565c",
      "#79b7b2",
      "#5da052",
      "#ecc853",
      "#ad7aa1",
      "#ef9ba7",
      "#9b7461",
      "#bab0ac"
    ],
    "ordinal": {"scheme": "greens"},
    "ramp": {"scheme": "purples"}
  }
}

К оглавлению

Определения сигналов ≥ 5.5

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

Пример

Чтобы менять размеры шрифта динамически, можно задать сигнал с коэффициентом масштабирования, а затем выразить через него другие параметры конфигурации:

{
  "signals": [
    {"name": "fontSizeScale", "value": 1}
  ],
  "text": {
    "fontSize": {"signal": "11 * fontSizeScale"}
  }
}

К оглавлению