Referência

Referência da API

O namespace global KatuCharts cria gráficos e gerencia padrões; cada instância de gráfico expõe métodos para atualizar, exportar, inspecionar e descartar.

Global — KatuCharts

Método	Assinatura → retorna	Descrição
`chart`	chart(containerOrId: string \| HTMLElement, options) → Chart	Cria um gráfico no container (id ou nó DOM).
`setOptions`	setOptions(options) → void	Define padrões globais herdados por gráficos posteriores.
`getOptions`	getOptions() → Partial<Options>	Lê os padrões globais atuais.
`use`	use(module) → void	Registra um plugin/módulo com um método <code>install(KC)</code>.
`dateFormat`	dateFormat(format: string, timestamp: number) → string	Formata um timestamp em ms (tokens abaixo).
`numberFormat`	numberFormat(value, decimals, decPoint?, thousandsSep?) → string	Formata um número; padrões '.' e ','.
`color`	color(input: string) → KatuChartsColor	Objeto de cor encadeável: .brighten(n), .setOpacity(a), .toString().
`palettes`	Record<string, string[]>	Mapa de nome de paleta → cores hex.
`getPalette`	getPalette(name: string) → string[]	Cópia de uma paleta nomeada (lança se desconhecida).
`setTheme`	setTheme(name: string) → void	Aplica 'dark' \| 'light' \| 'nordic'.
`SeriesRegistry.registerType`	registerType(name, seriesClass) → void	Registra um tipo de série personalizado.
`SeriesRegistry.getType`	getType(name) → class \| undefined	Procura uma classe de série registrada.

Tokens dateFormat

Token	Saída	Exemplo
`%Y`	Ano com quatro dígitos	2026
`%m / %d`	Mês / dia com preenchimento de zero	03 / 22
`%H / %M / %S`	Horas (24h) / minutos / segundos	14 / 05 / 09
`%B / %A`	Nome completo do mês / dia da semana	Março / Domingo

Paletas e temas

20 paletas integradas: default, tableau10, d3classic, brewer, google, ocean, sunset, earth, forest, berry, corporate, minimal, nordic, darkMode, neon, pastel, soft, classic, tupi, monochrome. 18 temas (9 famílias, cada uma clara e escura) definem um fundo + paleta, por exemplo:

Tema	Fundo	Paleta
`dark`	#1a1f24	monochrome
`light`	#ffffff	monochrome
`nordic`	#eceff4	nordic

import KatuCharts from 'katucharts.js';
import 'katucharts.js/bio'; // modules register their chart types on import

KatuCharts.setTheme('dark');
KatuCharts.setOptions({ colors: KatuCharts.getPalette('sunset') });

const chart = KatuCharts.chart('container', {
  series: [{ type: 'volcano', data: [/* … */] }]
});

Instância — dados e layout

Método	Assinatura → retorna	Descrição
`addSeries`	addSeries(options, redraw=true) → BaseSeries	Anexa uma série; redraw=false para lote.
`get`	get(id) → BaseSeries \| Axis \| undefined	Encontra uma série ou eixo por id.
`update`	update(options, redraw=true) → void	Mescla opções parciais (title, axes, series…).
`addAxis`	addAxis(options, isX=false, redraw=true) → Axis	Adiciona um eixo em tempo de execução.
`redraw`	redraw() → void	Aplica alterações pendentes imediatamente.
`animatedRedraw`	animatedRedraw(duration=500) → void	Redesenha com uma transição.
`reflow`	reflow() → void	Recalcula o layout para o tamanho atual do container.
`setSize`	setSize(width, height) → void	Define dimensões em pixels e redesenha.
`setTitle`	setTitle(titleOptions?, subtitleOptions?) → void	Atualiza title/subtitle; null remove.

Instância — exportação, dados e UI

Método	Assinatura → retorna	Descrição
`getSVG`	getSVG() → string	Markup SVG autossuficiente.
`getCSV`	getCSV() → string	Dados como CSV.
`getTable`	getTable() → string	Dados como uma string HTML <table>.
`getDataRows`	getDataRows() → array[][]	Array 2-D; primeira linha são cabeçalhos.
`exportChart`	exportChart({ type, filename, width, scale })	Baixa PNG/JPEG/SVG/PDF.
`showLoading`	showLoading(text='Loading...') → void	Mostra a sobreposição de carregamento.
`hideLoading`	hideLoading() → void	Oculta a sobreposição de carregamento.
`getSeriesInstances`	getSeriesInstances() → BaseSeries[]	Todas as instâncias de série.
`getXAxes / getYAxes`	→ Axis[]	Instâncias de eixo X / Y (múltiplos eixos retornam muitos).
`destroy`	destroy() → void	Remove do DOM e desvincula listeners — chame antes de remover o container.

chart.showLoading('Fetching data…');
fetch('/api/data').then(r => r.json()).then(data => {
  chart.addSeries({ data });
  chart.hideLoading();
});

chart.exportChart({ type: 'image/svg+xml', filename: 'report', width: 1200 });

// on teardown
chart.destroy();

Renderizador de plot

chart.plotRenderer expõe primitivas de baixo nível para formas personalizadas e anotações na área de plot.

Método	Assinatura	Desenha
`rect`	rect(x, y, width, height, attrs?)	Retângulo
`circle / ellipse`	circle(cx, cy, r, attrs?) / ellipse(cx, cy, rx, ry, attrs?)	Círculo / elipse
`path`	path(d, attrs?)	Caminho SVG a partir de uma string d
`line`	line(x1, y1, x2, y2, attrs?)	Linha reta
`text`	text(str, x, y, attrs?)	Rótulo de texto
`group`	group(attrs?)	Grupo <g> para aninhamento

Helpers de coordenada: plotRenderer.plotArea → { x, y, width, height }; xAxis.toPixels(value) e yAxis.toPixels(value) convertem dados para pixels.

const [xAxis] = chart.getXAxes();
const [yAxis] = chart.getYAxes();
const plot = chart.plotRenderer.plotArea;

const yPx = yAxis.toPixels(6);
chart.plotRenderer.line(plot.x, yPx, plot.x + plot.width, yPx, {
  stroke: '#d62728', strokeWidth: 2, strokeDasharray: '6 3'
});
chart.plotRenderer.text('Target', plot.x + plot.width + 8, yPx + 4, {
  fill: '#d62728', fontSize: 12, fontWeight: 'bold'
});