参考

API参考

全局KatuCharts命名空间创建图表并管理默认值；每个图表实例公开方法来更新、导出、检查和销毁。

全局——KatuCharts

方法	签名 → 返回值	描述
`chart`	chart(containerOrId: string \| HTMLElement, options) → Chart	在容器中创建图表（id或DOM节点）。
`setOptions`	setOptions(options) → void	设置由后续图表继承的全局默认值。
`getOptions`	getOptions() → Partial<Options>	读取当前全局默认值。
`use`	use(module) → void	注册具有install(KC)方法的插件/模块。
`dateFormat`	dateFormat(format: string, timestamp: number) → string	格式化ms时间戳（令牌见下）。
`numberFormat`	numberFormat(value, decimals, decPoint?, thousandsSep?) → string	格式化数字；默认使用'.'和','。
`color`	color(input: string) → KatuChartsColor	可链式颜色对象：.brighten(n)、.setOpacity(a)、.toString()。
`palettes`	Record<string, string[]>	调色板名称 → 十六进制颜色的映射。
`getPalette`	getPalette(name: string) → string[]	指定调色板的副本（未知时抛出异常）。
`setTheme`	setTheme(name: string) → void	应用'dark'\|'light'\|'nordic'。
`SeriesRegistry.registerType`	registerType(name, seriesClass) → void	注册自定义series类型。
`SeriesRegistry.getType`	getType(name) → class \| undefined	查找已注册的series类。

dateFormat令牌

令牌	输出	示例
`%Y`	四位数年份	2026
`%m / %d`	零填充月/日	03 / 22
`%H / %M / %S`	小时（24h）/ 分钟 / 秒	14 / 05 / 09
`%B / %A`	完整月名 / 工作日名	March / Sunday

调色板和主题

20个内置调色板：default, tableau10, d3classic, brewer, google, ocean, sunset, earth, forest, berry, corporate, minimal, nordic, darkMode, neon, pastel, soft, classic, tupi, monochrome。18种主题（9个系列，各有浅色和深色）设置背景+调色板，例如：

主题	背景	调色板
`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: [/* … */] }]
});

实例——数据和布局

方法	签名 → 返回值	描述
`addSeries`	addSeries(options, redraw=true) → BaseSeries	追加一条series；redraw=false可批量操作。
`get`	get(id) → BaseSeries \| Axis \| undefined	通过id查找series或轴。
`update`	update(options, redraw=true) → void	合并部分选项（title、axes、series…）。
`addAxis`	addAxis(options, isX=false, redraw=true) → Axis	在运行时添加轴。
`redraw`	redraw() → void	立即应用待决的更改。
`animatedRedraw`	animatedRedraw(duration=500) → void	使用过渡重绘。
`reflow`	reflow() → void	根据当前容器尺寸重新计算布局。
`setSize`	setSize(width, height) → void	设置像素尺寸并重绘。
`setTitle`	setTitle(titleOptions?, subtitleOptions?) → void	更新标题/副标题；null移除。

实例——导出、数据和UI

方法	签名 → 返回值	描述
`getSVG`	getSVG() → string	独立SVG标记。
`getCSV`	getCSV() → string	CSV格式的数据。
`getTable`	getTable() → string	HTML <table> 字符串格式的数据。
`getDataRows`	getDataRows() → array[][]	二维数组；首行是标头。
`exportChart`	exportChart({ type, filename, width, scale })	下载PNG/JPEG/SVG/PDF。
`showLoading`	showLoading(text='Loading...') → void	显示加载覆盖层。
`hideLoading`	hideLoading() → void	隐藏加载覆盖层。
`getSeriesInstances`	getSeriesInstances() → BaseSeries[]	所有series实例。
`getXAxes / getYAxes`	→ Axis[]	X / Y轴实例（多轴返回多个）。
`destroy`	destroy() → void	从DOM移除并解绑监听器——在移除容器前调用。

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();

绘制渲染器

chart.plotRenderer 公开低级原始元素用于在绘制区域中自定义形状和注释。

方法	签名	绘制
`rect`	rect(x, y, width, height, attrs?)	矩形
`circle / ellipse`	circle(cx, cy, r, attrs?) / ellipse(cx, cy, rx, ry, attrs?)	圆形 / 椭圆
`path`	path(d, attrs?)	来自d字符串的SVG路径
`line`	line(x1, y1, x2, y2, attrs?)	直线
`text`	text(str, x, y, attrs?)	文本标签
`group`	group(attrs?)	<g>嵌套组

坐标助手：plotRenderer.plotArea → { x, y, width, height }；xAxis.toPixels(value)和yAxis.toPixels(value)将数据转换为像素。

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'
});