参考

高级

使用自定义series和模块扩展KatuCharts，流传输实时数据，处理非常大的数据集，并访问内部构建块。

插件系统

自定义series类型

继承BaseSeries，在render()内绘制，并通过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 }] }] });

模块注册

使用init(KC)方法将多个扩展捆绑到模块中，并通过KatuCharts.use()激活它。

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

BaseSeries扩展点

方法	描述
`render()`	主绘制方法——必须覆盖。
`init(context)`	在创建时调用一次；接收SeriesContext。
`processData()`	将原始选项数据规范化为渲染格式。
`animateUpdate(duration)`	数据更改时的自定义过渡。
`getDataExtents()`	返回{ xMin, xMax, yMin, yMax }用于轴自动缩放。
`getCategories()`	series驱动分类轴时返回string[]。
`setVisible(visible, animated?)`	显示/隐藏series。
`destroy()`	在移除时清理DOM和监听器。

SeriesContext

属性	类型	描述
`plotArea`	{ x, y, width, height }	边距内的可绘制区域。
`xAxis / yAxis`	AxisInstance	已解析的轴；getPixelForValue(v)将数据映射到像素。
`colorIndex / colors`	number / string[]	此series的调色板索引 / 完整调色板。
`events`	EventBus	组件间共享的事件总线。
`chartGroup`	Selection	此series的<g>的SVG选择。
`totalSeriesOfType / indexInType`	number	在相同类型series中的计数 / 位置。
`animate`	boolean	是否启用动画。

实时流传输

从三个源将实时点推入series。传递{{ shift: true }}保持固定滚动窗口；返回的订阅有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);
});

大数据集——数据抽取

在保留视觉形状的同时减少数万个点。

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)

曼哈顿图在~20k个点以上自动切换到canvas，并配有交互式SVG覆盖；对于非常大的series禁用动画（chart.animation = false）。

导出的内部

核心类

导出	描述
`Chart`	主控制器——生命周期、渲染、更新。
`EventBus`	跨组件共享的Pub/sub事件系统。
`SVGRenderer`	低级SVG渲染层。
`OptionsParser`	合并用户选项与默认值并验证。
`SeriesRegistry / ModuleRegistry`	类型注册表 / 已安装模块跟踪器。
`BaseSeries`	所有series继承的抽象基类。

组件和特性

导出	描述
`Tooltip / Legend / DataLabels / Crosshair / ExportButton`	UI组件。
`ExportModule`	编程式PNG/SVG/PDF导出（PDF需要jspdf）。
`ResponsiveEngine / A11yModule`	调整大小时重新渲染 / ARIA + 键盘导航。
`Drilldown / Zoom`	钻取过渡 / 鼠标滚轮 + 框缩放。
`Navigator / RangeSelector / DataGrouping`	股票图表功能。

注册函数

函数	注册
`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

TypeScript导出

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

实用程序

导出	描述
`dateFormat(format, timestamp)`	strftime风格日期格式化。
`numberFormat(value, decimals, decPoint?, thousandsSep?)`	区域设置风格数字格式化。
`templateFormat — '{path:spec}'`	令牌替换具有可选数字格式规范，例如{point.y:,.0f}。
`parseColor(c)`	→{ r, g, b, a }。
`brighten(c, amount) / setOpacity(c, a)`	变亮/变暗 / 设置透明度。
`getPalette(name) / setGlobalOptions / getGlobalOptions`	调色板查找 / 全局默认值。

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}%'