syncfusion-blazor-3D-charts

实现 Syncfusion Blazor 3D 图表

NuGet： Syncfusion.Blazor.Chart3D + Syncfusion.Blazor.Themes
命名空间： Syncfusion.Blazor.Chart3D

这是一项全面的技能，用于实现和自定义 Syncfusion 的 Blazor 3D Chart 组件。3D Chart 支持柱形图、条形图和堆积图，可通过旋转、倾斜、深度以及多种坐标轴类型等丰富选项进行自定义，打造出色的三维可视化效果。

何时使用此技能

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

• 在 Blazor 应用中创建三维图表
• 使用 3D 柱形图、条形图或堆积图可视化数据
• 实现可旋转和倾斜的 3D 可视化效果
• 为 3D 图表配置类别、数值、日期时间或对数坐标轴
• 从各种数据源绑定数据（IEnumerable、远程数据、动态对象）
• 自定义 3D 图表外观（颜色、深度、墙面颜色、旋转）
• 为 3D 图表添加数据标签、图例和工具提示
• 配置坐标轴标签、刻度线和网格线
• 在 3D 图表中启用选择、高亮和交互
• 创建多窗格 3D 图表布局
• 导出或打印 3D 图表
• 确保 3D 可视化符合 WCAG 无障碍标准
• 排查 3D 图表渲染或配置问题

组件概览

包：Syncfusion.Blazor.Chart3D
组件：SfChart3D
支持的图表类型：Column、Bar、StackedColumn、StackedBar
支持的坐标轴类型：Category、Numeric、DateTime、Logarithmic
平台：Blazor Server、Blazor WebAssembly、Blazor Web App（.NET 8+）

3D Chart 组件可在三维空间中渲染数据，并支持配置旋转、倾斜和深度，以增强视觉效果。它支持所有标准图表功能，包括多个系列、丰富的工具提示、图例、数据标签和广泛的自定义选项。

文档与导航指南

API 参考

📄 阅读： references/api-reference.md

• Syncfusion.Blazor.Chart3D 命名空间的完整 API 参考
• SfChart3D 组件的属性、方法和事件
• 所有图表系列、坐标轴、图例和工具提示类
• 数据标签、边框、边距和样式组件
• 所有图表事件的事件参数类
• 枚举（Chart3DSeriesType、ValueType、SelectionMode 等）
• 接口定义和基类
• 常见 API 场景的用法示例
• 详细在线 API 文档的链接

事件参考

📄 阅读： references/events.md

• 所有 3D 图表事件的完整参考
• 生命周期事件（OnCreated、OnResized）
• 渲染事件（OnSeriesRender、OnPointRender、OnAxisLabelRender 等）
• 用户交互事件（OnPointClick、OnLegendClick、OnSelectionChanged）
• 鼠标事件（OnChartMouseMove、OnChartMouseClick 等）
• 导出和数据事件（OnExported、OnAxisRangeRendered）
• 事件参数属性和用法示例
• 包含多个事件的完整可运行示例
• 事件处理最佳实践

入门

📄 阅读： references/getting-started.md

• 适用于 Blazor Server、WebAssembly 和 Web App 的完整安装与设置指南
• NuGet 包安装（Syncfusion.Blazor.Chart3D）
• 服务注册和命名空间导入
• 脚本和主题配置
• 使用完整代码示例创建首个 3D 图表
• 数据源设置和基本绑定
• .NET 8+ 的渲染模式配置
• 常见设置问题的故障排除

图表类型

📄 阅读： references/chart-types.md

• 柱形图——垂直 3D 柱
• 条形图——水平 3D 柱
• 堆积柱形图——垂直堆积的系列
• 堆积条形图——水平堆积的系列
• 图表类型配置（Chart3DSeriesType 枚举）
• 自定义柱形图和条形图的间距与宽度
• 使用 GroupName 属性对柱形图分组
• 在单个图表中使用多个系列
• 每种类型的完整代码示例

数据绑定

📄 **阅读：references/data-binding.md

• 使用 IEnumerable 对象进行列表绑定
• 使用 ExpandoObject 绑定动态数据结构
• 使用 DynamicObject 绑定运行时数据
• 使用 SfDataManager 绑定远程数据
• DataSource、XName、YName 属性映射
• 复杂数据结构和嵌套属性
• 动态数据更新和刷新
• 性能优化技巧

