syncfusion-blazor-sankey

实现 Syncfusion Blazor Sankey Diagram

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

一份全面的指南，介绍如何实现 Syncfusion Blazor Sankey Diagram 组件。Sankey 图是一种强大的可视化工具，用于展示类别之间的流向和关系，并通过按比例调整宽度的连线显示流量的大小和方向。

何时使用此指南

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

• 可视化不同类别或阶段之间的流向和关系
• 展示系统中的能源或资源流向（电力、水、材料）
• 显示实体之间的数据流动（网站流量、用户旅程、数据管道）
• 呈现预算或财务流向（收入／支出、资源分配）
• 映射供应链或物流流向（产品流动、配送）
• 创建可量化流量的流程图
• 分析网络流量（数据传输、通信模式）
• 展示带有流失可视化的转化漏斗
• 实现 SfSankey Blazor 组件
• 使用流量数据结构（节点和连线）
• 自定义 Sankey 图的外观和行为
• 处理用于流量探索的交互事件
• 导出或打印流量图

组件概述

什么是 Sankey 图？

Sankey 图是一种流向图，其中箭头或连接的宽度与流量大小成正比。它由以下部分组成：

• 节点：流中的实体、类别或阶段（例如，能源来源、流程步骤）
• 连线：展示节点之间流向和流量大小的连接
• 流量宽度：数量／流量大小的可视化表示（越宽 = 流量越大）

主要功能

• 由节点和连线集合驱动的数据可视化
• 可配置方向（水平／垂直）的自动布局
• 丰富的自定义选项，可设置节点、连线、标签和图例
• 用于单击、悬停和自定义渲染的交互事件
• 悬停时显示流量详情的工具提示
• 打印和导出功能（PNG、JPEG、SVG、PDF）
• 符合 WCAG 2.2 标准的无障碍设计
• 支持动态调整大小的响应式设计

文档与导航指南

入门

📄 阅读： references/getting-started.md
阅读时机： 初次设置、安装、项目配置
内容包括：

• NuGet 包安装（Syncfusion.Blazor.Sankey）
• 服务注册和命名空间导入
• CSS 主题和脚本引用
• 基本 Sankey 图实现
• 完整的最小可运行示例
• 设置故障排查

数据绑定

📄 阅读： references/data-binding.md
阅读时机： 设置数据结构、绑定节点和连线、集成 API
内容包括：

• 了解 SankeyDataNode 和 SankeyDataLink 模型
• 创建节点和连线集合
• 将数据绑定到 Sankey 组件
• REST API 集成模式
• JSON 数据结构示例
• 动态数据更新

节点配置

📄 阅读： references/nodes.md
阅读时机： 自定义节点外观、样式和属性
内容包括：

• 节点基础知识和结构
• 节点 ID 和标签配置
• 使用 SankeyNodeSettings 设置节点样式
• 颜色、宽度和内边距属性
• 节点定位和布局
• 完整的节点示例

连线配置

📄 阅读： references/links.md
阅读时机： 配置流量连接、连线样式和流量大小表示
内容包括：

• 连线基础知识和流量表示
• SourceId、TargetId 和 Value 属性
• 使用 SankeyLinkSettings 设置连线样式
• 颜色、不透明度和描边属性
• 流量方向和大小
• 多路径流量示例

标签自定义

📄 阅读： references/labels.md
阅读时机： 自定义节点标签、文本格式
包含内容：

• 标签配置和定位
• 字体属性（大小、粗细、字体系列、颜色）
• 文本格式化和截断
• 标签可见性控制
• 自定义标签示例

图例配置

📄 阅读： references/legends.md
阅读时机： 添加和自定义图表图例
包含内容：

• 使用 SankeyLegendSettings 配置图例
• 可见性和定位选项
• 图例项自定义
• 形状和颜色映射
• 交互式图例行为
• LegendItemRendering 事件

工具提示

📄 阅读： references/tooltips.md
阅读时机： 添加交互式工具提示、自定义工具提示内容
包含内容：

• 工具提示配置和触发方式
• 自定义工具提示模板
• 区分节点和链接的工具提示
• TooltipRendering 事件
• 格式化工具提示内容
• 样式示例

API 参考

📄 阅读： references/api-reference.md
阅读时机： 查询组件属性、事件、方法和枚举
包含内容：

• 完整的 SfSankey 组件 API 文档
• 所有属性及其类型和默认值
• 全部 16 个事件及其事件参数
• 所有公共方法（Export、Print、Refresh）
• 数据模型类（SankeyDataNode、SankeyDataLink、SankeyDataLabel）
• 设置组件（Node、Link、Label、Legend、Tooltip）
• 枚举和事件参数
• 完整的组件层次结构
• 完整的可运行示例

