Компиляция Vega-Lite в Vega

Чтобы преобразовать спецификации Vega-Lite в Vega, используйте встроенный компилятор JavaScript или одну из поставляемых утилит командной строки.

Сначала установите Vega-Lite через npm (npm install vega-lite) или скачайте последний выпуск. Во втором случае также понадобятся Vega и D3.

Использование JavaScript

Чтобы получить скомпилированную спецификацию Vega в программе JavaScript, вызовите функцию vegaLite.compile:

var vgSpec = vegaLite.compile(vlSpec, options).spec;

Необязательный аргумент options — объект с одним или несколькими свойствами:

• config — конфигурация по умолчанию;
• logger — объект для вывода сообщений;
• fieldTitle — функция формирования заголовков полей.

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

Передайте объект конфигурации как свойство config аргумента options функции compile. Свойства config, заданные непосредственно в спецификации Vega-Lite, имеют приоритет над конфигурацией, переданной функции compile.

Собственный вывод сообщений

По умолчанию предупреждения и другие сообщения выводятся в консоль JavaScript методами console.log/warn. Чтобы направить сообщения в другое место, передайте функции компиляции собственный объект logger:

var vgSpec = vegaLite.compile(vlSpec, {logger: logger}).spec;

Он должен реализовывать следующий интерфейс:

interface LoggerInterface {
  level: (_: number) => number | LoggerInterface;
  warn(...args: any[]): LoggerInterface;
  info(...args: any[]): LoggerInterface;
  debug(...args: any[]): LoggerInterface;
}

Собственная функция формирования заголовков полей

Чтобы изменить способ формирования заголовков осей и легенд для определения поля, передайте функцию fieldTitle в аргументе options функции compile:

const vgSpec = vegaLite.compile(vlSpec, {
  fieldTitle: function (fieldDef, config) {
    const fn = fieldDef.aggregate || fieldDef.timeUnit || (fieldDef.bin && 'bin');
    if (fn) {
      return `${fn.toUpperCase()}(${fieldDef.field})`;
    } else {
      return fieldDef.field;
    }
  },
}).spec;

Использование командной строки

В комплект входят утилиты для преобразования спецификаций Vega-Lite в Vega, SVG, PNG и PDF: соответственно vl2vg, vl2svg, vl2png и vl2pdf.

Каждая утилита принимает спецификацию Vega-Lite первым аргументом:

vl2svg spec.vl.json

Данные можно передать и через стандартный поток ввода:

cat spec.vl.json | vl2svg

У команды vl2vg есть необязательный аргумент p, который форматирует полученную спецификацию Vega:

vl2vg spec.vl.json -p

Проще всего запускать команды через npx. Он автоматически использует исполняемые файлы из локального каталога node_modules/.bin или общего кеша, при необходимости устанавливая пакеты для запуска. Заранее устанавливать Vega или Vega-Lite для работы npx не требуется:

npx vl2vg spec.vl.json

Для использования утилит в проекте добавляйте к командам префикс node_modules/.bin/. Можно также установить Vega и Vega-Lite глобально, хотя авторы не рекомендуют этот способ.

Если возникает ошибка Error: CanvasRenderer is missing a valid canvas or context, установите пакет canvas либо vega-cli.

Использование npx

Для запуска исполняемых файлов npm через npx укажите нужные пакеты и выберите команду. Например, справку по vl2png можно открыть так: npx -p vega -p vega-lite vl2png --help.