syncfusion-blazor-charts

实现 Syncfusion Blazor Charts

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

本指南全面介绍如何实现 Syncfusion Blazor Chart 组件，以便在 Blazor 应用程序中创建交互丰富、功能齐全的数据可视化图表。Chart 组件支持 33+ 种图表类型、多个坐标轴、高级交互功能和丰富的自定义选项。

何时使用此技能

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

• 在 Blazor 应用程序中创建数据可视化（折线图、柱形图、条形图、面积图等）
• 实现用于股票分析的金融图表（蜡烛图、HILO、HILOOC）
• 构建统计可视化图表（直方图、箱线图、帕累托图、瀑布图）
• 使用堆叠图表或分组图表展示对比数据
• 使用范围面积图／柱形图展示基于范围的数据
• 创建用于圆形数据表示的极坐标图或雷达图
• 添加工具提示、缩放、十字准线、选择等交互功能
• 使用主题、渐变、注释自定义图表外观
• 通过实时更新和数据编辑处理动态数据
• 实现支持 ARIA 和国际化的无障碍图表

组件概述

Syncfusion Blazor Chart 组件是一款功能强大的数据可视化工具，提供以下功能：

• **33+ 种图表类型：**折线图、柱形图、条形图、面积图、样条图、散点图、气泡图、蜡烛图、HILO、极坐标图、雷达图等
• **多个坐标轴：**支持类别、数值、日期时间和对数坐标轴
• **丰富的交互功能：**缩放、平移、十字准线、跟踪球、工具提示、选择
• **数据绑定：**支持 List、DataManager、动态更新和实时数据
• **可视元素：**标记、数据标签、注释、图例、渐变
• **高级功能：**技术指标、趋势线、条带线、多窗格
• **无障碍支持：**完整的 ARIA 支持、键盘导航、本地化、RTL
• **自定义：**主题、响应式设计、打印支持、自适应布局

文档与导航指南

完整 API 参考

📄 阅读： references/api-reference.md

重要：所有 API 相关问题都应首先查阅此参考资料

在以下情况下使用此权威 API 参考：

• 查找正确的枚举值（ChartSeriesType、ValueType、SelectionMode 等）
• 查找公共方法签名（RefreshAsync、ExportAsync、ShowTooltip 等）
• 验证属性名称和类型
• 生成代码示例
• 排查 API 相关问题

涵盖主题：

• SfChart 公共方法及其签名的完整列表
• 所有图表枚举及其正确值
• 关键组件类及其属性
• 方法用法示例
• 常见模式和最佳实践

要点：

• 所有枚举值都是精确值——请勿使用变体
• 方法名称遵循 C# 约定（例如，RefreshAsync 而不是 Refresh）
• 调用方法时，始终使用 @ref 访问图表实例
• 命名空间：Syncfusion.Blazor.Charts

---

入门指南

📄 阅读： references/getting-started.md

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

• 搭建新的 Blazor Chart 项目
• 安装 NuGet 包并配置服务
• 创建第一个图表组件
• 了解基本图表结构和数据绑定
• 使用 Visual Studio、VS Code 或 .NET CLI

涵盖主题：

• 安装和先决条件
• 包配置（Syncfusion.Blazor.Charts）
• 命名空间导入和服务注册
• 脚本引用
• 基本图表实现
• 简单的数据绑定示例

---

图表类型

常见图表类型

📄 阅读： references/chart-types-common.md

用于常用图表类型：

• 用于趋势可视化的折线图
• 用于展示随时间变化幅度的面积图
• 用于类别比较的柱形图
• 用于水平比较的条形图
• 用于平滑曲线的样条图
• 用于阶梯式数据变化的阶梯图

涵盖主题：

• 折线图、面积图、柱形图和条形图的实现
• 样条图和样条面积图的变体
• 阶梯折线图和阶梯面积图模式
• 各类图表的适用场景
• 配置和自定义
• 多系列示例

专用图表类型

📄 阅读： references/chart-types-specialized.md

用于专用可视化需求：

