以下教程将系统地介绍 Ant Design Charts 的用法，涵盖安装、引入、通用配置项、常用图表组件及它们的核心 API，每个 API 均附上详细示例代码，帮助您快速上手并深入掌握。
一、安装
# 使用 npm
npm install @ant-design/charts --save# 或使用 pnpm（文档示例）
pnpm install @ant-design/charts # 或者 @ant-design/plots 子包安装 :contentReference[oaicite:0]{index=0}
- 安装完成后，所有图表组件均可从
@ant-design/charts中按需导入。
二、引入与基础用法
import React from 'react';
import { Line } from '@ant-design/charts';const Demo: React.FC = () => {const data = [{ time: '2020-01-01', value: 30 },{ time: '2020-01-02', value: 50 },{ time: '2020-01-03', value: 45 },// …];const config = {data,xField: 'time',yField: 'value',smooth: true,};return <Line {...config} />;
};
- 上例中，
data为图表的数据源；xField/yField指定横、纵坐标对应的数据字段。([umijs.org][1])
三、通用配置项（所有组件均支持） ([ant-design-charts-next.antgroup.com][2])
| 属性 | 类型 | 说明 |
|---|---|---|
data | object[] | 数据源 |
xField | string | X 轴字段 |
yField | string | Y 轴字段 |
seriesField | string | 分组字段，用于多系列图 |
colorField | string | 着色字段 |
height | number | 图表高度（px） |
width | number | 图表宽度（px） |
autoFit | boolean | 是否自适应容器宽度 |
padding | number[]|string | 内边距，例如 [16, 16, 32, 16] 或 'auto' |
meta | Record<string,object> | 用于字段别名、格式化、刻度等设置 |
xAxis/yAxis | object | 轴配置，可详见下例 |
legend | object|false | 图例配置或隐藏 |
tooltip | object|false | 提示框配置或隐藏 |
label | object|boolean | 图形标签配置或关闭 |
interactions | Array<object> | 交互行为列表 |
annotations | Array<object> | 注解列表 |
state | object | 状态样式，如 hover/selected |
animation | object|boolean | 动画配置或关闭 |
theme | string|object | 主题名称或自定义主题 |
四、常用图表及核心 API
4.1 曲线图（Line）
import { Line } from '@ant-design/charts';const config = {data,xField: 'time',yField: 'value',seriesField: 'category', // 多系列时使用smooth: true, // 平滑曲线point: { // 数据点size: 4,shape: 'circle',},xAxis: {tickCount: 5,title: { text: '日期' },},yAxis: {label: { formatter: v => `${v} 万` },},tooltip: {shared: true,showCrosshairs: true,},
};
return <Line {...config} />;
4.2 柱状图（Column / Bar）
import { Column } from '@ant-design/charts';const config = {data,xField: 'type',yField: 'value',seriesField: 'category', // 分组柱状isStack: false, // 关闭堆叠dodgePadding: 2, // 分组间距color: ({ category }) => category === 'A' ? '#5B8FF9' : '#61DDAA',legend: false, // 隐藏图例xAxis: { label: { autoRotate: false } },
};
return <Column {...config} />;
4.3 饼图（Pie）
import { Pie } from '@ant-design/charts';const config = {appendPadding: 10,data,angleField: 'value',colorField: 'type',radius: 0.8,label: {type: 'inner',offset: '-30%',content: '{percentage}',style: { fontSize: 14, textAlign: 'center' },},interactions: [{ type: 'element-active' }],
};
return <Pie {...config} />;
4.4 区域图（Area）
import { Area } from '@ant-design/charts';const config = {data,xField: 'time',yField: 'value',seriesField: 'category',smooth: true,areaStyle: { opacity: 0.6 },legend: { position: 'top-right' },
};
return <Area {...config} />;
4.5 散点图（Scatter）
import { Scatter } from '@ant-design/charts';const config = {data,xField: 'sepalLength',yField: 'sepalWidth',colorField: 'species',size: 5,shape: 'circle',tooltip: { showMarkers: false },state: {active: { style: { lineWidth: 3 } },},
};
return <Scatter {...config} />;
五、动态更新数据
React 中直接通过状态改变 data 即可触发图表更新，无需手动调用 API：
const Demo = () => {const [data, setData] = useState(initialData);useEffect(() => {setTimeout(() => {setData(newData); // 图表自动重绘}, 3000);}, []);return <Line {...{ data, xField:'x', yField:'y' }} />;
};
六、高级功能
6.1 交互（Interactions）
interactions: [{ type: 'brush' }, // 框选{ type: 'zoom-canvas' }, // 缩放{ type: 'element-highlight' }, // 悬停高亮
];
6.2 注解（Annotations）
annotations: [{type: 'text',position: ['2020-01-02', 50],content: '峰值',style: { fill: 'red', fontSize: 12 },},{type: 'line',start: ['min', 40],end: ['max', 40],style: { stroke: '#aaa', lineDash: [4,4] },},
];
6.3 自定义主题
import { registerTheme } from '@ant-design/charts';registerTheme('my-theme', {colors10: ['#5B8FF9', '#61DDAA', …],styleSheet: { brandColor: '#5B8FF9' },
});const config = { theme: 'my-theme', data, xField:'x', yField:'y' };
return <Line {...config} />;
七、小结
- 安装与引入：
@ant-design/charts，按需导入 React 组件。 - 通用配置：
data、xField/yField、seriesField、colorField、meta、tooltip、legend、interactions、annotations、state、animation、theme。 - 常用图表：
Line、Column、Pie、Area、Scatter等，配置方式高度一致。 - 动态更新：直接通过 React state 更改
data即可。 - 高级扩展：交互、注解、自定义主题满足各种可视化需求。
