syncfusion-react-charts

实现 Syncfusion React 图表

何时使用此技能

在以下情况下使用此技能：

• 创建和渲染图表（面积图、条形图、柱形图、折线图、散点图等）
• 配置图表坐标轴并自定义其外观
• 绑定本地数据、远程数据（DataManager），或使用 OData/WebAPI/自定义适配器
• 动态添加、删除或替换数据点（addPoint、removePoint、setData）
• 自定义图表外观（颜色、标签、图例、注释）
• 配置数据标签（必须放在 marker.dataLabel 中，而非直接放在系列上）
• 实现用户交互（选择、缩放、工具提示）
• 启用 WebMCP，以便浏览器模型上下文和 AI Agent 检查并操作已渲染的图表
• 添加金融指标和技术分析功能
• 处理无障碍访问和国际化
• 排查图表渲染或数据问题

组件概述

Syncfusion React Chart 是一款功能强大的数据可视化组件，支持 20 多种图表类型，并提供丰富的自定义选项。它专为构建专业仪表板、报表和分析应用而设计，支持缩放、选择和工具提示等交互功能。

主要功能：

• 20 多种图表类型（笛卡尔坐标系、极坐标系、雷达图、饼图、圆环图等）
• 多种坐标轴（类别、数值、日期时间、对数）
• 金融指标和蜡烛图
• 高级交互（缩放、平移、十字准线、工具提示）
• 响应式设计和无障碍访问支持
• 打印和导出功能
• WebMCP 集成，支持自动注册工具、所选工具允许列表、执行控制和 AI Agent 访问

---

文档和导航指南

API 参考

📄 阅读： references/api-reference.md

• 完整的 ChartComponent 属性参考
• 所有方法和事件的文档
• SeriesDirective 属性
• 模型接口（AxisModel、ZoomSettingsModel 等）
• 模块服务（系列类型、功能、指标）
• 官方 API 文档链接

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 创建第一个图表
• CSS 导入和主题配置
• 基本图表示例的渲染
• 软件包结构概述

图表类型

📄 阅读： references/chart-types.md

• 20 多种受支持图表类型的概述
• 各种图表类型的适用场景
• 常见类型（折线图、条形图、柱形图、面积图、散点图）的基本示例
• 特定类型的配置
• 为数据选择合适的图表

坐标轴和自定义

📄 阅读： references/axes-and-customization.md

• 类别、数值、日期时间和对数坐标轴
• 坐标轴标签和格式
• 多坐标轴配置
• 范围和间隔设置
• 坐标轴交叉和定位

系列和数据绑定

📄 阅读： references/series-and-data.md

• 系列配置和属性
• 本地数据绑定模式
• 使用 DataManager 绑定远程数据
• 数据适配器：ODataAdaptor、ODataV4Adaptor、WebApiAdaptor、自定义适配器
• 离线模式和延迟加载
• 通过 addPoint、removePoint、setData 或 React 状态动态更新数据
• 多系列处理
• 数据验证和边缘情况

外观和样式

📄 阅读： references/appearance-and-styling.md

• 图例配置和定位
• 数据标签和格式
• 图表注释
• 渐变和颜色自定义
• 标题、副标题和说明的样式设置

用户交互

📄 阅读： references/user-interaction.md

• 选择和高亮
• 缩放和平移
• 工具提示和十字准线配置
• 同步图表
• 事件处理模式

WebMCP 与 AI Agent 集成

📄 阅读：references/webmcp.md

• 生成完整的 React Chart WebMCP 示例
• 导入并注入 WebMcpChart
• 设置 enableWebMcp={true} 并使用稳定的 ChartComponent ID
• 配置 webMcpSettings.name、tools 和 exposedTo
• 自动注册所有内置工具，或使用经过验证的工具名称允许列表限制注册范围
• 仅将 getWebMcpTools() 用于诊断、测试或直接执行
• 使用 beforeWebMcpToolExecute 进行验证、取消或控制确认
• 保留 WebMCP 参考示例中定义的模块注入列表
• 不要生成手动注册按钮，也不要调用 registerWebMcpTools()
• 根据经过验证的内置工具列表验证生成的工具名称

高级功能

📄 阅读：references/advanced-features.md

• 金融图表类型（蜡烛图、HLOC、最高价-最低价图）
• 技术指标（移动平均线、趋势线等）
• 多个窗格和指标窗格
• 无障碍功能（符合 WCAG 标准、键盘导航）
• 国际化和本地化

---

快速入门示例

import { ChartComponent, SeriesCollectionDirective, SeriesDirective, Inject, LineSeries, Category, Legend, Tooltip } from '@syncfusion/ej2-react-charts';

export default function BasicChart() {
  const data = [
    { x: 'Jan', y: 35 },
    { x: 'Feb', y: 28 },
    { x: 'Mar', y: 34 },
    { x: 'Apr', y: 32 },
    { x: 'May', y: 40 }
  ];

  return (
    <ChartComponent id='charts'>
      <Inject services={[LineSeries, Category, Legend, Tooltip]} />
      <SeriesCollectionDirective>
        <SeriesDirective dataSource={data} xName='x' yName='y' type='Line' />
      </SeriesCollectionDirective>
    </ChartComponent>
  );
}

