syncfusion-react-3d-chart

Syncfusion React 3D Chart

这是一份全面的指南，介绍如何在 React 应用中实现和自定义 Syncfusion 的 3D Chart 组件。借助本指南，你可以创建包含柱形图、条形图和堆叠图类型的交互式 3D 可视化效果。

何时使用本指南

在以下情况下使用本指南：

• 在 React 应用中实现 Syncfusion 3D 图表
• 创建柱形图、条形图或堆叠 3D 图表
• 配置类别、数值、日期时间或对数坐标轴
• 绑定和管理图表数据源
• 自定义 3D 图表外观（旋转、深度、墙面）
• 为 3D 图表添加数据标签、图例或工具提示
• 实现图表选择和交互
• 导出或打印 3D 图表
• 为 3D 可视化效果提供无障碍支持
• 排查 3D 图表渲染或性能问题

组件概述

包： @syncfusion/ej2-react-charts

主要组件：

• Chart3DComponent - 3D 图表根容器
• Chart3DSeriesCollectionDirective - 系列集合包装器
• Chart3DSeriesDirective - 单个系列的配置
• Chart3DAxesDirective - 多坐标轴配置

图表类型： 柱形图、条形图、堆叠柱形图、堆叠条形图、100% 堆叠柱形图、100% 堆叠条形图

坐标轴类型： 类别、数值、日期时间、对数

文档与导航指南

API 参考

📄 阅读： references/api-reference.md

• 简明列出公共属性、方法、事件、子指令，并提供用法示例。请将其作为仓库内 API 概述的权威参考。

入门指南

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-react-charts 包
• 设置依赖项和 CSS 主题
• 创建第一个 3D 图表
• Chart3DComponent 基本用法
• TypeScript 配置

图表类型

📄 阅读： references/chart-types.md

• 柱形图（垂直 3D 柱）
• 条形图（水平 3D 柱）
• 堆叠柱形图
• 堆叠条形图
• 100% 堆叠柱形图
• 100% 堆叠条形图
• 各种图表类型的适用场景
• 系列类型配置

使用数据

📄 阅读： references/working-with-data.md

• 数据绑定方式
• 数据源结构要求
• 系列配置（xName、yName）
• 多个系列的处理
• 动态数据更新
• 空数据点处理

类别坐标轴

📄 阅读： references/category-axis.md

• 类别坐标轴配置
• 标签格式与位置
• 类别分组
• 间隔设置
• 分类数据的使用场景

数值坐标轴

📄 阅读： references/numeric-axis.md

• 数值坐标轴设置
• 范围配置（最小值、最大值）
• 间隔和步长
• 标签格式（小数、货币）
• 从零开始与自动范围

日期时间坐标轴

📄 阅读： references/datetime-axis.md

• 日期时间坐标轴配置
• 日期格式选项
• 间隔类型（天、月、年）
• 日期范围设置
• Skeleton 格式
• 时区注意事项

对数坐标轴

📄 阅读： references/logarithmic-axis.md

• 对数刻度概述
• 基数配置（log10、log2 等）
• 指数数据的使用场景
• 对数刻度的标签格式
• 范围和间隔设置

坐标轴自定义

📄 阅读： references/axis-customization.md

• 坐标轴标题和标签
• 多个坐标轴（次 Y 轴）
• 坐标轴线样式
• 网格线配置
• 刻度线自定义
• 标签旋转和格式
• 坐标轴交叉值
• 反转坐标轴

多面板

📄 阅读： references/multiple-panes.md

• 多面板概述
• 行配置和分布
• 面板高度设置
• 将系列分配到不同面板
• 每个面板的坐标轴绑定
• 多指标对比的使用场景

数据标签、图例和工具提示

📄 阅读： references/data-labels-legend-tooltip.md

• 数据标签配置和定位
• 标签模板和格式设置
• 图例位置和自定义
• 切换图例可见性
• 启用和格式化工具提示
• 自定义工具提示模板
• 共享工具提示

选择和交互

📄 阅读： references/selection-interaction.md

• 选择模式（Point、Series、Cluster）
• 单选和多选
• 选择事件和处理程序
• 悬停时高亮
• 选择样式
• 交互功能