• 金融图表（蜡烛图、HILO、HILOOC）
• 统计图表（箱线图、直方图、误差线图、帕累托图、瀑布图）
• 堆叠图表（堆叠面积图／条形图／柱形图／折线图）
• 范围图表（范围面积图／柱形图／阶梯面积图）
• 极坐标图和雷达图
• 散点图和气泡图
• 垂直图表方向

涵盖主题：

• 金融图表模式和配置
• 统计分析图表类型
• 堆叠模式（普通与 100%）
• 范围可视化技术
• 环形图表布局
• XY 散点关系
• 图表方向选项

---

坐标轴和数据配置

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

在以下情况下使用：

• 配置坐标轴类型（类别、数值、日期时间、对数）
• 自定义坐标轴外观和行为
• 设置坐标轴标签和值的格式
• 使用多个坐标轴
• 设置坐标轴范围和间隔

涵盖主题：

• 用于离散数据的类别坐标轴
• 用于连续值的数值坐标轴
• 用于时间序列数据的日期时间坐标轴
• 用于指数数据的对数坐标轴
• 坐标轴自定义（标题、范围、间隔）
• 标签格式、旋转和位置
• 多坐标轴配置
• 反向和相对坐标轴

📄 阅读： references/data-handling.md

在以下情况下使用：

• 将数据源绑定到图表
• 动态添加、删除或更新数据
• 启用数据编辑
• 对图表数据排序
• 使用实时或流式数据

涵盖主题：

• 数据源绑定（List、DataManager）
• 动态数据操作
• 数据编辑功能
• 图表排序选项
• 实时数据更新
• 数据序列化模式

---

可视化元素

📄 阅读： references/visual-elements.md

在以下情况下使用：

• 为图表点添加数据标记
• 在系列上显示数据标签
• 创建自定义标签模板
• 添加注释（文本、形状、图像）
• 应用渐变填充

涵盖主题：

• 数据标记类型和自定义
• 数据标签的可见性和格式
• 标签定位策略
• 数据标签模板
• 显示系列标签以标识系列
• 突出显示最后一个数据标签
• 图表注释（文本、形状、图像）
• 渐变颜色填充

📄 阅读： references/legend.md

在以下情况下使用：

• 启用和配置图表图例
• 设置图例位置（顶部、底部、左侧、右侧）
• 自定义图例外观
• 实现图例点击行为
• 创建自定义图例模板

涵盖主题：

• 图例可见性和位置
• 图例形状和文本自定义
• 交互式图例（切换系列）
• 图例分页
• 自定义图例模板
• 图例对齐选项

---

交互功能

📄 阅读： references/interactive-features.md

适用于以下情况：

• 启用自定义格式的工具提示
• 添加十字线或跟踪球以跟踪数据
• 实现数据点、系列或簇的选择
• 启用缩放和平移
• 创建交互式用户体验

涵盖主题：

• 工具提示配置和模板
• 十字线和跟踪球功能
• 选择模式和模式
• 缩放类型（选区、捏合、鼠标滚轮）
• 缩放工具栏配置
• 平移功能
• 用户交互事件

---

自定义和外观

📄 阅读： references/appearance-styling.md

适用于以下情况：

• 自定义图表外观和主题
• 设置图表尺寸
• 配置响应式／自适应布局
• 启用打印功能
• 设置背景、边框和边距样式

涵盖主题：

• 图表外观自定义
• 主题配置
• 图表尺寸
• 响应式设计模式
• 适用于移动设备的自适应布局
• 打印支持
• 背景和边框样式
• 渐变自定义

📄 阅读： references/advanced-features.md

适用于以下情况：

• 添加技术指标（EMA、SMA、RSI 等）
• 实现趋势线（线性、指数、多项式）
• 创建条带线（水平／垂直带）
• 使用多个窗格（子图表）
• 处理空数据点

涵盖主题：

• 金融图表的技术指标
• 趋势线类型和配置
• 条带线模式
• 多窗格布局
• 空数据点处理策略
• 行和列定义

