Referência

Avançado

Estenda KatuCharts com séries personalizadas e módulos, faça streaming de dados ao vivo, lide com conjuntos de dados muito grandes e alcance os blocos de construção internos.

Sistema de plugin

Tipos de série personalizado

Subclassifique BaseSeries, desenhe dentro de render(), e registre a classe com o SeriesRegistry.

import KatuCharts, { BaseSeries, SeriesRegistry } from 'katucharts.js';

class MyCustomSeries extends BaseSeries {
  render() {
    const { plotArea, xAxis, yAxis } = this.context;
    this.context.chartGroup
      .selectAll('circle.custom-point')
      .data(this.processData())
      .join('circle')
      .attr('cx', d => xAxis.getPixelForValue(d.x) + plotArea.x)
      .attr('cy', d => yAxis.getPixelForValue(d.y) + plotArea.y)
      .attr('r', 6)
      .attr('fill', this.context.colors[this.context.colorIndex]);
  }
}

SeriesRegistry.registerType('mycustom', MyCustomSeries);
KatuCharts.chart(container, { series: [{ type: 'mycustom', data: [{ x: 1, y: 10 }] }] });

Registro de módulo

Agrupe múltiplas extensões em um módulo com um método init(KC) e ative-o com KatuCharts.use().

const myModule = {
  init(KC) {
    KC.SeriesRegistry.registerType('mycustom', MyCustomSeries);
    KC.SeriesRegistry.registerType('mycustom2', MyOtherSeries);
  }
};
KatuCharts.use(myModule);

Pontos de extensão BaseSeries

Método	Descrição
`render()`	Método de desenho principal — deve substituir.
`init(context)`	Chamado uma vez na criação; recebe o SeriesContext.
`processData()`	Normaliza dados de opções brutas no formato de renderização.
`animateUpdate(duration)`	Transição personalizada quando os dados mudam.
`getDataExtents()`	Retorna { xMin, xMax, yMin, yMax } para auto-escala do eixo.
`getCategories()`	Retorna string[] quando a série conduz um eixo de categoria.
`setVisible(visible, animated?)`	Mostra/oculta a série.
`destroy()`	Limpa DOM e listeners na remoção.

SeriesContext

Propriedade	Tipo	Descrição
`plotArea`	{ x, y, width, height }	Região desenhável dentro das margens.
`xAxis / yAxis`	AxisInstance	Eixos resolvidos; getPixelForValue(v) mapeia dados → pixels.
`colorIndex / colors`	number / string[]	Índice de paleta para esta série / a paleta completa.
`events`	EventBus	Barramento de eventos compartilhado para componentes.
`chartGroup`	Selection	Seleção SVG do <g> desta série.
`totalSeriesOfType / indexInType`	number	Contagem / posição entre séries do mesmo tipo.
`animate`	boolean	Se animações estão habilitadas.

Streaming em tempo real

Empurre pontos ao vivo em uma série de três fontes. Passe {{ shift: true }} para manter uma janela rolling fixa; a subscrição retornada tem unsubscribe().

import { StreamAdapter, UpdateScheduler } from 'katucharts.js';

const sub = StreamAdapter.fromWebSocket(ws, series, parseMessage, { shift: true });
// StreamAdapter.fromEventSource(es, series, 'tick', parseMessage, { shift })
// StreamAdapter.fromPolling(fetchFn, series, 1000, { shift })
sub.unsubscribe();

// Batch many updates into one redraw
UpdateScheduler.batch(() => {
  series.addPoint(p1, false);
  series.addPoint(p2, false);
});

Grandes conjuntos de dados — decimação

Reduza dezenas de milhares de pontos preservando a forma visual.

import { lttbDecimate, minMaxDecimate } from 'katucharts.js';

// LTTB — keeps the most visually significant point per bucket
const reduced = lttbDecimate(bigDataset, 500);   // 50 000 → 500

// Min/Max — keeps the extremes per bucket (preserves outliers)
const bounds  = minMaxDecimate(bigDataset, 500); // 50 000 → 1 000 (2/bucket)

O gráfico Manhattan auto-muda para canvas acima de ~20k pontos com um overlay SVG interativo; desative animação (chart.animation = false) para séries muito grandes.

Internals exportados

Classes principais

Exportação	Descrição
`Chart`	Controlador principal — ciclo de vida, renderização, atualizações.
`EventBus`	Sistema de eventos pub/sub compartilhado entre componentes.
`SVGRenderer`	Camada de renderização SVG de baixo nível.
`OptionsParser`	Mescla opções do usuário com padrões e valida.
`SeriesRegistry / ModuleRegistry`	Registro de tipo / rastreador de módulos instalados.
`BaseSeries`	Base abstrata que todas as séries estendem.

Componentes e recursos

Exportação	Descrição
`Tooltip / Legend / DataLabels / Crosshair / ExportButton`	Componentes de UI.
`ExportModule`	Exportação programática PNG/SVG/PDF (PDF precisa de jspdf).
`ResponsiveEngine / A11yModule`	Re-renderização ao redimensionar / ARIA + nav de teclado.
`Drilldown / Zoom`	Transições de drill-down / zoom de roda + caixa.
`Navigator / RangeSelector / DataGrouping`	Recursos de gráfico de estoque.

Funções de registro

Função	Registra
`registerCoreSeriesTypes()`	line, area, column, scatter, pie, bar, spline, areaspline, histogram, heatmap, waterfall, funnel, pyramid, bubble, boxplot, errorbar, gauge, solidgauge, polar, windbarb
`registerFinancialSeriesTypes()`	candlestick, ohlc
`registerFlowSeriesTypes()`	sankey, networkgraph, dependencywheel
`registerBioSeriesTypes()`	volcano, manhattan, circos, dotplot, lollipop

Exportações TypeScript

import type {
  KatuChartsOptions, ChartOptions, SeriesOptions, AxisOptions,
  TooltipOptions, LegendOptions, PlotOptions, PointOptions,
  MarkerOptions, DataLabelOptions, SeriesType, PlotArea,
  InternalConfig, ExportingOptions
} from 'katucharts.js';

Utilitários

Exportação	Descrição
`dateFormat(format, timestamp)`	Formatação de data estilo strftime.
`numberFormat(value, decimals, decPoint?, thousandsSep?)`	Formatação de número estilo locale.
`templateFormat — '{path:spec}'`	Substituição de token com uma especificação de formato de número opcional, ex: {point.y:,.0f}.
`parseColor(c)`	→ { r, g, b, a }.
`brighten(c, amount) / setOpacity(c, a)`	Clarecer/escurecer / definir alfa.
`getPalette(name) / setGlobalOptions / getGlobalOptions`	Busca de paleta / padrões globais.

import { parseColor, brighten, setOpacity, getPalette } from 'katucharts.js';

parseColor('#1f77b4');           // { r: 31, g: 119, b: 180, a: 1 }
brighten('#1f77b4', 0.3);        // '#5da5d5'
setOpacity('#1f77b4', 0.4);      // 'rgba(31,119,180,0.4)'

// Template tokens (tooltip / dataLabels / axis formatters)
'{point.name}: {point.y:,.0f}'   // 'Revenue: 8,900'
'{series.name} — {point.percentage:.1f}%'