打印和导出

📄 阅读： references/print-export.md

• 打印功能
• 导出为 PNG、JPEG、SVG
• 导出为 PDF
• 导出配置选项
• 文件命名约定
• 导出事件

外观和主题

• 内置主题（Material、Bootstrap、Fluent、Tailwind）
• 创建自定义主题
• 调色板
• 3D 旋转角度和倾斜角度
• 3D 深度配置
• 墙面自定义
• 图表背景和边框
• 动画设置

无障碍

• 符合 WCAG 2.1 标准
• 支持键盘导航
• ARIA 属性
• 兼容屏幕阅读器
• 高对比度模式
• 焦点管理
• 无障碍配色方案

快速入门示例

import * as React from 'react';
import * as ReactDOM from 'react-dom';
import { 
  Chart3DComponent, 
  Chart3DSeriesCollectionDirective, 
  Chart3DSeriesDirective,
  Inject,
  Category3D,
  ColumnSeries3D,
  Legend3D,
  DataLabel3D,
  Tooltip3D
} from '@syncfusion/ej2-react-charts';

function SalesChart() {
  const data = [
    { month: 'Jan', sales: 35 },
    { month: 'Feb', sales: 28 },
    { month: 'Mar', sales: 34 },
    { month: 'Apr', sales: 32 },
    { month: 'May', sales: 40 }
  ];

  return (
    <Chart3DComponent
      id='chart'
      title='Monthly Sales'
      primaryXAxis={{ valueType: 'Category' }}
      primaryYAxis={{ title: 'Sales (K)' }}
      enableRotation={true}
      rotation={7}
      tilt={10}
      depth={100}
    >
      <Inject services={[ColumnSeries3D, Category3D, Legend3D, DataLabel3D, Tooltip3D]} />
      <Chart3DSeriesCollectionDirective>
        <Chart3DSeriesDirective
          dataSource={data}
          xName='month'
          yName='sales'
          type='Column'
          name='Sales'
        />
      </Chart3DSeriesCollectionDirective>
    </Chart3DComponent>
  );
}

export default SalesChart;
ReactDOM.render(<SalesChart />, document.getElementById('charts'));

常见模式

基本柱状图

<Chart3DComponent primaryXAxis={{ valueType: 'Category' }}>
  <Inject services={[ColumnSeries3D, Category3D]} />
  <Chart3DSeriesCollectionDirective>
    <Chart3DSeriesDirective
      dataSource={data}
      xName='category'
      yName='value'
      type='Column'
    />
  </Chart3DSeriesCollectionDirective>
</Chart3DComponent>

堆叠柱状图

<Chart3DComponent primaryXAxis={{ valueType: 'Category' }}>
  <Inject services={[StackingColumnSeries3D, Category3D]} />
  <Chart3DSeriesCollectionDirective>
    <Chart3DSeriesDirective
      dataSource={data1}
      xName='x'
      yName='y'
      type='StackingColumn'
      name='Product A'
    />
    <Chart3DSeriesDirective
      dataSource={data2}
      xName='x'
      yName='y'
      type='StackingColumn'
      name='Product B'
    />
  </Chart3DSeriesCollectionDirective>
</Chart3DComponent>

条形图（水平）

<Chart3DComponent primaryXAxis={{ valueType: 'Category' }}>
  <Inject services={[BarSeries3D, Category3D]} />
  <Chart3DSeriesCollectionDirective>
    <Chart3DSeriesDirective
      dataSource={data}
      xName='category'
      yName='value'
      type='Bar'
    />
  </Chart3DSeriesCollectionDirective>
</Chart3DComponent>

添加数据标签和图例

<Chart3DComponent
  primaryXAxis={{ valueType: 'Category' }}
  legendSettings={{ visible: true }}
>
  <Inject services={[ColumnSeries3D, Category3D, Legend3D, DataLabel3D]} />
  <Chart3DSeriesCollectionDirective>
    <Chart3DSeriesDirective
      dataSource={data}
      xName='x'
      yName='y'
      type='Column'
      name='Sales'
      dataLabel={{ visible: true }}
    />
  </Chart3DSeriesCollectionDirective>
</Chart3DComponent>