---

无障碍功能和国际化

📄 阅读： references/accessibility-internationalization.md

适用于以下情况：

• 实现无障碍图表（ARIA、键盘导航）
• 配置高级无障碍功能
• 启用国际化（i18n）
• 设置本地化（l10n）
• 支持 RTL 布局

涵盖主题：

• 无障碍功能和 ARIA 支持
• 键盘导航模式
• 高级无障碍配置
• 国际化设置
• 本地化资源
• RTL 支持
• 屏幕阅读器兼容性

---

事件

📄 阅读： references/events.md

适用于以下情况：

• 处理图表生命周期事件
• 响应用户交互（点击、鼠标事件）
• 侦听坐标轴、系列或数据点事件
• 实现自定义事件处理程序
• 在缩放、平移或选择时触发操作

涵盖主题：

• 图表加载和渲染事件
• 数据点和系列事件
• 鼠标事件（点击、移动、离开）
• 坐标轴标签渲染事件
• 图例事件
• 缩放和平移事件
• 选择事件
• 事件处理程序模式

---

实用示例和操作指南

📄 阅读： references/practical-examples.md

适用于以下常见实现方案：

• 动态添加／移除系列
• 以编程方式隐藏坐标轴
• 将毫秒转换为日期时间
• 动态更新数据点
• 实现延迟加载
• 创建实时图表
• 获取选中的数据
• 同步多个图表
• 添加阈值线
• 自定义工具提示表格

涵盖主题：

• 动态系列管理
• 坐标轴可见性控制
• 日期转换技术
• 动态数据点更新
• 延迟加载模式
• 实时图表实现
• 获取选中数据
• 图表同步
• 阈值线实现
• 自定义工具提示表格

---

公共方法参考

SfChart 组件提供多种公共方法，可用于编程控制。访问这些方法时，请始终使用 @ref：

基本方法

<SfChart @ref="ChartRef">
    
</SfChart>

@code {
    SfChart ChartRef;
    
    // Refresh the chart
    async Task RefreshChart() => await ChartRef.RefreshAsync();
    
    // Export the chart
    async Task ExportChart() => await ChartRef.ExportAsync(ExportType.PNG, "chart.png");
    
    // Print the chart
    async Task PrintChart() => await ChartRef.PrintAsync();
    
    // Show/Hide tooltip
    void ShowChartTooltip() => ChartRef.ShowTooltip("January", 35);
    void HideChartTooltip() => ChartRef.HideTooltip();
    
    // Show/Hide crosshair
    void ShowChartCrosshair() => ChartRef.ShowCrosshair(100, 50);
    void HideChartCrosshair() => ChartRef.HideCrosshair();
    
    // Selection control
    void ClearSelections() => ChartRef.ClearSelection();
    
    // Sorting
    void SortData() => ChartRef.Sort("YValue", ListSortDirection.Descending);
    void ClearChartSort() => ChartRef.ClearSort();
}

完整的方法文档请参阅 references/api-reference.md。

---

⚠️ 重要：API 使用指南

1. 枚举名称——必须使用完整命名空间

Syncfusion Blazor Charts 要求使用完全限定的枚举名称：

<ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category" />
<ChartSeries Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column" />


<ChartPrimaryXAxis ValueType="ValueType.Category" />
<ChartSeries Type="ChartSeriesType.Column" />

以下内容始终使用 Syncfusion.Blazor.Charts. 前缀：

• ValueType（Category、Double、DateTime 等）
• ChartSeriesType（Column、Line、Area 等）
• LegendPosition、SelectionMode、ZoomMode、ChartShape 等

2. 组件属性限制

⚠️ 需要避免的常见属性错误：

ChartCrosshairLine——属性有限

<ChartCrosshairSettings Enable="true">
    <ChartCrosshairLine Width="1" Color="#666"></ChartCrosshairLine>
</ChartCrosshairSettings>


<ChartCrosshairLine Width="1" Color="#666" DashArray="5,5"></ChartCrosshairLine>

