syncfusion-blazor-chart-wizard

实现 Syncfusion Blazor Chart Wizard

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

Syncfusion Blazor Chart Wizard 是一款功能全面、易于使用的组件，可引导用户以交互方式创建和自定义图表。它提供基于对话框的界面，包含属性面板、多种图表类型、数据绑定、主题、无障碍功能和导出功能。

何时使用此技能

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

• 交互式图表创建：构建允许用户以交互方式创建和自定义图表的应用程序
• 数据可视化工具：实现仪表板构建器、报表生成器或分析界面
• 引导式图表配置：通过可视化属性面板提供分步图表设置
• 多格式导出：需要将图表导出为 PNG、JPEG、SVG、PDF、CSV 或 XLSX 格式
• 适配主题的图表：构建可适配应用程序主题（Material、Fluent、Bootstrap、Tailwind 等）的图表
• 无障碍可视化：创建符合 WCAG 2.2 AA 标准并支持键盘导航和屏幕阅读器的图表
• 图表状态持久化：保存和加载图表配置，以便保存用户偏好或模板
• Blazor 应用程序：在 Blazor Server、WebAssembly 或 Web App 架构中实现

组件概述

Chart Wizard 组件提供：

• 交互式图表构建器：通过分步引导界面创建图表
• 15 种以上图表类型：折线图、柱状图、条形图、面积图、饼图、散点图及堆叠变体
• 属性面板：通过可视化控件实时自定义图表
• 数据绑定：支持 IEnumerable、List 和 ObservableCollection 数据源
• 多系列支持：使用多个数据系列和类别创建图表
• 导出功能：导出为图像（PNG、JPEG、SVG）、文档（PDF）和数据格式（CSV、XLSX）
• 序列化：将完整图表配置保存并加载为 JSON
• 主题：提供 20 种以上内置主题，样式一致
• 无障碍功能：完全符合 WCAG 2.2 AA 标准，并支持键盘导航
• RTL 支持：为国际化应用程序提供从右向左的布局

文档与导航指南

开始使用

根据 Blazor 应用程序类型选择相应的设置指南：

Blazor Server 应用设置

📄 阅读： references/getting-started.md

Blazor Server 应用程序的完整设置说明，包括：

• 使用 Visual Studio、VS Code 和 .NET CLI 创建项目
• 安装 NuGet 包（Syncfusion.Blazor.ChartWizard）
• 导入命名空间并注册服务
• 配置脚本引用
• 实现组件
• 创建和绑定数据模型
• 配置主题
• 使用奥运会数据的完整可运行示例
• 常见设置问题的故障排除

Blazor WebAssembly (WASM) 应用设置

📄 阅读： references/getting-started-wasm.md

Blazor WASM 应用程序的完整设置说明，包括：

• 使用不同 IDE 创建 WASM 专用项目
• 安装软件包并还原依赖项
• 配置客户端渲染
• 设置组件并绑定数据
• 配置 WASM 主题
• 完整的 WASM 功能示例
• 性能优化注意事项

Blazor Web App 设置

📄 阅读： references/getting-started-web-app.md

使用渲染模式的 Blazor Web Apps 完整设置说明，包括：

• 配置交互式渲染模式（Server、WebAssembly、Auto）
• 设置交互性位置（全局、按页面/组件）
• 管理客户端与 Server 项目的软件包
• 实现特定于渲染模式的组件
• 管理不同渲染模式下的主题
• 使用 Auto 模式的完整 Web App 示例
• 选择渲染模式的最佳实践

数据操作

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

全面介绍数据绑定和字段配置，包括：

• ChartSettings 配置和属性
• DataSource 绑定（IEnumerable）
• CategoryFields 配置，用于 x 轴分组
• SeriesFields 用于多系列数据映射
• SeriesType 选择（15 种以上图表类型）
• 单系列与多系列图表模式
• List 数据绑定示例
• 用于动态数据的 ObservableCollection
• 数据模型设计最佳实践
• 字段映射和排序
• 使用 Olympics 和销售数据的完整示例
• 数据显示问题的故障排除

外观与自定义

📄 阅读： references/appearance-customization.md

介绍视觉自定义和布局配置，包括：