自定义

📄 阅读： references/customization.md
阅读时机： 高级样式设置、布局选项、主题、RTL 支持
包含内容：

• 背景样式设置（颜色和图像）
• 图表尺寸和大小设置
• 布局方向（水平/垂直）
• RTL（从右到左）支持
• 主题集成
• 自定义 CSS 类
• 响应式设计模式

事件和交互

📄 阅读： references/events.md
阅读时机： 处理用户交互、自定义渲染、响应变化
包含内容：

• 完整的事件参考（16 个事件）
• 渲染事件（NodeRendering、LinkRendering、LabelRendering）
• 交互事件（NodeClick、LinkClick）
• 悬停事件（NodeEnter/Leave、LinkEnter/Leave）
• 生命周期事件（Created、SizeChanged）
• 导出事件（PrintCompleted、ExportCompleted）
• 事件参数结构和示例

打印和导出

📄 阅读： references/print-export.md
阅读时机： 将图表导出为图像/PDF、使用打印功能
包含内容：

• 打印 Sankey 图
• 导出格式（PNG、JPEG、SVG、PDF）
• 导出方法配置
• 文件命名和质量设置
• 打印/导出事件
• 完整的可运行示例

快速入门示例

以下是一个简要示例，展示能源来源流向能源类型和最终使用部门：

@page "/sankey-demo"
@using Syncfusion.Blazor.Sankey

<SfSankey Width="100%" Height="600px" Nodes="@Nodes" Links="@Links">
    <SankeyNodeSettings Width="20" Padding="20"></SankeyNodeSettings>
    <SankeyLinkSettings Opacity="0.4"></SankeyLinkSettings>
</SfSankey>

@code {
    public List<SankeyDataNode> Nodes = new List<SankeyDataNode>();
    public List<SankeyDataLink> Links = new List<SankeyDataLink>();

    protected override void OnInitialized()
    {
        // Define nodes
        Nodes = new List<SankeyDataNode>()
        {
            new SankeyDataNode() { Id = "Solar", Label = new SankeyDataLabel() { Text = "Solar" } },
            new SankeyDataNode() { Id = "Wind", Label = new SankeyDataLabel() { Text = "Wind" } },
            new SankeyDataNode() { Id = "Hydro", Label = new SankeyDataLabel() { Text = "Hydro" } },
            new SankeyDataNode() { Id = "Electricity", Label = new SankeyDataLabel() { Text = "Electricity" } },
            new SankeyDataNode() { Id = "Heat", Label = new SankeyDataLabel() { Text = "Heat" } },
            new SankeyDataNode() { Id = "Residential", Label = new SankeyDataLabel() { Text = "Residential" } },
            new SankeyDataNode() { Id = "Commercial", Label = new SankeyDataLabel() { Text = "Commercial" } },
            new SankeyDataNode() { Id = "Industrial", Label = new SankeyDataLabel() { Text = "Industrial" } }
        };

        // Define links (flows)
        Links = new List<SankeyDataLink>()
        {
            new SankeyDataLink() { SourceId = "Solar", TargetId = "Electricity", Value = 30 },
            new SankeyDataLink() { SourceId = "Wind", TargetId = "Electricity", Value = 45 },
            new SankeyDataLink() { SourceId = "Hydro", TargetId = "Electricity", Value = 25 },
            new SankeyDataLink() { SourceId = "Solar", TargetId = "Heat", Value = 15 },
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Residential", Value = 35 },
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Commercial", Value = 30 },
            new SankeyDataLink() { SourceId = "Electricity", TargetId = "Industrial", Value = 35 },
            new SankeyDataLink() { SourceId = "Heat", TargetId = "Residential", Value = 10 },
            new SankeyDataLink() { SourceId = "Heat", TargetId = "Commercial", Value = 5 }
        };
    }
}

常见模式

模式 1：简单流程图

<SfSankey Nodes="@Nodes" Links="@Links" Width="800px" Height="400px">
</SfSankey>

模式 2：使用自定义颜色设置样式的 Sankey 图

<SfSankey Nodes="@Nodes" Links="@Links" BackgroundColor="#f5f5f5">
    <SankeyNodeSettings Color="#2e7d32" Width="15" Padding="25"></SankeyNodeSettings>
    <SankeyLinkSettings Color="#1976d2" Opacity="0.3"></SankeyLinkSettings>
    <SankeyLabelSettings Color="#000000" FontSize="14px" FontWeight="500"></SankeyLabelSettings>