ChartCrosshairLine 支持的属性：

• Width - 线条宽度（数字）
• Color - 线条颜色（字符串）

不支持：

• ❌ DashArray - 会导致运行时错误
• ❌ Opacity - 此组件不提供该属性

条带线——使用复数形式

<ChartPrimaryYAxis>
    <ChartStriplines>
        <ChartStripline Start="50" End="60" Color="red" />
    </ChartStriplines>
</ChartPrimaryYAxis>


<ChartAxisStripLineSettings>
    <ChartAxisStripLine Start="50" End="60" />
</ChartAxisStripLineSettings>

3. 验证清单

部署前，请确认：

• ✅ 所有枚举均使用 Syncfusion.Blazor.Charts. 前缀
• ✅ ChartCrosshairLine 仅使用 Width 和 Color
• ✅ 条带线使用 <ChartStriplines> 和 <ChartStripline>
• ✅ 组件引用使用 @ref 以访问方法
• ✅ 属性名称与官方 API 完全一致（区分大小写）

---

快速入门示例

下面是一个使用数据创建柱状图的最简示例：

@page "/chart-demo"
@using Syncfusion.Blazor.Charts

<SfChart Title="Sales Analysis">
    <ChartPrimaryXAxis Title="Month" ValueType="Syncfusion.Blazor.Charts.ValueType.Category">
    </ChartPrimaryXAxis>
    
    <ChartPrimaryYAxis Title="Sales in Dollar">
    </ChartPrimaryYAxis>
    
    <ChartTooltipSettings Enable="true"></ChartTooltipSettings>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@SalesData" 
                     Name="Sales" 
                     XName="Month" 
                     YName="SalesValue" 
                     Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
            <ChartMarker>
                <ChartDataLabel Visible="true"></ChartDataLabel>
            </ChartMarker>
        </ChartSeries>
    </ChartSeriesCollection>
</SfChart>

@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 }
    };
}

前置条件：

1. 安装 Syncfusion.Blazor.Charts NuGet 包
2. 将 @using Syncfusion.Blazor.Charts 添加到 _Imports.razor
3. 在 Program.cs 中注册服务：builder.Services.AddSyncfusionBlazor();
4. 在 App.razor 中添加脚本引用

---

常见模式

多系列对比图表

<SfChart Title="Product Sales Comparison">
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category"></ChartPrimaryXAxis>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@Product1Sales" XName="Month" YName="Sales" 
                     Name="Product 1" Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
        </ChartSeries>
        <ChartSeries DataSource="@Product2Sales" XName="Month" YName="Sales" 
                     Name="Product 2" Type="Syncfusion.Blazor.Charts.ChartSeriesType.Column">
        </ChartSeries>
    </ChartSeriesCollection>
    
    <ChartLegendSettings Visible="true"></ChartLegendSettings>
</SfChart>

带缩放功能的时间序列折线图

<SfChart>
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.DateTime" 
                        Title="Date">
    </ChartPrimaryXAxis>
    
    <ChartZoomSettings EnableSelectionZooming="true" 
                       EnablePan="true" 
                       EnableMouseWheelZooming="true">
    </ChartZoomSettings>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@TimeSeriesData" 
                     XName="Date" 
                     YName="Value" 
                     Type="Syncfusion.Blazor.Charts.ChartSeriesType.Line">
        </ChartSeries>
    </ChartSeriesCollection>
</SfChart>

带图例的堆叠面积图

<SfChart Title="Resource Allocation">
    <ChartPrimaryXAxis ValueType="Syncfusion.Blazor.Charts.ValueType.Category"></ChartPrimaryXAxis>
    
    <ChartSeriesCollection>
        <ChartSeries DataSource="@ResourceData1" XName="Period" YName="Hours" 
                     Name="Development" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
        <ChartSeries DataSource="@ResourceData2" XName="Period" YName="Hours" 
                     Name="Testing" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
        <ChartSeries DataSource="@ResourceData3" XName="Period" YName="Hours" 
                     Name="Documentation" Type="Syncfusion.Blazor.Charts.ChartSeriesType.StackingArea">
        </ChartSeries>
    </ChartSeriesCollection>
    
    <ChartLegendSettings Visible="true" Position="Syncfusion.Blazor.Charts.LegendPosition.Bottom">
    </ChartLegendSettings>