• Width 和 Height 属性（百分比和像素单位）
• 响应式设计模式
• Theme 属性配置（20 种以上内置主题）
  • Material、Material3、MaterialDark、Material3Dark
  • Fluent、Fluent2、FluentDark、Fluent2Dark、Fluent2HighContrast
  • Bootstrap、Bootstrap4、Bootstrap5、BootstrapDark、Bootstrap5Dark
  • Tailwind、Tailwind3、TailwindDark、Tailwind3Dark
  • Fabric、FabricDark
  • HighContrast、HighContrastLight
• 主题样式表的前提条件和引入方式
• EnableRtl 支持从右向左布局
• PropertyPanelExpanded 用于控制面板的初始状态
• 外观组合配置示例
• 主题一致性最佳实践
• 主题和尺寸问题的故障排除

无障碍访问

📄 阅读： references/accessibility.md

全面介绍无障碍合规性和功能，包括：

• 支持 WCAG 2.2 AA 级别
• 符合 Section 508 标准
• WAI-ARIA 属性和角色
  • 数据标签、图例、轴标题
  • 图表标题和系列数据点
  • ARIA 角色：img、button、region
  • ARIA 属性：label、hidden、pressed
• 屏幕阅读器支持
• 完整的键盘导航
  • 焦点管理（Alt+J、Tab、Shift+Tab）
  • 数据点导航（方向键）
  • 系列选择（Enter、Space）
  • 图例导航和切换
  • 缩放和平移控件
  • 打印快捷键（Ctrl+P）
• 符合色彩对比度要求
• 支持移动设备
• Axe-core 验证集成
• 测试指南和最佳实践

序列化

📄 阅读： references/serialization.md

介绍图表状态的保存和加载功能，包括：

• SaveChart() 方法——序列化为 JSON 字符串
• LoadChartAsync() 方法——从 JSON 恢复
• 完整捕获图表状态（设置、系列、坐标轴、标题、样式）
• 存储选项（数据库、文件、LocalStorage、会话状态）
• 保存和加载按钮的实现
• 组件引用设置（@ref）
• 状态管理模式
• 版本兼容性注意事项
• 使用场景：用户偏好设置、仪表板配置、报告模板
• 错误处理和验证
• 完整的可运行示例

打印和导出

📄 阅读： references/print-export.md

介绍将图表导出为多种格式，包括：

• 支持的格式：PNG、JPEG、SVG、PDF、CSV、XLSX、PRINT
• ChartExportSettings 声明式配置
  • FileName 属性
  • 用于图像和 PDF 导出的 Width 和 Height
  • 用于 PDF 和打印的 Orientation（纵向/横向）
• 导出按钮集成
• 通过浏览器对话框实现打印功能
• Exporting 事件用于运行时自定义
  • ChartExportingEventArgs 属性
  • 动态文件命名
  • 有条件地取消导出
  • 运行时调整尺寸
  • 方向控制
• 特定格式的注意事项
• 分辨率和文件命名最佳实践
• 带事件处理的完整示例
• 导出问题的故障排除

API 参考

📄 阅读： references/api-reference.md

所有类、属性、方法和事件的完整 API 文档，包括：

• SfChartWizard 类
  • Width、Height、Theme 属性
  • EnableRtl、PropertyPanelExpanded
  • Exporting 事件
  • SaveChart()、LoadChartAsync() 方法
• ChartSettings 类
  • Datasource、CategoryFields、SeriesFields
  • 包含 15 种以上类型的 SeriesType 属性
• ChartExportSettings 类
  • FileName、Width、Height、Orientation
• ChartExportingEventArgs 类
  • 用于自定义导出的事件参数
• ChartWizardSeriesType 枚举
  • 所有可用的系列类型
• PageOrientation 枚举
  • Portrait 和 Landscape 选项

快速入门示例

下面是一个简单示例，帮助你开始使用 Chart Wizard 组件：

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard Width="100%" Height="500px">
    <ChartSettings DataSource="@Data"
                   CategoryFields="@CategoryList"
                   SeriesFields="@SeriesList"
                   SeriesType="ChartWizardSeriesType.Column">
    </ChartSettings>
</SfChartWizard>

