syncfusion-react-3d-circular-chart

实现 Syncfusion React 3D 圆形图表

全面介绍如何实现 Syncfusion 的 React 3D 圆形图表组件。本技能将指导你创建饼图和圆环图，并使用 3D 可视化、数据标签、图例、工具提示和高级自定义选项。

何时使用此技能

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

• 在 React 应用程序中创建 3D 饼图或圆环图
• 使用圆形图表可视化比例数据
• 以 3D 深度和视觉效果呈现数据
• 为图表添加交互式工具提示和图例
• 使用数据标签自定义图表外观
• 妥善处理空值或 null 数据点
• 将图表导出为各种格式（PNG、JPEG、SVG、PDF）
• 直接从浏览器打印图表
• 实现响应式圆形图表可视化

组件概述

3D 圆形图表组件提供：

• 饼图和圆环图： 带有 3D 深度效果的经典圆形可视化
• 灵活的数据绑定： 轻松将数据源映射到图表系列
• 交互功能： 工具提示、图例和单击事件
• 视觉自定义： 数据标签、颜色和半径配置
• 导出选项： 打印并导出为多种格式
• 空点处理： 智能处理 null/undefined 值
• 响应式设计： 自动适应容器大小

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包依赖项
• 使用 Vite 或 Create React App 设置 React 应用程序
• 将 3D 圆形图表组件添加到项目中
• 导入 CSS 主题
• 使用数据源实现基础饼图系列
• 使用 xName 和 yName 属性映射数据字段
• 运行第一个 3D 圆形图表
• 最小可用示例

饼图和圆环图

📄 阅读： references/pie-donut-charts.md

• 注入 PieSeries3D 模块
• 渲染默认饼图
• 自定义图表半径（默认为容器的 80%）
• 创建不同半径的饼图，并逐个自定义扇区
• 使用 innerRadius 属性实现圆环图
• 从数据源映射文本和填充颜色
• 使用 pointRender 事件自定义单个数据点
• 饼图和圆环图各种形式的完整示例

数据标签

📄 阅读： references/data-labels.md

• 启用数据标签显示
• 注入 CircularChartDataLabel3D 模块
• 智能排列标签，防止重叠
• 将标签放在图表内部或外部
• 使用占位符创建自定义模板
• 设置文本格式并设计标签样式
• 配置连接线
• 自定义数据标签字体

图例

📄 阅读： references/legend.md

• 启用图例显示
• 注入 CircularChartLegend3D 模块
• 设置图例位置（左、右、上、下）
• 对齐选项（居中、远端、近端）
• 反转图例项顺序
• 为多个图例项启用分页
• 自定义形状和标记
• 配置样式和单击行为

工具提示

📄 阅读： references/tooltip.md

• 启用悬停工具提示
• 注入 CircularChartTooltip3D 模块
• 设置自定义工具提示标题
• 使用占位符自定义格式字符串
• 创建工具提示模板
• 显示系列名称和数据点值
• 设置工具提示外观样式
• 基于事件自定义工具提示

空点

📄 阅读： references/empty-points.md

• 了解空点（null/undefined 值）
• 配置 emptyPointSettings 属性
• 模式选项：Gap、Average、Drop、Zero
• Gap 模式：跳过空数据点
• Average 模式：使用计算出的平均值
• Drop 模式：从图表中排除空数据点
• Zero 模式：将空数据点视为零值
• 为空点自定义填充颜色

标题和副标题

📄 阅读： references/title-and-subtitle.md

• 使用 title 属性添加图表标题
• 标题的位置和对齐方式
• 自定义标题样式（字体、颜色、大小）
• 使用 subTitle 属性添加副标题
• 副标题的位置
• 独立设置副标题样式
• 组合使用标题和副标题
• 响应式标题大小

打印和导出

📄 阅读： references/print-and-export.md

• 直接从浏览器打印图表
• 使用带图表 ID 的 print 方法
• 导出为图像格式（JPEG、PNG、SVG）
• 使用 pdfExport 方法导出为 PDF
• 指定导出类型和文件名
• 通过按钮触发打印和导出
• 导出质量和分辨率设置
• 排查导出问题

API 参考

📄 阅读： references/api-reference.md

• 根据 CircularChart3DComponent 的官方 Syncfusion API 文档，汇总组件属性、方法和事件。

快速入门示例