坐标轴配置

📄 **阅读：references/axes-configuration.md

• 分类坐标轴——用于离散类别
• 数值坐标轴——用于连续数值数据
• 日期时间坐标轴——用于时间序列数据
• 对数坐标轴——用于指数刻度数据
• ValueType 属性配置
• 坐标轴范围（Minimum、Maximum、Interval）
• 坐标轴标题和标题旋转
• 刻度线和网格线自定义
• 支持多个坐标轴
• 每种坐标轴类型的完整示例

坐标轴标签

📄 **阅读：references/axis-labels.md

• 标签格式化（LabelFormat 属性）
• 自定义标签模板
• 标签旋转（LabelRotationAngle）
• 标签位置（BetweenTicks、OnTicks）
• 标签样式自定义（字体、颜色、大小）
• 智能标签碰撞处理
• 使用事件设置自定义标签文本
• 边缘标签位置
• 多级标签

数据标签

📄 **阅读：references/data-labels.md

• 为系列启用数据标签
• 标签位置配置
• 标签模板自定义
• 标签样式（字体、颜色、背景）
• 智能标签定位
• 格式自定义
• 按条件显示标签
• 完整的实现示例

图例

📄 **阅读：references/legend.md

• 启用图例并设置其位置
• 图例对齐选项
• 自定义系列名称
• 图例样式和外观
• 交互式图例切换
• 自定义图例项和图标
• 图例模板
• 完整的配置示例

工具提示

📄 **阅读：references/tooltip.md

• 启用悬停工具提示
• 工具提示格式自定义
• 自定义工具提示模板
• 工具提示样式（边框、填充、透明度）
• 多点工具提示内容
• 跨系列共享工具提示
• 完整的实现示例

外观和样式

📄 **阅读：references/appearance.md

• 图表背景和墙面颜色
• 系列颜色和调色板
• 主题集成（Material、Bootstrap、Fluent、Tailwind）
• 使用 CssClass 自定义 CSS 样式
• 不透明度和透明效果
• 边框样式和自定义
• 动画配置
• 视觉效果和增强功能

图表尺寸和 3D 效果

📄 **阅读：references/chart-dimensions.md

• 图表尺寸配置（Width、Height）
• 响应式尺寸设置技巧
• 3D 旋转（EnableRotation、RotationAngle）
• 倾斜角度配置（TiltAngle）
• 深度配置（Depth 属性）
• 墙面尺寸自定义
• 透视和视角
• 完整的尺寸示例

选择和高亮

📄 **阅读：references/selection.md

• 选择模式（Point、Series、Cluster）
• 启用选择功能
• 选择图案和视觉样式
• 支持多选
• 选择事件和处理
• 以编程方式进行选择
• 高亮模式和效果
• 完整的选择示例

多窗格

📄 **阅读：references/multiple-panes.md

• 创建多窗格图表布局
• 配置行窗格和列窗格
• 将坐标轴分配到特定窗格
• 在多个窗格中分布系列
• 自定义窗格边框和背景
• 窗格同步行为
• 多窗格使用场景
• 完整的多窗格示例

打印和导出

📄 阅读： references/print-export.md

• 打印功能
• 导出为图像格式（PNG、JPEG、SVG）
• 导出为 PDF 文档
• 导出配置选项
• 自定义导出设置
• 自定义打印预览
• 完整的导出示例

无障碍

📄 阅读： references/accessibility.md

• WCAG 2.1 合规性概述
• 键盘导航支持
• ARIA 属性和角色
• 屏幕阅读器兼容性
• 焦点管理
• 高对比度模式支持
• 颜色对比度要求
• 无障碍设计模式
• 无障碍测试

快速入门示例

@page "/3d-chart-demo"
@using Syncfusion.Blazor.Chart3D

