Конфигурация

Чарт полностью описывается одним объектом ChartOptions — он сериализуем, типобезопасен и одинаково работает в Charts.create и chart.update.

Минимальный рабочий пример:

import { Charts } from 'grafit-charts';

const chart = Charts.create({
  container: document.getElementById('app')!, // куда рендерить
  data: [
    { month: 'Янв', plan: 120, fact: 134 },
    { month: 'Фев', plan: 125, fact: 118 },
  ],
  series: [
    { type: 'bar', xField: 'month', yField: 'plan', name: 'План' },
    { type: 'line', xField: 'month', yField: 'fact', name: 'Факт' },
  ],
});

Этого достаточно: оси, легенда, тултипы, подсветка и анимация входа включены по умолчанию.

Данные и серии

data — массив плоских объектов. Серии не содержат данных — они ссылаются на поля через xField/yField (у специализированных серий свои поля: angleField, sizeField, openField…).

series — discriminated union по полю type: после type: 'bar' TypeScript подсказывает только опции бара и не даст передать чужие. Все 27 типов серий перечислены в разделе «Серии», их общие опции — на странице Общие опции серий.

Оси

Если axes не заданы, виджет создаёт их сам: category снизу + number слева (для горизонтальных баров — наоборот; scatter/histogram просят числовую X-ось; heatmap — категориальные без линий и сетки). Явный блок axes нужен, когда требуется второй тип оси, формат подписей, crossLines и т.п. — см. Оси.

axes: [
  { type: 'time', position: 'bottom', label: { format: '%d %b' } },
  { type: 'number', position: 'left', nice: true },
],

Вторая ось значений на противоположной стороне получает свою шкалу; keys на каждой оси говорит, какие серии она несёт — см. Две оси значений.

У полярного графика — радар, роза, радиальные столбцы — осей не список, а две, поэтому axes он читает парой: angle — категории по ободу, radius — кольца значений.

axes: {
  angle: { title: { text: 'Месяц' } },
  radius: { min: 0, max: 60, ringCount: 3 },
},

См. Полярные оси.

Размер

Без width/height чарт следует за контейнером через ResizeObserver — задайте контейнеру размеры CSS-ом. Числа width/height фиксируют размер.

Заголовки, поля, фон

Опция	Тип	По умолчанию	Описание
title.text	string	—	заголовок чарта
title.textAlign	'left' | 'center' | 'right'	'center'	горизонтальное выравнивание
title.fontSize	Pixels	17	размер шрифта заголовка
title.color	ColorValue	foreground	цвет
title.position	'top' | 'bottom'	'top'	над или под областью построения
title.padding	PaddingValue	8 под заголовком	отступы вокруг текста заголовка; по умолчанию только со стороны графика
title.wrap	boolean	true	переносить длинный текст на несколько строк
subtitle.text	string	—	подзаголовок (приглушённый, те же опции)
subtitle.padding	PaddingValue	8 под подзаголовком	отступы вокруг текста подзаголовка
padding	PaddingValue	{ top: 12, right: 20, bottom: 12, left: 20 }	внешние поля чарта: 12, [12, 20], [12, 20, 12, 20] или { top, right, bottom, left }
background.fill	ColorValue	фон темы	заливка подложки
background.visible	boolean	true	рисовать ли фон

Все опции заголовков с живыми примерами: Заголовок и подзаголовок.

Оверлеи и загрузка

Опция	Тип	По умолчанию	Описание
loading	boolean	false	показать оверлей «Загрузка данных…»
overlays.loading.text	string	из locale	текст оверлея загрузки
overlays.noData.text	string	из locale	текст при пустых data
overlays.error.text	string	из locale	текст, когда рисовать нечего

Серия, которой достались шкалы, на которых её знаки не построить — столбцы против оси значений из категорий, ось time со значениями, которые не разбираются в даты, — не рисуется, но и не роняет чарт: остальное рисуется как обычно, причина один раз печатается в консоль, а оверлей error появляется, только если не нарисовалось вообще ничего. Рендер вызывается из тика анимации и из ResizeObserver, где исключение стало бы unhandled-ошибкой на каждом кадре, — поэтому он не бросает.

Конвенции

• *Field / *Name — пары «ключ данных / отображаемое имя»: *Field указывает на поле в data, *Name показывается в легенде и тултипе.
• { enabled } — каждый опциональный блок (legend, tooltip, axis.label, series.marker, …) включается/выключается этим флагом; блок без enabled: false включён.
• format / formatter — формат значений строкой (',.2f', '.0%', '%d %b') или функцией; функции — изолированные листья, остальной объект сериализуем в JSON.
• Мутации переданного объекта не отслеживаются — обновляйте чарт методами.

Обновление и методы инстанса

await chart.updateDelta({ theme: 'dark' }); // точечное изменение
await chart.update(buildOptions(newData)); // полная замена

Метод	Описание
update(options)	полная замена options; Promise резолвится после рендера
updateDelta(patch)	глубокий merge: объекты сливаются, массивы заменяются целиком
getOptions()	текущие options
getState() / setState(state)	зум и скрытые серии — см. Состояние
waitForUpdate()	дождаться рендера (и догрузки веб-шрифтов)
showTooltip / clickNode / setSelection / zoomTo / …	управление взаимодействиями из кода — см. Программное управление
getImageDataURL(opts?)	PNG/JPEG как data-URL
download(opts?)	скачать изображение ({ fileName?, fileFormat? })
destroy()	освободить DOM и подписки

Все корневые блоки

Блок	Что делает	Подробнее
container, data, series, axes	основа чарта	выше на этой странице
width, height	фиксированный размер	Размер
title, subtitle	заголовки	Заголовки
padding, background	поля и фон	Заголовки
loading, overlays	оверлеи	Оверлеи
theme	имя темы или объект	Темы
fonts	перерисовка после загрузки шрифта	Темы
legend	легенда	Легенда
gradientLegend	цветовая шкала colorField-серий	Heatmap
tooltip	тултипы (режимы, позиция, захват)	Тултип
highlight	подсветка и приглушение при ховере	Тултип
crosshair	перекрестие	Crosshair
zoom, navigator	зум и полоса диапазона	Zoom
sync	синхронизация нескольких чартов	Состояние
selection	выбор данных	Выделение данных
listeners	события чарта	События
annotations	линии/диапазоны/текст на чарте	Аннотации
animation	вход и обновления	Состояние
initialState	стартовый зум/скрытые серии	Состояние
contextMenu	меню по правому клику	Состояние
locale	строки UI	Доступность