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

Vega можно использовать для интерактивных визуализаций в браузере или для создания статических изображений PNG и SVG на сервере. На этой странице описаны основные способы установки и использования Vega.

Справочник по использованию

• Использование в браузере
  • Подключение JavaScript-библиотеки Vega
  • Использование API представления Vega
  • Использование модуля Vega-Embed
  • Политика безопасности содержимого
• Утилиты командной строки
• Использование на сервере

Использование в браузере

Чтобы использовать Vega на веб-странице, сначала подключите необходимые библиотеки JavaScript. Затем разберите спецификацию Vega и добавьте интерактивную визуализацию с помощью API представления Vega или вспомогательного модуля Vega-Embed.

Попробуйте Vega с Vega-Embed в интернете и опубликуйте собственный график, создав копию нашего примера в Block.

Подключение JavaScript-библиотеки Vega

Для работы с Vega на веб-странице сначала загрузите файлы JavaScript. Самый простой способ — подключить полную сборку Vega.

<head>
  <script src="https://vega.github.io/vega/vega.min.js"></script>
</head>

Загрузка Vega через CDN. В примере выше файл загружается с сайта Vega. В рабочем проекте удобнее раздавать собственную копию или использовать сеть доставки содержимого (CDN). Версии Vega опубликованы на jsDelivr:

<head>
  <script src="https://cdn.jsdelivr.net/npm/vega@6"></script>
</head>

Совместное использование Vega и D3. Полные файлы vega.js и vega.min.js включают все зависимости, в том числе модули D3 и topojson-client. Если вы отдельно используете d3.js на своей странице, можно подключить уменьшенную сборку Vega без дублирующих файлов D3. Сначала загрузите D3, затем vega-core.min.js, чтобы сократить общий размер файлов. Если вы собираетесь загружать данные TopoJSON, также понадобится пакет topojson-client.

<head>
  <script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
  <script src="https://cdn.jsdelivr.net/npm/topojson-client@3"></script>
  <script src="https://cdn.jsdelivr.net/npm/vega@6/build/vega-core.min.js"></script>
</head>

Использование Vega со сборщиком. Если вы применяете сборщик, например Rollup, Vega можно импортировать как модуль.

import * as vega from "vega";

Вернуться к оглавлению

Использование модуля Vega-Embed

Модуль Vega-Embed помогает добавлять на веб-страницу визуализации Vega и Vega-Lite. Он берёт на себя загрузку файла спецификации по URL-адресу и создание представления со стандартными параметрами. Также можно добавить элементы для экспорта изображения и просмотра исходного кода. Подробнее об этом модуле можно узнать в репозитории Vega-Embed.

<head>
  <script src="https://cdn.jsdelivr.net/npm/vega@6"></script>
  <script src="https://cdn.jsdelivr.net/npm/vega-lite@6"></script>
  <script src="https://cdn.jsdelivr.net/npm/vega-embed@7"></script>
</head>
<body>
  <div id="view"></div>
  <script>
    vegaEmbed(
      '#view',
      'https://vega.github.io/vega/examples/bar-chart.vg.json'
    );
  </script>
</body>

Вернуться к оглавлению

Использование API представления Vega

Компонент View получает разобранную спецификацию и параметры настройки, после чего создаёт интерактивный компонент на странице. API представления также позволяет передавать обновления данных, экспортировать статические изображения и обращаться к внутренним данным для отладки. Подробности приведены в документации компонента View.

<head>
  <script src="https://cdn.jsdelivr.net/npm/vega@6"></script>
</head>
<body>
  <div id="view"></div>
  <script type="text/javascript">
    var view;

    fetch('https://vega.github.io/vega/examples/bar-chart.vg.json')
      .then(res => res.json())
      .then(spec => render(spec))
      .catch(err => console.error(err));

    function render(spec) {
      view = new vega.View(vega.parse(spec), {
        renderer:  'canvas',  // способ отрисовки: canvas или svg
        container: '#view',   // родительский контейнер DOM
        hover:     true       // включить обработку наведения
      });
      return view.runAsync();
    }
  </script>
</body>

Визуализация Vega добавляется в родительский элемент-контейнер DOM. Этот элемент — объект DOM или строку с уникальным CSS-селектором — нужно передать при создании View либо в метод initialize. Примечание: при инициализации представления всё существующее содержимое контейнера удаляется.

Вернуться к оглавлению

Vega и политика безопасности содержимого (CSP)

По умолчанию Vega не соответствует стандартной политике безопасности содержимого (Content Security Policy, CSP), поскольку для создания функций из выражений Vega использует конструктор Function. Однако Vega поддерживает альтернативные вычислители выражений, совместимые с CSP. Подробнее читайте в документации по интерпретатору выражений.

Вернуться к оглавлению

Утилиты командной строки