@code {
    public class OlympicsData
    {
        public string Country { get; set; }
        public int Gold { get; set; }
        public int Silver { get; set; }
        public int Bronze { get; set; }
    }

    private readonly List<string> CategoryList = new() { "Country" };
    private readonly List<string> SeriesList = new() { "Gold", "Silver", "Bronze" };

    private List<OlympicsData> Data = new()
    {
        new OlympicsData { Country = "USA",   Gold = 40, Silver = 44, Bronze = 42 },
        new OlympicsData { Country = "China", Gold = 40, Silver = 27, Bronze = 24 },
        new OlympicsData { Country = "Japan", Gold = 20, Silver = 12, Bronze = 13 }
    };
}

常见模式

单系列图表

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard Width="100%" Height="500px">
    <ChartSettings DataSource="@SalesData"
                   CategoryFields="@CategoryList"
                   SeriesFields="@SeriesList"
                   SeriesType="ChartWizardSeriesType.Line">
    </ChartSettings>
</SfChartWizard>

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

    private List<SalesInfo> SalesData = new()
    {
        new SalesInfo { Month = "Jan", Sales = 100 },
        new SalesInfo { Month = "Feb", Sales = 120 },
        new SalesInfo { Month = "Mar", Sales = 140 }
    };

    private readonly List<string> CategoryList = new() { "Month" };
    private readonly List<string> SeriesList = new() { "Sales" };
}

使用主题的多系列图表

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard Theme="Theme.Fluent2" Width="100%" Height="500px">
    <ChartSettings DataSource="@OlympicsData"
                   CategoryFields="@CategoryList"
                   SeriesFields="@SeriesList"
                   SeriesType="ChartWizardSeriesType.Bar">
    </ChartSettings>
</SfChartWizard>

@code {
    private readonly List<string> CategoryList = new() { "Country" };
    private readonly List<string> SeriesList = new() { "Gold", "Silver", "Bronze" };

    public class OlympicsDataModel
    {
        public string Country { get; set; }
        public int Gold { get; set; }
        public int Silver { get; set; }
        public int Bronze { get; set; }
    }

    private List<OlympicsDataModel> OlympicsData = new()
    {
        new OlympicsDataModel { Country = "USA",   Gold = 40, Silver = 44, Bronze = 42 },
        new OlympicsDataModel { Country = "China", Gold = 40, Silver = 27, Bronze = 24 },
        new OlympicsDataModel { Country = "Japan", Gold = 20, Silver = 12, Bronze = 13 }
    };
}

配置导出

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard Width="100%" Height="500px">
    <ChartSettings DataSource="@ReportData"
                   CategoryFields="@CategoryList"
                   SeriesFields="@SeriesList"
                   SeriesType="ChartWizardSeriesType.Column">

        <ChartExportSettings FileName="QuarterlyReport"
                             Width="1024"
                             Height="768"
                             Orientation="Syncfusion.Blazor.ChartWizard.PageOrientation.Landscape" />
    </ChartSettings>
</SfChartWizard>

@code {
    private readonly List<string> CategoryList = new() { "Quarter" };
    private readonly List<string> SeriesList = new() { "Revenue", "Profit" };

    public class ReportItem
    {
        public string Quarter { get; set; }
        public double Revenue { get; set; }
        public double Profit { get; set; }
    }

    private List<ReportItem> ReportData = new()
    {
        new ReportItem { Quarter = "Q1", Revenue = 120000, Profit = 45000 },
        new ReportItem { Quarter = "Q2", Revenue = 150000, Profit = 60000 },
        new ReportItem { Quarter = "Q3", Revenue = 170000, Profit = 75000 },
        new ReportItem { Quarter = "Q4", Revenue = 200000, Profit = 90000 }
    };
}

折叠属性面板

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard Width="90%"
               Height="600px"
               PropertyPanelExpanded="false"
               Theme="Theme.Material3">

    <ChartSettings DataSource="@MyData"
                   CategoryFields="@CategoryFields"
                   SeriesFields="@SeriesFields"
                   SeriesType="ChartWizardSeriesType.Area">
    </ChartSettings>

</SfChartWizard>