import { CircularChart3DComponent, CircularChart3DSeriesCollectionDirective, CircularChart3DSeriesDirective, PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D, Inject } from '@syncfusion/ej2-react-charts';
import * as React from "react";
import * as ReactDOM from "react-dom";
function App() {
    const circularData = [
        { x: 'Chrome', y: 62.92 },
        { x: 'Internet Explorer', y: 6.12 },
        { x: 'Opera', y: 3.15 },
        { x: 'Edge', y: 5.5 },
        { x: 'Safari', y: 19.97 },
        { x: 'Others', y: 2.34 }
    ];
    return <CircularChart3DComponent id='charts' title='Browser Market Shares in November 2023' tilt={-45} legendSettings={{ visible: true, position: 'Right' }}>
        <Inject services={[PieSeries3D, CircularChartDataLabel3D, CircularChartLegend3D]} />
        <CircularChart3DSeriesCollectionDirective>
            <CircularChart3DSeriesDirective dataSource={circularData} xName='x' yName='y' dataLabel={{ visible: true, position: 'Outside', name: 'x', font: { fontWeight: '600' }, connectorStyle: { length: '40px' } }}>
            </CircularChart3DSeriesDirective>
        </CircularChart3DSeriesCollectionDirective>
    </CircularChart3DComponent>;
}
export default App;
const root = ReactDOM.createRoot(document.getElementById('charts'));
root.render(<App />);

常见模式

创建圆环图

<CircularChart3DSeriesDirective
  dataSource={data}
  xName="category"
  yName="value"
  innerRadius="40%"  // Creates donut effect
  radius="80%"
/>

添加数据标签

import { CircularChartDataLabel3D } from '@syncfusion/ej2-react-charts';

<CircularChart3DComponent>
  <Inject services={[PieSeries3D, CircularChartDataLabel3D]} />
  <CircularChart3DSeries>
    <CircularChart3DSeriesDirective
      dataSource={data}
      xName="x"
      yName="y"
      dataLabel={{ visible: true, position: 'Outside' }}
    />
  </CircularChart3DSeries>
</CircularChart3DComponent>

启用图例和工具提示

import { CircularChartLegend3D, CircularChartTooltip3D } from '@syncfusion/ej2-react-charts';

<CircularChart3DComponent
  legendSettings={{ visible: true, position: 'Bottom' }}
  tooltip={{ enable: true, format: '${point.x}: ${point.y}' }}
>
  <Inject services={[PieSeries3D, CircularChartLegend3D, CircularChartTooltip3D]} />
  {/* Series configuration */}
</CircularChart3DComponent>

处理空数据点

<CircularChart3DSeriesDirective
  dataSource={dataWithNulls}
  xName="category"
  yName="value"
  emptyPointSettings={{ 
    mode: 'Average',  // Options: Gap, Average, Drop, Zero
    fill: '#cccccc'
  }}
/>

关键属性参考

CircularChart3DComponent 属性

• title：图表标题文本
• subTitle：图表副标题文本
• legendSettings：配置图例外观和行为
• tooltip：启用并自定义工具提示
• enableExport：启用导出功能
• width/height：图表尺寸

CircularChart3DSeriesDirective 属性

• dataSource：数据对象数组
• xName：类别/标签的属性名称
• yName：值的属性名称
• radius：图表半径（百分比字符串，例如 "70%"）
• innerRadius：圆环图的内半径（百分比）
• dataLabel：数据标签配置
• emptyPointSettings：处理 null/undefined 值
• pointColorMapping：从数据源映射颜色

模块注入

必须通过 <Inject services={[...]} /> 注入所需模块：

• PieSeries3D：饼图/圆环图核心功能
• CircularChartDataLabel3D：数据标签功能
• CircularChartLegend3D：图例功能
• CircularChartTooltip3D：工具提示功能
• CircularChart3DExport：导出为图像格式
• CircularChart3DPdfExport：PDF 导出功能

常见用例

销售分布仪表板

非常适合展示市场份额、按类别划分的销售额，或不同产品/地区的收入分布。

预算分配

通过清晰的比例表示，直观展示各部门预算、费用类别或成本中心的预算细分。

调查结果

通过直观的圆形可视化展示投票结果、客户反馈分布或人口统计细分。

投资组合构成

通过交互式图表展示投资分配、资产分布或资源分配。

时间分配

使用圆环图表示活动耗时、项目阶段或资源利用情况。

故障排查提示

图表未渲染？

• 确保已安装 @syncfusion/ej2-react-charts 包
• 导入所需的 CSS 主题文件
• 确认数据源是格式正确的数组
• 检查是否已注入所需模块（PieSeries3D）

数据标签重叠？

• 组件会自动排列标签以防止重叠
• 使用 position: 'Outside' 以获得更好的间距
• 考虑减小字体大小或使用模板

无法导出？

• 注入 CircularChart3DExport 或 CircularChart3DPdfExport 模块
• 在图表组件上设置 enableExport: true
• 确保调用了正确的方法（export 或 pdfExport）

颜色显示不正确？

• 使用 pointColorMapping 从数据源映射颜色
• 在数据对象中指定颜色，或使用图表调色板
• 检查 CSS 主题是否已正确导入

---

准备好开始构建了吗？ 从 references/getting-started.md 开始了解安装和基本设置，然后根据需要探索具体功能。