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	アニメーションの時間（ms）
AnimationDelay	double	0	アニメーションの遅延（ms）

アクセシビリティと操作のプロパティ

プロパティ	型	デフォルト	説明
EnableRTL	bool	false	右から左へのレイアウトを有効にします
TabIndex	double	0	キーボードのタブインデックス
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	None	Task	コンポーネントを再レンダリングします

設定オブジェクト

• 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）

データモデル

モデル	主なプロパティ	説明
SankeyDataNode	Id、Label（SankeyDataLabel）、Color、Width	ノードを表します
SankeyDataLabel	Text	ノードのラベルテキスト
SankeyDataLink	SourceId、TargetId、Value、Color、Opacity	リンク／接続を表します

列挙型

列挙型	値	説明
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 を参照していることを確認します
• 値には正の数を指定します
• 明確さを保つため、循環フロー（ノード A → B → A）は避けます
• ノード Id は大文字と小文字を区別します

トラブルシューティングの簡単なヒント

図が表示されない場合：

• Nodes と Links が適切に初期化されていることを確認します
• SfSankey に Width と Height が設定されていることを確認します
• Syncfusion サービスが Program.cs に登録されていることを確認します

リンクが表示されない場合：

• SourceId と TargetId が既存のノード Id と完全に一致していることを確認します
• Value が 0 より大きいことを確認します
• Links コレクションがコンポーネントにバインドされていることを確認します

スタイルが適用されない場合：

• テーマの CSS が App.razor またはレイアウトで参照されていることを確認します
• 競合する 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/