自定义 3D 旋转

<Chart3DComponent
  primaryXAxis={{ valueType: 'Category' }}
  enableRotation={true}
  rotation={15}
  tilt={5}
  depth={120}
  wallColor='transparent'
  wallSize={1}
>
  <Inject services={[ColumnSeries3D, Category3D]} />
  <Chart3DSeriesCollectionDirective>
    <Chart3DSeriesDirective
      dataSource={data}
      xName='x'
      yName='y'
      type='Column'
    />
  </Chart3DSeriesCollectionDirective>
</Chart3DComponent>

多个不同颜色的系列

<Chart3DComponent
  primaryXAxis={{ valueType: 'Category' }}
  palettes={['#E94649', '#F6B53F', '#6FAAB0']}
>
  <Inject services={[ColumnSeries3D, Category3D, Legend3D]} />
  <Chart3DSeriesCollectionDirective>
    <Chart3DSeriesDirective
      dataSource={data1}
      xName='x'
      yName='y'
      type='Column'
      name='Product A'
    />
    <Chart3DSeriesDirective
      dataSource={data2}
      xName='x'
      yName='y'
      type='Column'
      name='Product B'
    />
    <Chart3DSeriesDirective
      dataSource={data3}
      xName='x'
      yName='y'
      type='Column'
      name='Product C'
    />
  </Chart3DSeriesCollectionDirective>
</Chart3DComponent>

关键属性参考

Chart3DComponent 属性

属性	类型	说明
primaryXAxis	Object	X 轴配置（类型、标题、标签）
primaryYAxis	Object	Y 轴配置（范围、标题、格式）
rotation	number	水平旋转角度（0-360）
tilt	number	垂直倾斜角度（0-90）
depth	number	3D 图表深度（0-100）
enableRotation	boolean	启用鼠标旋转交互
wallColor	string	3D 墙面的颜色
wallSize	number	墙面边框厚度
title	string	图表标题文本
legendSettings	Object	图例配置
tooltip	Object	工具提示设置
palettes	string[]	系列颜色数组

Chart3DSeriesDirective 属性

属性	类型	说明
dataSource	any[]	数据点数组
xName	string	X 轴值对应的属性名称
yName	string	Y 轴值对应的属性名称
type	string	图表类型：'Column'、'Bar'、'StackingColumn'、'StackingBar'、'StackingColumn100'、'StackingBar100'
name	string	系列名称（显示在图例中）
dataLabel	Object	数据标签配置
fill	string	系列颜色
opacity	number	系列不透明度（0-1）

常见用例

1. 销售额比较：使用柱状图比较不同产品的月度／季度销售额
2. 调查结果：使用条形图展示调查答复或排名
3. 市场份额：使用堆叠柱状图显示市场分布
4. 时间序列：使用 DateTime 轴可视化时间数据
5. 财务数据：使用对数轴展示股票价格或指数增长
6. 多指标仪表板：使用多个面板展示不同的 KPI
7. 绩效跟踪：使用 100% 堆叠图展示百分比贡献
8. 类别分析：使用类别轴对离散数据分组
9. 交互式报告：通过选择和导出，让用户自行探索
10. 无障碍可视化：为所有用户提供符合 WCAG 标准的图表

TypeScript 支持

所有组件都提供完整的类型定义。按需导入类型：

import { 
  Chart3DComponent,
  IChart3DLoadedEventArgs,
  IChart3DPointRenderEventArgs,
  Chart3DModel
} from '@syncfusion/ej2-react-charts';

故障排除快速参考

图表未渲染？

• 确认已安装 @syncfusion/ej2-react-charts
• 检查 CSS 主题导入
• 确保已注入所需服务

未显示数据？

• 确认 xName/yName 与数据属性名称匹配
• 检查坐标轴的 valueType 是否与数据类型匹配
• 验证数据源结构

性能问题？

• 减少数据点数量（必要时进行聚合）
• 禁用动画
• 优化数据结构

3D 效果不起作用？

• 设置 enableRotation={true}
• 配置旋转、倾斜和深度属性
• 检查系列类型是否支持 3D

如需详细的故障排除信息，请参阅上方的具体参考文件。