@code {
    private readonly List<string> CategoryFields = new() { "CategoryName" };
    private readonly List<string> SeriesFields = new() { "Value1", "Value2" };

    public class MyItem
    {
        public string CategoryName { get; set; }
        public double Value1 { get; set; }
        public double Value2 { get; set; }
    }

    private List<MyItem> MyData = new()
    {
        new MyItem { CategoryName = "A", Value1 = 30, Value2 = 20 },
        new MyItem { CategoryName = "B", Value1 = 45, Value2 = 35 },
        new MyItem { CategoryName = "C", Value1 = 50, Value2 = 40 }
    };
}

关键属性

SfChartWizard 属性

属性	类型	默认值	描述
Width	string	"100%"	组件宽度（px 或 %）
Height	string	"100%"	组件高度（px 或 %）
Theme	Theme	Fluent2	视觉主题（Material、Fluent、Bootstrap、Tailwind 等）
EnableRtl	bool	false	启用从右到左的布局
PropertyPanelExpanded	bool	true	初始渲染时显示属性面板

ChartSettings 属性

属性	类型	必需	描述
DataSource	IEnumerable	是	图表的数据集合
CategoryFields	List	是	x 轴类别的字段名称
SeriesFields	List	是	数据系列的字段名称
SeriesType	ChartWizardSeriesType	否	图表类型（Line、Column、Bar、Area、Pie 等）

ChartExportSettings 属性

属性	类型	默认值	描述
FileName	string	""	导出文件的名称（不含扩展名）
Width	double	NaN	导出宽度，单位为像素
Height	double	NaN	导出高度，单位为像素
Orientation	PageOrientation	Portrait	PDF/打印的页面方向

常见用例

商业分析仪表板

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard Width="100%"
               Height="600px"
               Theme="Theme.Bootstrap5">

    <ChartSettings DataSource="@QuarterlySales"
                   CategoryFields="@CategoryFields"
                   SeriesFields="@SeriesFields"
                   SeriesType="ChartWizardSeriesType.StackingColumn">

        <ChartExportSettings FileName="QuarterlyAnalysis"
                             Orientation="Syncfusion.Blazor.ChartWizard.PageOrientation.Landscape" />
    </ChartSettings>

</SfChartWizard>

@code {
    private readonly List<string> CategoryFields = new() { "Quarter", "Region" };
    private readonly List<string> SeriesFields = new() { "Revenue", "Profit", "Expenses" };

    public class QuarterlySale
    {
        public string Quarter { get; set; }
        public string Region { get; set; }
        public double Revenue { get; set; }
        public double Profit { get; set; }
        public double Expenses { get; set; }
    }

    private List<QuarterlySale> QuarterlySales = new()
    {
        new QuarterlySale { Quarter = "Q1", Region = "North", Revenue = 150000, Profit = 50000, Expenses = 30000 },
        new QuarterlySale { Quarter = "Q2", Region = "North", Revenue = 170000, Profit = 60000, Expenses = 35000 },
        new QuarterlySale { Quarter = "Q3", Region = "South", Revenue = 160000, Profit = 55000, Expenses = 32000 },
        new QuarterlySale { Quarter = "Q4", Region = "South", Revenue = 180000, Profit = 65000, Expenses = 38000 }
    };
}

奥运会奖牌对比

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard Theme="Theme.Material3"
               PropertyPanelExpanded="true"
               Width="100%"
               Height="500px">

    <ChartSettings DataSource="@OlympicsMedals"
                   CategoryFields="@CategoryFields"
                   SeriesFields="@SeriesFields"
                   SeriesType="ChartWizardSeriesType.Bar">
    </ChartSettings>

</SfChartWizard>

@code {
    private readonly List<string> CategoryFields = new() { "Country" };
    private readonly List<string> SeriesFields = new() { "Gold", "Silver", "Bronze" };

    public class OlympicsMedalInfo
    {
        public string Country { get; set; }
        public int Gold { get; set; }
        public int Silver { get; set; }
        public int Bronze { get; set; }
    }

    private List<OlympicsMedalInfo> OlympicsMedals = new()
    {
        new OlympicsMedalInfo { Country = "USA",   Gold = 40, Silver = 44, Bronze = 42 },
        new OlympicsMedalInfo { Country = "China", Gold = 40, Silver = 27, Bronze = 24 },
        new OlympicsMedalInfo { Country = "Japan", Gold = 20, Silver = 12, Bronze = 13 }
    };
}