</SfSankey>

模式 3：带事件交互的 Sankey 图

<SfSankey Nodes="@Nodes" Links="@Links" NodeClick="OnNodeClick" LinkClick="OnLinkClick">
    <SankeyTooltipSettings Visible="true"></SankeyTooltipSettings>
</SfSankey>

@code {
    private void OnNodeClick(NodeClickEventArgs args)
    {
        Console.WriteLine($"Node clicked: {args.Node.Id}");
    }

    private void OnLinkClick(LinkClickEventArgs args)
    {
        Console.WriteLine($"Link clicked: {args.Link.SourceId} -> {args.Link.TargetId}");
    }
}

模式 4：垂直布局

<SfSankey Nodes="@Nodes" Links="@Links" Orientation="SankeyOrientation.Vertical">
    <SankeyNodeSettings Width="30" Padding="15"></SankeyNodeSettings>
</SfSankey>

模式 5：带图例

<SfSankey Nodes="@Nodes" Links="@Links">
    <SankeyLegendSettings Visible="true" Position="LegendPosition.Bottom"></SankeyLegendSettings>
</SfSankey>

完整 API 属性参考

SfSankey 组件属性

数据属性

属性	类型	默认值	描述
Nodes	List<SankeyDataNode>	null	节点（实体/类别）集合
Links	List<SankeyDataLink>	null	链接（节点之间的流）集合

布局与尺寸属性

属性	类型	默认值	描述
Width	string	"100%"	图表宽度（像素或百分比）
Height	string	"100%"	图表高度（像素或百分比）
Orientation	SankeyOrientation	Auto	布局方向（Auto/Horizontal/Vertical）
EnableAutoLayout	bool	true	启用/禁用自动布局

样式属性

属性	类型	默认值	描述
BackgroundColor	string	Theme default	背景颜色
BackgroundImage	string	""	背景图片 URL
BorderColor	string	null	边框颜色
BorderWidth	double	1	边框宽度（像素）
Theme	Theme	Fluent2	图表主题
CssClass	string	""	自定义 CSS 类

标题与内容属性

属性	类型	默认值	描述
Title	string	""	主标题文本
SubTitle	string	""	副标题文本
LinkCurvature	double	1	连线曲线强度（0-1）

动画属性

属性	类型	默认值	描述
EnableAnimation	bool	true	启用/禁用动画
AnimationDuration	double	2000	动画时长（毫秒）
AnimationDelay	double	0	动画延迟（毫秒）

无障碍与交互属性

属性	类型	默认值	描述
EnableRTL	bool	false	启用从右到左布局
TabIndex	double	0	键盘 Tab 索引
AccessibilityDescription	string	""	无障碍描述
ID	string	Auto-generated	组件 ID

事件参考（共 16 个事件）

渲染事件

• NodeRendering - SankeyNodeRenderEventArgs - 节点渲染时触发
• LinkRendering - SankeyLinkRenderEventArgs - 连线渲染时触发
• LabelRendering - SankeyLabelRenderEventArgs - 标签渲染时触发
• LegendItemRendering - SankeyLegendRenderEventArgs - 图例项渲染前触发

鼠标交互事件

• NodeClick - SankeyNodeEventArgs - 单击节点时触发
• LinkClick - SankeyLinkEventArgs - 单击连线时触发
• NodeEnter - SankeyNodeEventArgs - 鼠标进入节点时触发
• NodeLeave - SankeyNodeEventArgs - 鼠标离开节点时触发
• LinkEnter - SankeyLinkEventArgs - 鼠标进入连线时触发
• LinkLeave - SankeyLinkEventArgs - 鼠标离开连线时触发

UI 事件

• TooltipRendering - SankeyTooltipRenderEventArgs - 工具提示渲染时触发
• LegendItemHover - SankeyLegendItemHoverEventArgs - 悬停在图例上时触发

生命周期事件

• Created - Action - 组件创建时触发
• SizeChanged - SankeySizeChangedEventArgs - 组件尺寸变化时触发

导出/打印事件

• PrintCompleted - Action - 打印完成时触发
• ExportCompleted - SankeyExportedEventArgs - 导出完成时触发

公共方法

方法	参数	返回值	描述
ExportAsync	type (SankeyExportType), fileName, orientation?, allowDownload?, isBase64?	Task	导出为 PNG/JPEG/SVG/PDF
PrintAsync	elementRef?	Task	打印图表
RefreshAsync	无	Task	重新渲染组件

