Спецификация

Спецификация Vega описывает интерактивную визуализацию в формате JavaScript Object Notation (JSON).

Ниже приведён общий шаблон спецификации Vega. Полная спецификация содержит необходимые определения данных, шкал, осей, графических примитивов и других компонентов.

{
  "$schema": "https://vega.github.io/schema/vega/v6.json",
  "description": "Пример структуры спецификации.",
  "width": 500,
  "height": 200,
  "padding": 5,
  "autosize": "pad",

  "signals": [],
  "data": [],
  "scales": [],
  "projections": [],
  "axes": [],
  "legends": [],
  "marks": []
}

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

Свойство Тип Описание
$schema URL URL-адрес схемы Vega.
description String Текстовое описание визуализации. Начиная с версии ≥ 5.10, оно задаёт атрибут aria-label контейнера представления Vega.
background Color | Signal Цвет фона всего представления (по умолчанию прозрачный). Если значением служит сигнал ≥ 5.10, выражение используется как свойство update определения сигнала background.
width Number | Signal Ширина прямоугольной области данных в пикселях. Если значением служит сигнал ≥ 5.10, выражение используется как свойство update определения сигнала width.
height Number | Signal Высота прямоугольной области данных в пикселях. Если значением служит сигнал ≥ 5.10, выражение используется как свойство update определения сигнала height.
padding Number | Object | Signal Отступы вокруг визуализации в пикселях. Число задаёт одинаковый отступ со всех сторон. Объект должен иметь вид {"left": 5, "top": 5, "right": 5, "bottom": 5}. Отступы применяются после завершения автоматического расчёта размеров. Если значением служит сигнал ≥ 5.10, выражение используется как свойство update определения сигнала padding и должно возвращать число или объект отступов.
autosize String или Autosize или Signal Определяет способ расчёта размеров визуализации. Строковое значение может быть pad (по умолчанию), fit, fit-x, fit-y или none. Объект позволяет дополнительно задать параметры размера содержимого и автоматического перерасчёта. Подробнее см. «Автоматический расчёт размеров». Если значением служит сигнал ≥ 5.10, выражение используется как свойство update определения сигнала autosize и должно возвращать полный объект параметров расчёта размеров.
config Конфигурация Параметры конфигурации со значениями по умолчанию для примитивов, осей и легенд.
signals Сигнал[ ] Сигналы — динамические переменные, задающие параметры визуализации.
data Данные[ ] Определения наборов данных и преобразований указывают, какие данные загружать и как их обрабатывать.
scales Шкала[ ] Шкалы сопоставляют значения данных — числа, даты, категории и другие — визуальным значениям: координатам, цветам и размерам.
projections Проекция[ ] Картографические проекции преобразуют пары (долгота, широта) в координаты (x, y).
axes Ось[ ] Координатные оси отображают пространственные шкалы.
legends Легенда[ ] Легенды показывают соответствие значений шкал цветам, формам и размерам.
title Заголовок Текст заголовка, описывающего визуализацию.
marks Примитив[ ] Графические примитивы кодируют данные геометрическими фигурами: прямоугольниками, линиями, символами и другими.
encode Кодирование Правила кодирования визуальных свойств группового примитива верхнего уровня, представляющего прямоугольную область данных. Например, здесь можно задать цвет фона области построения вместо фона всего представления.
usermeta Object Необязательные метаданные, которые парсер Vega игнорирует.

Автоматический расчёт размеров

Размер представления Vega можно задавать и пересчитывать разными способами. Если значение задано объектом, он должен иметь вид {"type": "pad", "resize": true}. Поле type содержит один из строковых режимов автоматического расчёта, а логическое поле resize указывает, нужно ли заново рассчитывать компоновку при каждом обновлении.

Имя Тип Описание
type String Обязательно. Режим расчёта размера: "pad" (по умолчанию), "fit", "fit-x", "fit-y" или "none". Описание режимов приведено ниже.
resize Boolean Логическое значение, указывающее, нужно ли пересчитывать компоновку при каждом обновлении представления. По умолчанию (false) она рассчитывается один раз при инициализации и пересчитывается при изменении сигналов высоты или ширины. В остальных случаях компоновка остаётся неизменной. Чтобы принудительно пересчитать размер извне, вызовите метод API View.resize.
contains String Способ учёта отступов при расчёте размера: content (по умолчанию) или padding. При content значения width и height задают размеры прямоугольной области данных, а padding добавляется к ним. При padding отступы включены в расчёт, поэтому width и height задают общий размер представления.

Режимы автоматического расчёта размеров

Общий размер визуализации Vega зависит от заданных значений width, height и padding, а также от её содержимого: осей, легенд и заголовков. Для разных задач Vega предлагает несколько режимов autosize, определяющих итоговый размер представления:

  • none: автоматический расчёт размера не выполняется. Общий размер визуализации определяется только значениями ширины, высоты и отступов. Например, по умолчанию общая ширина равна width + padding.left + padding.right. Содержимое за пределами этой области обрезается. Если autosize.contains равно "padding", общая ширина равна просто width.
  • pad: размер представления автоматически увеличивается так, чтобы всё содержимое было видно. Это значение autosize по умолчанию; оно учитывает оси, легенды и другие элементы за пределами заданных ширины и высоты. Общий размер часто превышает сумму указанных размеров и отступов.
  • fit: компоновка автоматически подстраивается под заданные ширину, высоту и отступы. Чтобы освободить место для осей, легенд и заголовков, область построения уменьшается; при этом могут измениться значения сигналов width и height. Для многих графиков этот режим подходит, но он не всегда способен показать всё содержимое. Например, если одним только осям и легендам нужно больше места, чем предусмотрено шириной и высотой, часть содержимого будет обрезана. Как и в режиме none, по умолчанию общая ширина равна width + padding.left + padding.right, где width — исходное значение до изменения компоновки. Если autosize.contains равно "padding", общая ширина равна исходному значению width.
  • fit-x: действует как fit, но под заданный размер подстраивается только ширина (ось x). Высота рассчитывается автоматически, как в режиме pad. ≥ 3.1
  • fit-y: действует как fit, но под заданный размер подстраивается только высота (ось y). Ширина рассчитывается автоматически, как в режиме pad. ≥ 3.1