销售趋势可视化

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard Width="90%"
               Height="500px">

    <ChartSettings DataSource="@MonthlySales"
                   CategoryFields="@CategoryFields"
                   SeriesFields="@SeriesFields"
                   SeriesType="ChartWizardSeriesType.Line">
    </ChartSettings>

</SfChartWizard>

@code {
    private readonly List<string> CategoryFields = new() { "Month" };
    private readonly List<string> SeriesFields = new() { "CurrentYear", "PreviousYear" };

    public class SalesRecord
    {
        public string Month { get; set; }
        public double CurrentYear { get; set; }
        public double PreviousYear { get; set; }
    }

    private List<SalesRecord> MonthlySales = new()
    {
        new SalesRecord { Month = "Jan", CurrentYear = 12000, PreviousYear = 10000 },
        new SalesRecord { Month = "Feb", CurrentYear = 13500, PreviousYear = 11000 },
        new SalesRecord { Month = "Mar", CurrentYear = 15000, PreviousYear = 12500 }
    };
}

多类别人口数据

@using Syncfusion.Blazor.ChartWizard

<SfChartWizard EnableRtl="false"
               Theme="Theme.Fluent2"
               Width="100%"
               Height="500px">

    <ChartSettings DataSource="@CityPopulation"
                   CategoryFields="@CategoryFields"
                   SeriesFields="@SeriesFields"
                   SeriesType="ChartWizardSeriesType.Column">
    </ChartSettings>

</SfChartWizard>

@code {
    private readonly List<string> CategoryFields = new() { "City", "Country" };
    private readonly List<string> SeriesFields = new() { "Population" };

    public class PopulationInfo
    {
        public string City { get; set; }
        public string Country { get; set; }
        public double Population { get; set; }
    }

    private List<PopulationInfo> CityPopulation = new()
    {
        new PopulationInfo { City = "Tokyo",       Country = "Japan",  Population = 37.4 },
        new PopulationInfo { City = "Delhi",       Country = "India",  Population = 31.0 },
        new PopulationInfo { City = "Shanghai",    Country = "China",  Population = 27.0 },
        new PopulationInfo { City = "São Paulo",   Country = "Brazil", Population = 22.0 }
    };
}

可用图表类型（SeriesType）

• Line - 连接数据点的折线图
• StackingLine - 堆积折线图
• StackingLine100 - 100% 堆积折线图
• Column - 纵向柱状图
• StackingColumn - 堆积柱状图
• StackingColumn100 - 100% 堆积柱状图
• Bar - 横向条形图
• StackingBar - 堆积条形图
• StackingBar100 - 100% 堆积条形图
• Area - 带填充区域的面积图
• StackingArea - 堆积面积图
• StackingArea100 - 100% 堆积面积图
• Scatter - 使用独立标记的散点图
• Pie - 表示比例的圆形饼图

前提条件

• .NET SDK 6.0 或更高版本
• Syncfusion Blazor 许可证（试用版或商业版）
• Blazor Server、WebAssembly 或 Web App 项目
• Visual Studio 2022、VS Code 或 .NET CLI

包要求

dotnet add package Syncfusion.Blazor.ChartWizard

命名空间导入

@using Syncfusion.Blazor
@using Syncfusion.Blazor.ChartWizard

服务注册

// Program.cs
builder.Services.AddSyncfusionBlazor();

脚本引用

<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js" type="text/javascript"></script>

后续步骤

1. 选择 Blazor 应用类型（Server、WASM 或 Web App）
2. 阅读相应的入门指南
3. 使用数据模型配置数据绑定
4. 使用主题和属性自定义外观
5. 根据需要实现导出和序列化
6. 确保符合生产环境的无障碍要求

相关组件

• Syncfusion Blazor Charts - 用于通过编程创建图表，无需使用向导界面
• Syncfusion Blazor DataGrid - 用于以表格形式可视化数据
• Syncfusion Blazor Dashboard Layout - 用于排列多个图表

支持资源

• 官方文档
• API 参考
• 在线演示
• 社区论坛