Settings Objects

• SankeyNodeSettings：节点外观（Width、Padding、Alignment、Color、Offset）
• SankeyLinkSettings：连接外观（Color、Opacity、HighlightOpacity、InactiveOpacity、ColorType）
• SankeyLabelSettings：标签样式（Visible、FontSize、FontFamily、FontWeight、Color、Padding）
• SankeyMargin：图表边距（Left、Right、Top、Bottom）
• SankeyTitleStyle：标题样式（FontSize、FontFamily、FontWeight、FontStyle、Color）
• SankeySubtitleStyle：副标题样式（FontSize、FontFamily、FontWeight、FontStyle、Color）
• SankeyLegendSettings：图例配置（Visible、Position、Height、Width）
• SankeyTooltipSettings：工具提示配置（Enable、Fill、Opacity）

Data Models

Model	Key Properties	Description
SankeyDataNode	Id、Label (SankeyDataLabel)、Color、Width	表示一个节点
SankeyDataLabel	Text	节点标签文本
SankeyDataLink	SourceId、TargetId、Value、Color、Opacity	表示一条连接

Enums

Enum	Values	Description
SankeyOrientation	Auto、Horizontal、Vertical	布局方向
SankeyNodeAlign	None、Left、Center、Right	节点对齐方式
SankeyColorType	Static、Source	颜色映射类型
SankeyLegendPosition	Top、Bottom、Left、Right	图例位置
SankeyExportType	PNG、JPEG、SVG、PDF	导出格式
Theme	Bootstrap5、Fluent2、Material、Tailwind、Fabric 等	图表主题

常见用例

用例 1：能源流可视化

可视化能源来源流向不同能源类型，再流向最终使用部门（住宅、商业、工业）的过程。

用例 2：网站流量分析

展示用户流量从入口点（搜索、社交媒体、直接访问）经过各个页面，最终流向转化目标的过程。

用例 3：预算分配

展示预算从收入来源经过各个类别，最终流向各项支出的过程。

用例 4：供应链流转

展示产品从供应商经过制造环节，最终流向分销渠道的过程。

用例 5：用户旅程映射

映射用户在应用程序各个状态间的流转，展示每个阶段的流失和转化情况。

用例 6：数据管道可视化

展示数据在 ETL 管道或数据转换工作流中经过各个处理阶段的流转情况。

数据结构要求

节点

每个节点必须包含：

• 唯一的 Id（字符串）
• 带有 Text 属性的 Label

连接

每条连接必须包含：

• 与某个节点 Id 匹配的 SourceId
• 与某个节点 Id 匹配的 TargetId
• 表示流量大小的 Value（数值）

验证提示

• 确保所有连接的 SourceId 和 TargetId 都引用现有节点 Id
• Value 应为正数
• 为保持清晰，请避免循环流（节点 A → B → A）
• 节点 Id 区分大小写

快速故障排除提示

图表未显示：

• 确认 Nodes 和 Links 已正确初始化
• 检查 SfSankey 是否已设置 Width 和 Height
• 确保已在 Program.cs 中注册 Syncfusion 服务

连接未显示：

• 确认 SourceId 和 TargetId 与现有节点 Id 完全匹配
• 检查 Value 是否大于 0
• 确认 Links 集合已绑定到组件

样式未生效：

• 确保在 App.razor 或布局中引用了主题 CSS
• 检查是否存在冲突的 CSS 样式
• 确认颜色格式有效（hex、rgb、命名颜色）

事件未触发：

• 确认事件处理程序的方法签名与事件参数类型匹配
• 检查组件标记中是否已正确绑定事件
• 确认 .NET 8+ 项目的组件交互模式

后续步骤

有关特定功能的详细实现，请参阅上方导航指南中列出的参考文件。每个参考文件都提供完整、独立的文档，包含示例和最佳实践。

资源

文档与参考资料

• 官方文档：https://blazor.syncfusion.com/documentation/sankey-chart/getting-started
• 组件演示：https://blazor.syncfusion.com/demos/sankey-chart/default-functionalities
• 官方 API 参考：https://help.syncfusion.com/cr/blazor/Syncfusion.Blazor.Sankey.html
• 本地 API 参考：references/api-reference.md - 全面的本地 API 文档，涵盖所有属性、事件、方法和示例

社区与支持

• GitHub 示例：https://github.com/SyncfusionExamples/
• 支持：https://www.syncfusion.com/support/
• NuGet 包：https://www.nuget.org/packages/Syncfusion.Blazor.Sankey/