Пакет vega-cli содержит три утилиты командной строки для Node.js — vg2pdf, vg2png и vg2svg. Они создают статические изображения визуализаций в форматах PDF, PNG и SVG соответственно.

• vg2pdf: vg2pdf [options] [input_vega_json_file] [output_pdf_file]
• vg2png: vg2png [options] [input_vega_json_file] [output_png_file]
• vg2svg: vg2svg [options] [input_vega_json_file] [output_svg_file]

Если не указан входной JSON-файл Vega, утилита попробует прочитать спецификацию из стандартного ввода. Если не указан выходной файл, результат в формате PDF, PNG или SVG будет записан в стандартный вывод. Это позволяет передавать его другим программам через конвейер.

Утилиты также принимают следующие необязательные параметры:

• -b, –base — [строка] Базовый каталог для загрузки данных и изображений. Для загрузки из интернета укажите -b http://host/data/. Для локальных файлов используйте -b data/ (относительный путь) или -b file:///dir/data/ (абсолютный путь).
• -h, –header — [флаг] Добавить заголовок XML и DOCTYPE в SVG (только для vg2svg).
• -s, –scale — [число, по умолчанию 1] Коэффициент масштаба разрешения. Например, -s 2 удвоит разрешение выходного изображения. Для PDF и SVG масштабируется пространство координат.
• -seed — [число] Начальное значение генератора случайных чисел для воспроизводимого результата. Внутри Math.random заменяется линейным конгруэнтным генератором.
• -c, –config — [строка] Путь к JSON-файлу или файлу .js, экспортирующему объект конфигурации Vega.
• -f, –format — [строка] Путь к JSON-файлу или файлу .js, экспортирующему локаль числовых форматов.
• -t, –timeFormat — [строка] Путь к JSON-файлу или файлу .js, экспортирующему локаль форматов даты и времени.
• -l, –loglevel — [строка] Уровень сообщений, записываемых в стандартный поток ошибок: error, warn (по умолчанию), info или debug.
• –help — [флаг] Вывести справку по использованию утилиты.

Для работы с утилитами установите npm-пакет vega-cli. Например, команды yarn global add vega-cli и npm install -g vega-cli устанавливают их глобально. При локальной установке команды доступны в каталоге node_modules (./node_modules/bin/vg2png). Утилиты командной строки зависят от пакета node-canvas. Подробнее о Vega и node-canvas сказано ниже.

Все ошибки и сообщения журнала записываются в стандартный поток ошибок (stderr). Чтобы сохранить их в файл, перенаправьте этот поток, например: vg2pdf ...arguments 2> vg2pdf.log.

Примеры

После установки vega-cli в пакете Vega можно выполнять следующие команды.

Сохранить пример столбчатой диаграммы в PNG:

vg2png test/specs-valid/bar.vg.json bar.png

Сохранить пример столбчатой диаграммы в SVG с заголовками XML:

vg2svg -h test/specs-valid/bar.vg.json bar.svg

Создать PDF для примера с дугами, перенаправив стандартный вывод в файл:

vg2pdf test/specs-valid/arc.vg.json > arc.pdf

Создать PNG для примера картограммы, указав базовый каталог для загрузки файлов данных:

vg2png -b test test/specs-valid/choropleth.vg.json > choropleth.png

Создать PNG столбчатой диаграммы с удвоенным разрешением:

vg2png -s 2 test/specs-valid/bar.vg.json bar.png

Вернуться к оглавлению

Использование на сервере с Node.js

Чтобы использовать Vega как компонент более крупного проекта, установите её напрямую (yarn add vega или npm install vega) либо добавьте "vega" в список зависимостей файла package.json. В коде JavaScript для Node.js подключайте Vega через require('vega'). Как и в браузере, на сервере используется API представления Vega. Однако для серверных экземпляров View укажите тип отрисовки none и не передавайте элемент DOM в метод initialize.

Для создания PNG и точного измерения текста при усечении текста в текстовых примитивах установите пакет node-canvas. Пакет vega не требует node-canvas по умолчанию, поэтому при необходимости добавьте его в зависимости своего проекта явно. В отличие от него, vega-cli уже включает node-canvas как обязательную зависимость.

В некоторых системных конфигурациях при установке node-canvas возникают ошибки. Если это произошло, обратитесь к документации node-canvas.

Пример

var vega = require('vega');

// создать представление для заданной JSON-спецификации Vega
var view = new vega.View(vega.parse(spec), {renderer: 'none'});

// создать статическое изображение SVG
view.toSVG()
  .then(function(svg) {
    // обработать строку SVG
  })
  .catch(function(err) { console.error(err); });

// создать статическое изображение PNG
view.toCanvas()
  .then(function(canvas) {
    // обработать экземпляр node-canvas
    // например, создать поток PNG для записи
    var stream = canvas.createPNGStream();
  })
  .catch(function(err) { console.error(err); });

Вернуться к оглавлению