Конфигурация
Чарт полностью описывается одним объектом 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 фиксируют размер.
| Опция | Тип | По умолчанию | Описание |
|---|---|---|---|
width | number | ширина контейнера | фиксированная ширина, px |
height | number | высота контейнера | фиксированная высота, px |
minWidth | number | 300 | нижняя граница измеренной ширины; 0 — без границы |
minHeight | number | 200 | нижняя граница измеренной высоты; 0 — без границы |
responsive | boolean | true, если не заданы оба width и height | следовать ли за контейнером |
У размера, измеренного по контейнеру, есть пол — 300×200: чарт в контейнере, которому ещё не задали размер, не выходит нечитаемо мелким. Пол именно пол, а не ограничение на контейнер: контейнер шире пола выигрывает, уже — нет, и тогда канвас оказывается внутри контейнера размером больше самого контейнера.
minWidth/minHeight двигают этот пол, 0 — убирает: плотной раскладке нужно именно это — плитка дашборда шириной 195 px, ряд KPI-карточек высотой 140 px, спарклайн в ячейке таблицы. Содержимое чарт подгоняет под ту площадь, что у него есть; лишнее убирается штатными опциями — legend.enabled, title, axes[].label.
Charts.create({ container, data, series, minWidth: 0, minHeight: 0 });Без пола контейнер может не измеряться вовсе — display: none, ещё не открытая вкладка. Чарт говорит об этом один раз в консоль и ждёт: раскладка на 0×0 не строится, а первый размер, который принесёт ResizeObserver, и станет тем, в котором чарт нарисуется. Уже нарисованный чарт, который спрятали, сохраняет раскладку, к которой вернётся.
responsive разделяет два вопроса, на которые раньше разом отвечали width/height: каким быть размеру и кто его считает. responsive: false меряет контейнер один раз и больше не возвращается к этому. responsive: true вместе с 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 | Доступность |