---

常见模式

模式 1：多系列图表

显示共享相同坐标轴的多个数据集时，在 SeriesCollectionDirective 中添加多个 SeriesDirective 组件：

<SeriesCollectionDirective>
  <SeriesDirective dataSource={salesData} xName='month' yName='revenue' type='Column' />
  <SeriesDirective dataSource={profitData} xName='month' yName='profit' type='Column' />
</SeriesCollectionDirective>

模式 2：动态更新数据

根据使用场景选择以下三种方法：

a) React 状态（简单重新渲染）：

const [data, setData] = useState(initialData);

const handleDataUpdate = () => {
  setData(prev => [...prev, { x: 'Jun', y: 45 }]);
};

<SeriesDirective dataSource={data} xName='x' yName='y' type='Line' />

b) addPoint / removePoint / setData（命令式操作，带动画）：

const chartRef = useRef(null);

// Add a point
chartRef.current.series[0].addPoint({ x: 'Jun', y: 45 }, 300);

// Remove first point
chartRef.current.series[0].removePoint(0, 300);

// Replace all data
chartRef.current.series[0].setData(newDataArray, 500);

<ChartComponent ref={chartRef} ...>
  <SeriesDirective dataSource={data} xName='x' yName='y' type='Line' />
</ChartComponent>

模式 3：远程数据绑定

使用 DataManager 和适配器，从 REST API 或 OData 服务绑定数据：

import { DataManager, Query, WebApiAdaptor } from '@syncfusion/ej2-data';

const dataManager = new DataManager({
  url: 'your data source URL link',
  adaptor: new WebApiAdaptor()
});

<SeriesDirective dataSource={dataManager} xName='CustomerID' yName='Freight' type='Column' query={new Query()} />

其他适配器：ODataAdaptor（OData v3）、ODataV4Adaptor（OData v4），以及通过扩展 ODataAdaptor 创建的自定义适配器。

模式 4：数据标签（位于标记内）

数据标签必须放置在 marker.dataLabel 中，而不能直接放在系列上。注入 DataLabel 服务：

<Inject services={[LineSeries, Category, DataLabel]} />

<SeriesDirective
  dataSource={data}
  xName='x'
  yName='y'
  type='Line'
  marker={{
    visible: true,
    dataLabel: { visible: true, position: 'Top' }
  }}
/>

模式 5：自定义工具提示

使用格式化的工具提示模板提升用户体验：

<ChartComponent tooltip={{ enable: true, template: '<div>${point.x}: ${point.y}</div>' }}>

模式 6：响应式设计

使用容器样式使图表具有响应性：

<ChartComponent id='charts' width='100%' height='400px'>
  {/* chart content */}
</ChartComponent>

---

关键属性参考

ChartComponent

属性	类型	用途	使用场景
id	string	唯一标识符	每个图表都必须设置
width	string	图表宽度（px 或 %）	控制布局尺寸
height	string	图表高度	设置明确的尺寸
title	string	图表标题	显示主标题
tooltip	object	工具提示配置	交互式检查数据
primaryXAxis	object	主 X 轴配置	定义水平轴
primaryYAxis	object	主 Y 轴配置	定义垂直轴

SeriesDirective

属性	类型	用途	使用场景
dataSource	array | DataManager	数据源	绑定本地数组或远程 DataManager
xName	string	X 轴属性	将数据字段映射到 X 轴
yName	string	Y 轴属性	将数据字段映射到 Y 轴
type	string	图表类型	选择可视化类型
fill	string	系列颜色	自定义系列颜色
marker	object	标记和数据标签配置	显示数据点标记和/或数据标签（marker.dataLabel）
name	string	系列名称	在图例中显示
query	Query	DataManager 查询	筛选、排序或分页远程数据

---

常见用例

1. 销售仪表板：结合使用收入柱形图和趋势折线图
2. 时间序列分析：对时间数据使用日期时间轴和折线图
3. 对比分析：使用多系列柱形图比较不同类别
4. 财务分析：使用带移动平均指标的蜡烛图
5. 分布分析：使用直方图或箱线图展示统计数据
6. 实时监控：使用 addPoint/removePoint 配合平滑动画处理实时数据流
7. REST API 远程数据：将 DataManager 与 WebApiAdaptor 或 ODataAdaptor 直接绑定到系列
8. 服务端 OData：将 ODataV4Adaptor 与 Query 搭配使用，在服务端进行筛选和分页

---

后续步骤

选择符合当前需求的参考资料：

• 需要了解 API 详情？ → API 参考
• 刚开始使用？ → 入门指南
• 选择图表类型？ → 图表类型
• 配置坐标轴？ → 坐标轴与自定义
• 绑定数据？ → 系列与数据
• 设置外观样式？ → 外观与样式
• 添加交互？ → 用户交互
• 了解高级功能？ → 高级功能
• 添加 WebMCP 或 AI Agent 访问？ → WebMCP

外部资源

• 官方 API 文档： https://ej2.syncfusion.com/react/documentation/api/chart/
• 在线演示： https://ej2.syncfusion.com/react/demos/
• GitHub 仓库： https://github.com/syncfusion/ej2-react-ui-components