Функция vegaEmbed является центральной точкой интеграции
спецификаций Vega и Vega-Lite в веб-приложения на JavaScript. Она
принимает JSON-описание визуализации и преобразует его в интерактивный
график внутри DOM-элемента, управляя рендерингом, стилями и набором
встроенных действий пользователя. Конфигурация через параметры
actions, renderer и theme
определяет поведение интерфейса, производительность и визуальную
согласованность графиков.
Вызов vegaEmbed обычно имеет следующую форму:
vegaEmbed('#vis', spec, options)где:
#vis — DOM-элемент или селектор контейнера;spec — спецификация Vega или Vega-Lite;options — объект конфигурации, содержащий параметры
рендера и поведения.Именно options определяет ключевые аспекты
взаимодействия с визуализацией, включая:
renderer);theme);actions).Эти параметры не влияют на саму структуру данных или описание графика, но существенно изменяют способ его отображения и пользовательский опыт.
Параметр renderer определяет технологию, используемую
для генерации графической сцены. Vega поддерживает два основных режима:
canvas и svg.
vegaEmbed('#vis', spec, {
renderer: 'canvas'
});Canvas использует HTML5 <canvas> и рисует графику
в виде растрового изображения.
Особенности:
Canvas предпочтителен в случаях:
Недостаток заключается в невозможности прямого доступа к отдельным элементам графика через DOM, что ограничивает сложные сценарии кастомизации.
vegaEmbed('#vis', spec, {
renderer: 'svg'
});SVG-режим создает каждый графический элемент как отдельный узел DOM.
Особенности:
SVG используется, когда:
Недостаток SVG проявляется при росте количества элементов: DOM становится перегруженным, а производительность падает.
| Критерий | Canvas | SVG |
|---|---|---|
| Производительность | Высокая | Средняя/низкая |
| Интерактивность | Ограниченная | Полная |
| Масштабируемость | Очень высокая | Ограниченная |
| Стилизация | Через пересчет | Через CSS |
Параметр theme управляет внешним видом визуализации,
включая цветовые схемы, типографику и базовые стилистические настройки.
Vega предоставляет несколько встроенных тем, а также возможность
подключения пользовательских.
vegaEmbed('#vis', spec, {
theme: 'dark'
});Наиболее распространенные встроенные темы:
default — базовая светлая тема;dark — темная тема с приглушенными цветами;quartz, excel, ggplot2 —
стили, имитирующие популярные графические системы.Каждая тема представляет собой набор переопределений конфигурации Vega, влияющих на:
Тема применяется на уровне конфигурации Vega перед компиляцией спецификации. Это означает, что итоговая визуализация уже включает все переопределенные параметры.
Упрощенно процесс выглядит следующим образом:
Темы могут быть определены как JavaScript-объекты:
const customTheme = {
background: '#1e1e1e',
axis: {
labelColor: '#cccccc',
titleColor: '#ffffff',
gridColor: '#333333'
},
style: {
'guide-label': {
fontSize: 12
}
}
};
vegaEmbed('#vis', spec, {
theme: customTheme
});Пользовательские темы позволяют стандартизировать визуальный стиль в рамках одного продукта или дизайн-системы.
Vega-Lite использует концепцию компиляции в Vega. При этом тема применяется после трансляции, но до рендера. Это обеспечивает:
Параметр actions отвечает за отображение и поведение
встроенного UI-блока действий Vega, который обычно появляется в правом
верхнем углу визуализации. Этот блок предоставляет инструменты экспорта
и инспекции.
vegaEmbed('#vis', spec, {
actions: true
});vegaEmbed('#vis', spec, {
actions: false
});При actions: false панель полностью скрывается, включая
все элементы управления.
vegaEmbed('#vis', spec, {
actions: {
export: true,
source: false,
compiled: true,
editor: true
}
});Параметр может быть не только булевым значением, но и объектом, позволяющим тонко управлять функциональностью.
actions: {
export: true
}Отвечает за возможность сохранения визуализации в различных форматах:
Экспорт реализуется через рендеринг текущего состояния сцены и сериализацию графического слоя.
actions: {
source: true
}Открывает JSON-представление исходной Vega или Vega-Lite спецификации.
Функционально это:
При включении создается модальное окно с форматированным JSON.
actions: {
compiled: true
}Vega-Lite спецификация перед рендерингом преобразуется в
низкоуровневую Vega-схему. Параметр compiled позволяет
просматривать этот промежуточный результат.
Это важно для:
actions: {
editor: true
}Добавляет ссылку на открытие спецификации в внешнем редакторе Vega Editor.
Функционально это обеспечивает:
vegaEmbed('#vis', spec, {
actions: {
export: true,
source: true,
compiled: false,
editor: false
}
});Такое управление позволяет создавать строго контролируемые интерфейсы, где, например, пользователю доступен только экспорт, но скрыты внутренние представления.
Хотя параметры renderer, theme и
actions относятся к разным уровням системы, их
взаимодействие формирует итоговое поведение визуализации.
source и compiled, так как DOM-структура
соответствует визуальным элементам.source отражает не тему, а спецификацию до
применения визуального слоя.compiled может содержать уже инкорпорированные
параметры темы.vegaEmbed('#vis', spec, {
renderer: 'canvas',
theme: 'dark',
actions: false
});vegaEmbed('#vis', spec, {
renderer: 'svg',
theme: 'default',
actions: {
export: true,
source: true,
compiled: true,
editor: false
}
});vegaEmbed('#vis', spec, {
renderer: 'canvas',
theme: customTheme,
actions: {
export: false,
source: false,
compiled: false,
editor: false
}
});Если renderer, theme или
actions не указаны явно, используются значения по
умолчанию:
renderer: зависит от окружения, чаще
canvas;theme: default;actions: true.Это обеспечивает предсказуемое поведение без дополнительной конфигурации, но ограничивает контроль над визуальным и интерактивным слоем.