</SfChart>

---

关键配置属性

图表组件（SfChart）

• Title - 图表标题文本
• Width / Height - 图表尺寸（接受 px 或 %，默认值："100%"）
• Theme - 视觉主题（请参阅 API 参考中的 Theme 枚举）
• Background - 图表背景颜色
• EnableAnimation - 启用/禁用动画（默认值：true）
• SelectionMode - 选择模式（None、Series、Point、Cluster、DragXY、DragX、DragY、Lasso）
• HighlightMode - 高亮模式（None、Series、Point、Cluster）

主坐标轴（ChartPrimaryXAxis、ChartPrimaryYAxis）

• ValueType - 坐标轴类型：Syncfusion.Blazor.Charts.ValueType.Category、ValueType.Double、ValueType.DateTime、ValueType.Logarithmic、ValueType.DateTimeCategory
• Title - 坐标轴标题
• Minimum / Maximum - 坐标轴范围
• Interval - 标签间距
• LabelFormat - 标签格式字符串（例如，"C0"、"N2"、"dd MMM"）
• EdgeLabelPlacement - 边缘标签处理方式（None、Hide、Shift）
• LabelIntersectAction - 标签交叠处理方式（None、Hide、Trim、Wrap、MultipleRows、Rotate45、Rotate90）
• 条带线 - 使用 <ChartStriplines>（复数）绘制水平或垂直色带

系列（ChartSeries）

• DataSource - 数据集合（IEnumerable）
• XName / YName - X 值和 Y 值的属性名称（区分大小写）
• Type - 图表类型：Syncfusion.Blazor.Charts.ChartSeriesType.Column、ChartSeriesType.Line 等（请参阅 API 参考）
• Name - 图例中显示的系列名称
• Fill - 系列颜色（CSS 颜色字符串）
• Width - 线条/边框宽度（像素）
• DashArray - 虚线图案（例如，"5,5"）
• Opacity - 透明度（0 到 1）

交互性

• ChartTooltipSettings - 工具提示配置
  • Enable - 显示/隐藏工具提示
  • Shared - 为多个系列启用共享工具提示
  • Format - 自定义工具提示格式
  • Template - 自定义工具提示模板（RenderFragment）
• ChartZoomSettings - 缩放和平移选项
  • EnableSelectionZooming - 启用基于选择的缩放
  • EnableMouseWheelZooming - 启用鼠标滚轮缩放
  • EnablePinchZooming - 启用捏合缩放（触控设备）
  • EnablePan - 启用平移
  • Mode - 缩放模式（X、Y、XY）
• SelectionMode - 选择行为（参见 SelectionMode 枚举）
• ChartCrosshairSettings - 十字线配置
  • Enable - 显示/隐藏十字线
  • LineType - 十字线类型（Vertical、Horizontal、Both）
  • ChartCrosshairLine - 线条样式（仅限 Width、Color——不支持 DashArray）

视觉元素

• ChartMarker - 数据点标记
  • Visible - 显示/隐藏标记
  • Shape - 标记形状（参见 ChartShape 枚举）
  • Width / Height - 标记尺寸
• ChartDataLabel - 数据点上的数据标签
  • Visible - 显示/隐藏标签
  • Position - 标签位置
  • Template - 自定义标签模板
• SeriesLabelSettings - 系列标签的可见性、文本、重叠处理和样式
• ChartLegendSettings - 图例配置
  • Visible - 显示/隐藏图例
  • Position - 图例位置（参见 LegendPosition 枚举）
• ChartAnnotations - 自定义注释
  • 支持文本、图像和形状

---

其他资源

• 官方文档： Syncfusion Blazor 图表文档
• API 参考： 图表 API
• 在线演示： Blazor 图表示例