<SfChart3D Title="Sales Analysis" 
           WallColor="transparent" 
           EnableRotation="true" 
           RotationAngle="7" 
           TiltAngle="10" 
           Depth="100">
    
    <Chart3DPrimaryXAxis Title="Month" 
                         ValueType="Syncfusion.Blazor.Chart3D.ValueType.Category">
    </Chart3DPrimaryXAxis>
    
    <Chart3DPrimaryYAxis Title="Sales (in thousands)">
    </Chart3DPrimaryYAxis>
    
    <Chart3DLegendSettings Visible="true"></Chart3DLegendSettings>
    
    <Chart3DTooltipSettings Enable="true"></Chart3DTooltipSettings>
    
    <Chart3DSeriesCollection>
        <Chart3DSeries DataSource="@SalesData" 
                       Name="Sales" 
                       XName="Month" 
                       YName="SalesValue" 
                       Type="Chart3DSeriesType.Column">
            <Chart3DDataLabel Visible="true"></Chart3DDataLabel>
        </Chart3DSeries>
    </Chart3DSeriesCollection>
</SfChart3D>

@code {
    public class SalesInfo
    {
        public string Month { get; set; }
        public double SalesValue { get; set; }
    }

    public List<SalesInfo> SalesData = new List<SalesInfo>
    {
        new SalesInfo { Month = "Jan", SalesValue = 35 },
        new SalesInfo { Month = "Feb", SalesValue = 28 },
        new SalesInfo { Month = "Mar", SalesValue = 34 },
        new SalesInfo { Month = "Apr", SalesValue = 32 },
        new SalesInfo { Month = "May", SalesValue = 40 },
        new SalesInfo { Month = "Jun", SalesValue = 32 },
        new SalesInfo { Month = "Jul", SalesValue = 35 }
    };
}

常见模式

多系列图表

@using Syncfusion.Blazor.Chart3D

<SfChart3D WallColor="transparent" EnableRotation="true" RotationAngle="7" TiltAngle="10" Depth="100">
    <Chart3DPrimaryXAxis ValueType="Syncfusion.Blazor.Chart3D.ValueType.Category">
    </Chart3DPrimaryXAxis>
    
    <Chart3DSeriesCollection>
        <Chart3DSeries DataSource="@Data" Name="Series 1" XName="X" YName="Y1" Type="Chart3DSeriesType.Column">
        </Chart3DSeries>
        <Chart3DSeries DataSource="@Data" Name="Series 2" XName="X" YName="Y2" Type="Chart3DSeriesType.Column">
        </Chart3DSeries>
    </Chart3DSeriesCollection>
</SfChart3D>

@code {
    public class ChartData
    {
        public string X { get; set; }
        public double Y1 { get; set; }
        public double Y2 { get; set; }
    }

    public List<ChartData> Data = new List<ChartData>
    {
        new ChartData { X = "Jan", Y1 = 35, Y2 = 28 },
        new ChartData { X = "Feb", Y1 = 28, Y2 = 32 },
        new ChartData { X = "Mar", Y1 = 34, Y2 = 30 },
        new ChartData { X = "Apr", Y1 = 32, Y2 = 36 },
        new ChartData { X = "May", Y1 = 40, Y2 = 38 },
        new ChartData { X = "Jun", Y1 = 32, Y2 = 34 },
        new ChartData { X = "Jul", Y1 = 35, Y2 = 37 }
    };
}

堆叠柱形图

@using Syncfusion.Blazor.Chart3D

<SfChart3D WallColor="transparent" EnableRotation="true" RotationAngle="7" TiltAngle="10" Depth="100">
    <Chart3DPrimaryXAxis ValueType="Syncfusion.Blazor.Chart3D.ValueType.Category">
    </Chart3DPrimaryXAxis>
    
    <Chart3DSeriesCollection>
        <Chart3DSeries DataSource="@Data" XName="X" YName="Y1" Type="Chart3DSeriesType.StackingColumn">
        </Chart3DSeries>
        <Chart3DSeries DataSource="@Data" XName="X" YName="Y2" Type="Chart3DSeriesType.StackingColumn">
        </Chart3DSeries>
    </Chart3DSeriesCollection>
</SfChart3D>

@code {
    public class StackingData
    {
        public string X { get; set; }
        public double Y1 { get; set; }
        public double Y2 { get; set; }
    }

    public List<StackingData> Data = new List<StackingData>
    {
        new StackingData { X = "Jan", Y1 = 20, Y2 = 15 },
        new StackingData { X = "Feb", Y1 = 18, Y2 = 12 },
        new StackingData { X = "Mar", Y1 = 25, Y2 = 14 },
        new StackingData { X = "Apr", Y1 = 22, Y2 = 16 },
        new StackingData { X = "May", Y1 = 28, Y2 = 18 },
        new StackingData { X = "Jun", Y1 = 24, Y2 = 14 },
        new StackingData { X = "Jul", Y1 = 26, Y2 = 17 }  
    };
}

