API расширения Vega
Во время выполнения Vega можно расширять новыми шкалами, проекциями, цветовыми схемами и преобразованиями данных. Это полезно в отдельных проектах, но полученные спецификации Vega в формате JSON могут не работать у тех, кто не установил ваши расширения.
Справочник API расширения
Проекции
# vega.projection(type[, projection]) Исходный код
Функция реестра для добавления картографических проекций и обращения к ним. Строковый аргумент type задаёт имя типа проекции. Если projection не указан, метод возвращает соответствующий конструктор из реестра или null, если он не найден. Если projection указан, он должен быть функцией-конструктором проекции, которая будет зарегистрирована под именем type.
По умолчанию Vega включает все картографические проекции из справочника проекций. Проекции, созданные возвращённым конструктором, имеют дополнительный метод copy, который создаёт копию проекции. Можно зарегистрировать и другие проекции, например из библиотеки d3-geo-projection:
// импортируйте d3-geo-projection и добавьте функции в объект d3
// для регистрации в Vega передайте имя и функцию проекции d3
vega.projection('winkel3', d3.geoWinkel3);
// парсер и среда выполнения Vega теперь поддерживают проекцию 'winkel3'
var runtime = vega.parse({
...,
"projections": [
{ "name": "proj", "type": "winkel3" }
],
...
});
Шкалы
# vega.scale(type[, scale, metadata]) Исходный код
Функция реестра для добавления конструкторов шкал и обращения к ним. Строковый аргумент type задаёт имя типа шкалы. Если scale не указан, метод возвращает соответствующий конструктор из реестра или null, если он не найден. Если scale указан, он должен быть функцией-конструктором шкалы, которая будет зарегистрирована под именем type.
Аргумент metadata содержит дополнительные сведения, по которым Vega определяет, как использовать шкалу. Это строка или массив строк со следующими допустимыми значениями:
"continuous"— шкала имеет непрерывную область определения."discrete"— область определения и диапазон шкалы дискретны."discretizing"— шкала переводит непрерывную область определения в дискретный диапазон."interpolating"— диапазон шкалы задаётся интерполятором цветов."log"— шкала логарифмически преобразует непрерывную область определения."temporal"— область определения шкалы состоит из значений даты и времени.
По умолчанию реестр содержит все типы шкал модуля d3-scale. Шкалы, созданные возвращённым конструктором, получают дополнительное свойство type с именем типа шкалы. Шкалы с методом invert или invertExtent также получают метод invertRange: он возвращает массив значений области определения, соответствующих заданному интервалу диапазона.
// линейная шкала
var linear = vega.scale('linear');
var scale = linear().domain([0, 10]).range([0, 100]);
scale.type; // 'linear'
scale.invertRange([0, 100]); // [0, 10]
var ordinal = vega.scale('ordinal');
// порядковая шкала
var scale1 = ordinal().domain(['a', 'b', 'c']).range([0, 1, 2]);
scale1.type; // 'ordinal'
// порядковая шкала с диапазоном из палитры 'category20'
var scale2 = ordinal().range(vega.scheme('category20'));
var seq = vega.scale('sequential');
// последовательная шкала с палитрой plasma
var scale1 = seq().interpolator(vega.scheme('plasma'));
scale1.type; // 'sequential'
Цветовые схемы
# vega.scheme(name[, scheme]) Исходный код
Функция реестра для добавления цветовых схем и обращения к ним. Строковый аргумент name задаёт имя схемы. Регистр букв в имени не учитывается: "blues" и "Blues" обозначают одну схему. Если scheme не указан, метод возвращает значение схемы из реестра или undefined, если она не найдена. Если scheme указан, он должен быть массивом допустимых значений цвета либо функцией-интерполятором, которая сопоставляет значения из интервала [0, 1] цветам.
По умолчанию реестр содержит все типы схем из справочника цветовых схем Vega.
Преобразования
# vega.transforms Исходный код
Объект, который сопоставляет имена преобразований их конструкторам. Чтобы добавить преобразование в Vega, запишите его в этот объект под нужным именем.
Чтобы парсер распознавал ссылки на преобразование в спецификации Vega, его конструктор обязательно должен иметь свойство Definition с метаданными и описанием параметров. В пакете vega-transforms есть примеры преобразований, показывающие формат такого описания.
Если преобразование добавлено во время выполнения, спецификации Vega с ним не пройдут проверку по стандартной схеме JSON: в ней этого преобразования нет. Чтобы включить новые преобразования в собственную схему JSON, можно собрать Vega самостоятельно, добавив их в экспорт transforms пакета vega-dataflow при сборке.
Форматы данных
# vega.formats(name[, format]) Исходный код
Функция реестра парсеров форматов данных. При вызове с двумя аргументами добавляет парсер format под именем name. При вызове с одним аргументом возвращает существующий парсер с указанным именем. Сигнатура парсера формата:
- format(data, options)
Парсер формата принимает два аргумента: входные data для разбора (например, текст CSV) и набор зависящих от формата options. По умолчанию зарегистрированы следующие форматы:
- dsv: значения с разделителями. Каждая строка текста представляет запись, а поля разделяются заданной строкой. Параметр delimiter указывает разделитель полей.
- csv: значения, разделённые запятыми. Вариант dsv с разделителем
,. - tsv: значения, разделённые символами табуляции. Вариант dsv с разделителем
\t. - json: формат JSON (JavaScript Object Notation). Параметр property указывает вложенное свойство разобранного JSON, которое нужно вернуть; это полезно, если массив данных находится внутри более крупного объекта. Параметр copy (по умолчанию
false) создаёт защитную копию объекта JSON, переданного напрямую в Vega, а не полученного из строки. - topojson: формат сжатого представления географических данных TopoJSON. Требуется указать параметр feature с именем географического объекта для извлечения (например, отдельных контуров всех стран) либо mesh с именем объекта, из которого нужно получить единую сетку (например, все границы стран одним контуром). Подробнее см. описание формата TopoJSON.
Функции выражений
# vega.expressionFunction(name[, fn, visitor]) Исходный код
Функция реестра для добавления функций выражений и обращения к ним. Строковый аргумент name задаёт имя функции в языке выражений Vega. Если fn не указан, метод возвращает функцию из реестра или undefined, если она не найдена. Если fn указан, он должен быть функцией JavaScript, которая будет зарегистрирована под именем name. После регистрации парсер принимает спецификации Vega с вызовами этой функции в выражениях.
Аргумент visitor — функция обхода абстрактного синтаксического дерева (AST) выражения. Она нужна для анализа зависимостей, например поиска шкал или источников данных, и используется внутри Vega. Для большинства простых функций она не требуется, поэтому аргумент можно опустить.
Регистрируйте новую функцию до разбора спецификации, которая её использует. После регистрации функция доступна всем спецификациям Vega, разобранным позднее.