Установка и подключение библиотек

Vega и Vega-Lite распространяются как набор npm-пакетов и подключаются в JavaScript-проектах через стандартную систему управления зависимостями Node.js.

Базовая установка выполняется через npm:

npm install vega
npm install vega-lite

В большинстве практических сценариев дополнительно устанавливается пакет для рендеринга:

npm install vega-embed

Ключевой момент архитектуры: Vega-Lite не рендерит графики напрямую. Он компилируется в спецификацию Vega, которая затем интерпретируется движком Vega.

Подключение в проектах на JavaScript (ES Modules)

Современные сборщики (Vite, Webpack, Rollup) используют ES Modules:

import embed from 'vega-embed';
import vegaLite from 'vega-lite';

Типичная цепочка работы:

  1. Описание визуализации создаётся в формате Vega-Lite JSON
  2. Vega-Lite компилируется в Vega JSON
  3. Vega рендерит сцену в Canvas или SVG

Пример минимальной спецификации:

const spec = {
  data: { values: [
    {category: "A", value: 28},
    {category: "B", value: 55}
  ]},
  mark: "bar",
  encoding: {
    x: {field: "category", type: "nominal"},
    y: {field: "value", type: "quantitative"}
  }
};

Рендеринг через vega-embed:

import embed from 'vega-embed';

embed('#vis', spec);

Подключение через CDN без сборщика

Для быстрых прототипов используется подключение через CDN:

<script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-lite@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>

Рендеринг осуществляется через глобальный объект:

<div id="vis"></div>

<script>
const spec = {
  mark: "line",
  data: { values: [
    {x: 1, y: 3},
    {x: 2, y: 5},
    {x: 3, y: 2}
  ]},
  encoding: {
    x: {field: "x", type: "quantitative"},
    y: {field: "y", type: "quantitative"}
  }
};

vegaEmbed("#vis", spec);
</script>

Подключение в Vite и Webpack-проектах

В сборочных системах важны корректные зависимости и обработка JSON-спецификаций.

Vite

Vite автоматически поддерживает ESM-модули:

import embed from 'vega-embed';
import spec from './chart.json';

embed('#vis', spec);

Webpack

В Webpack иногда требуется настройка JSON-лоадера (в новых версиях встроен):

import embed from 'vega-embed';
import spec from './chart.json';

embed('#vis', spec);

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

Vega-Lite является надстройкой над Vega, поэтому перед рендерингом происходит трансформация:

import vegaLite from 'vega-lite';

const vgSpec = vegaLite.compile(spec).spec;

На выходе получается полноценная Vega-спецификация:

import vega from 'vega';

const view = new vega.View(vega.parse(vgSpec))
  .renderer('canvas')
  .initialize('#vis')
  .run();

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

Node.js применяется для генерации графиков на сервере (PNG, SVG, PDF через дополнительные библиотеки).

Установка:

npm install vega vega-lite canvas

Пример серверного рендеринга:

import vega from 'vega';
import vegaLite from 'vega-lite';
import fs from 'fs';

const spec = {
  mark: "bar",
  data: { values: [
    {a: "X", b: 10},
    {a: "Y", b: 20}
  ]},
  encoding: {
    x: {field: "a", type: "nominal"},
    y: {field: "b", type: "quantitative"}
  }
};

const vgSpec = vegaLite.compile(spec).spec;

const view = new vega.View(vega.parse(vgSpec), {
  renderer: 'none'
});

view.toSVG()
  .then(svg => fs.writeFileSync('chart.svg', svg));

Типизация TypeScript и интеграция

Обе библиотеки предоставляют типы:

npm install --save-dev @types/vega @types/vega-lite

Использование строгой типизации позволяет проверять корректность спецификаций на этапе компиляции:

import { TopLevelSpec } from 'vega-lite';

const spec: TopLevelSpec = {
  mark: "point",
  data: { values: [] },
  encoding: {}
};

Подключение модулей рендеринга

Vega использует разные движки:

  • Canvas (по умолчанию для производительности)
  • SVG (для точности и масштабируемости)
  • WebGL (в расширенных конфигурациях)

Настройка выполняется при создании View:

new vega.View(vega.parse(spec))
  .renderer('svg')
  .initialize('#vis')
  .run();

CDN-архитектура и глобальные зависимости

При подключении через CDN создаются глобальные объекты:

  • vega
  • vegaLite
  • vegaEmbed

Зависимости должны подключаться в строгом порядке:

  1. vega
  2. vega-lite
  3. vega-embed

Нарушение порядка приводит к ошибкам компиляции спецификаций.

Работа с версиями и совместимость

Vega и Vega-Lite развиваются синхронно, но версии не всегда строго совпадают.

Типовая связка:

  • Vega 5.x
  • Vega-Lite 5.x
  • Vega-Embed 6.x

Несовместимость версий приводит к:

  • ошибкам компиляции spec
  • отсутствию рендеринга
  • некорректной интерпретации scale/encoding

Использование в монорепозиториях

В монорепозиториях важно избегать дублирования зависимостей:

npm dedupe

или через pnpm:

pnpm add vega vega-lite

Импорт JSON-спецификаций

Vega-Lite спецификации обычно хранятся как JSON:

{
  "mark": "area",
  "data": { "values": [] },
  "encoding": {}
}

Импорт возможен напрямую:

import spec from './vis.json' assert { type: 'json' };

Интеграция с DOM

Для встраивания в DOM используется контейнер:

<div id="vis"></div>

и функция embed:

vegaEmbed('#vis', spec, {
  actions: false
});

Параметр actions отключает панель экспорта и просмотра спецификации.

Структура зависимостей внутри экосистемы

Архитектура основана на слоях:

  • Vega-Lite: декларативный уровень описания
  • Vega: ядро визуализации
  • Vega-Scales / Signals / Dataflow: вычислительный слой
  • Vega-Embed: интеграция с DOM

Эта структура позволяет разделять описание графика и механизм его отрисовки, обеспечивая переносимость между средами браузера и Node.js.

Оглавление