日期时间轴图表

@using Syncfusion.Blazor.Chart3D

<SfChart3D WallColor="transparent" EnableRotation="true" RotationAngle="7" TiltAngle="10" Depth="100">
    <Chart3DPrimaryXAxis ValueType="Syncfusion.Blazor.Chart3D.ValueType.DateTime" 
                         LabelFormat="yyyy">
    </Chart3DPrimaryXAxis>
    
    <Chart3DSeriesCollection>
        <Chart3DSeries DataSource="@TimeSeriesData" 
                       XName="Date" 
                       YName="Value" 
                       Type="Chart3DSeriesType.Column">
        </Chart3DSeries>
    </Chart3DSeriesCollection>
</SfChart3D>

@code {
    public class TimeSeriesPoint
    {
        public DateTime Date { get; set; }
        public double Value { get; set; }
    }

    public List<TimeSeriesPoint> TimeSeriesData = new List<TimeSeriesPoint>
    {
        new TimeSeriesPoint { Date = new DateTime(2018, 1, 1), Value = 120 },
        new TimeSeriesPoint { Date = new DateTime(2019, 1, 1), Value = 135 },
        new TimeSeriesPoint { Date = new DateTime(2020, 1, 1), Value = 150 },
        new TimeSeriesPoint { Date = new DateTime(2021, 1, 1), Value = 170 },
        new TimeSeriesPoint { Date = new DateTime(2022, 1, 1), Value = 160 },
        new TimeSeriesPoint { Date = new DateTime(2023, 1, 1), Value = 185 },
        new TimeSeriesPoint { Date = new DateTime(2024, 1, 1), Value = 200 }
    };
}

关键属性和 API

SfChart3D 组件

主要属性：

• Title：图表标题文本
• SubTitle：图表副标题文本
• Width/Height：图表尺寸（带单位或百分比的字符串）
• WallColor：3D 墙面的背景颜色
• EnableRotation：启用鼠标旋转（bool）
• RotationAngle：初始旋转角度（0-360 度）
• TiltAngle：3D 透视倾斜角度（0-360 度）
• Depth：3D 渲染深度（数值）
• Theme：图表主题（Material、Bootstrap、Fluent、Tailwind 等）
• Background：图表背景颜色
• BackgroundImage：背景图像 URL

方法：

• ExportAsync(ExportType, string) - 将图表导出为 PNG、JPEG、SVG 或 PDF
• PrintAsync() - 打印图表
• Refresh() - 刷新图表渲染

主要事件：

• OnCreated - Chart3DCreatedEventArgs
• OnPointClick - Chart3DPointClickEventArgs
• OnSeriesRender - Chart3DSeriesRenderEventArgs
• OnPointRender - Chart3DPointRenderEventArgs
• OnLegendClick - Chart3DLegendClickEventArgs
• OnTooltipRender - Chart3DTooltipRenderEventArgs
• OnSelectionChanged - Chart3DSelectionChangedEventArgs
• OnAxisLabelRender - Chart3DAxisLabelRenderEventArgs

Chart3DSeries 属性

• DataSource：要绑定的数据集合
• XName：X 轴值的属性名称
• YName：Y 轴值的属性名称
• Name：系列在图例中的显示名称
• Type：Chart3DSeriesType 枚举（Column、Bar、StackingColumn、StackingBar）
• Fill：系列颜色
• Opacity：系列不透明度（0-1）
• ColumnSpacing：柱形之间的间距（0-1）
• ColumnWidth：柱形宽度（0-1）
• GroupName：分组柱形的组名
• Visible：系列可见性切换

子组件：

• Chart3DDataLabel - 数据标签配置
• Chart3DEmptyPointSettings - 空数据点处理
• Chart3DSeriesBorder - 边框自定义
• Chart3DAnimation - 动画设置

轴组件（Chart3DPrimaryXAxis、Chart3DPrimaryYAxis、Chart3DAxis）

核心属性：

• ValueType：ValueType 枚举（Category、Numeric、DateTime、Double、DateTimeCategory、Logarithmic）
• Title：轴标题文本
• Minimum/Maximum：轴范围边界
• Interval：轴值之间的间隔
• LabelFormat：标签格式字符串（例如，“yyyy”、“C”、“N2”）
• LabelRotationAngle：标签旋转角度
• EdgeLabelPlacement：EdgeLabelPlacement 枚举（None、Shift、Hide）
• LabelPlacement：LabelPlacement 枚举（OnTicks、BetweenTicks）
• RangePadding：ChartRangePadding 枚举（Auto、None、Normal、Additional、Round）
• IsInversed：反转轴方向
• OpposedPosition：将轴置于另一侧

子组件：

• Chart3DAxisLabelStyle - 标签字体自定义
• Chart3DAxisTitleStyle - 标题字体自定义
• Chart3DMajorGridLines / Chart3DMinorGridLines - 网格线设置
• Chart3DMajorTickLines / Chart3DMinorTickLines - 刻度线设置

图例设置 (Chart3DLegendSettings)

• Visible：显示/隐藏图例
• Position：LegendPosition 枚举（Top、Bottom、Left、Right、Custom）
• Alignment：Alignment 枚举（Near、Center、Far）
• Height/Width：图例尺寸
• ShapeHeight/ShapeWidth：图标尺寸
• ToggleVisibility：启用单击切换系列的显示状态
• Mode：Chart3DLegendMode 枚举（Series、Point）

子组件：

• Chart3DLegendTextStyle - 文本字体样式
• Chart3DLegendBorder - 边框自定义
• Chart3DLegendMargin - 边距设置

提示框设置 (Chart3DTooltipSettings)

• Enable：启用提示框
• Fill：背景颜色
• Format：提示框内容的格式字符串
• Shared：在多个系列间共享提示框
• EnableMarker：在提示框中显示标记
• FadeOutDuration：淡出时长，单位为 ms
• FadeOutMode：Chart3DFadeOutMode 枚举（Click、Move）
• Template：用于自定义提示框的 RenderFragment

子组件：

• Chart3DTooltipTextStyle - 文本字体样式
• Chart3DTooltipBorder - 边框自定义

选择设置

• SelectionMode：SelectionMode 枚举（None、Point、Series、Cluster）
• SelectionPattern：SelectionPattern 枚举（None、Dots、DiagonalForward、Grid、Chessboard 等）
• HighlightMode：HighlightMode 枚举（None、Point、Series、Cluster）

使用 Chart3DSelectedDataIndexes 集合和 Chart3DSelectedDataIndex 以编程方式选择数据点。

常见用例

业务仪表板指标

通过增强的 3D 可视化，在高管仪表板中展示 KPI、销售数据或绩效指标。

金融数据可视化

使用日期时间轴和多个系列呈现股票价格、市场趋势或金融对比数据。

科学数据展示

使用对数轴或数值轴可视化实验数据、测量结果或研究发现。

产品对比

使用分组柱形图或堆叠柱形图，按类别比较产品功能、评分或销量。

时间序列分析

使用日期时间轴和流畅的动画展示随时间变化的趋势。

区域销售报告

使用类别轴和丰富多彩的系列展示各地区、国家或区域的销售额。

故障排除提示

图表未渲染：

• 验证 Program.cs 中的 AddSyncfusionBlazor() 服务注册
• 检查 _Imports.razor 中的命名空间导入
• 确保脚本引用位于 body 标签末尾
• 确认 .NET 8+ 项目的渲染模式

未显示数据：

• 检查 XName 和 YName 是否与属性名称完全一致（区分大小写）
• 验证 DataSource 不为 null 且包含数据
• 确保 ValueType 与数据类型匹配（字符串使用 Category，数字使用 Numeric）

3D 旋转无效：

• 设置 EnableRotation="true"
• 确保 RotationAngle 介于 0-360 之间
• 检查鼠标事件是否被覆盖层阻止

性能问题：

• 限制数据点数量（3D 渲染占用大量资源）
• 如果不需要动画，请将其禁用
• 根据数据量选择合适的图表类型

相关 Syncfusion 组件

• 图表 - 支持 30 多种图表类型的 2D 图表组件
• 股票图表 - 带技术指标的金融图表
• 径向量规 - 径向量规可视化
• 透视表 - 多维数据分析
• 矩形树图 - 层次数据可视化