syncfusion-wpf-kanban-board

Syncfusion WPF Kanban（SfKanban）の実装

このスキルでは、タスクをワークフローの各段階を表す列にカードとして整理して表示する、強力なビジュアルワークフロー管理システムである Syncfusion® WPF Kanban（SfKanban）コントロールの実装について、包括的なガイダンスを提供します。

このスキルを使用するタイミング

次の場合は、すぐにこのスキルを使用してください：

• タスクやプロジェクト管理用のカンバンボードを作成したい場合
• ワークフローの可視化システム（未着手、進行中、完了）を構築する場合
• アジャイルプロジェクト管理ボードを実装する場合
• ワークフローの各段階に仕掛かり作業（WIP）の上限を設定する必要がある場合
• ドラッグアンドドロップ機能を備えたタスクボードを作成する場合
• スイムレーンを使って、チーム、プロジェクト、カスタム条件ごとにタスクを整理する場合
• ソフトウェア開発のワークフローや課題追跡システムを管理する場合
• 複数の段階にわたるタスクの状態を可視化する必要がある場合

コンポーネントの概要

Syncfusion WPF Kanban（SfKanban）は、完了までの各段階におけるワークフローを効率的に可視化します。次の機能を備えています：

主な機能：

• カード：タイトル、説明、タグ、画像、優先度インジケーターを含むタスクの視覚的表現
• 列：作業をワークフローの段階（例：未着手、進行中、完了）に整理
• スイムレーン：プロジェクト、チーム、ユーザー、カスタムカテゴリごとにカードをグループ化
• 仕掛かり作業（WIP）の上限：過負荷を防ぐため、列ごとにタスクの最小数と最大数を設定
• ドラッグアンドドロップ：列やスイムレーン間でカードを直感的に移動。複数カードの一括ドラッグアンドドロップにも対応
• カード選択：選択したカードの外観をカスタマイズできる、単一および複数カードの選択
• 列の並べ替え：ドラッグアンドドロップによる列の並べ替え
• ワークフロー：特定の状態間で許可するカードの遷移を定義
• 並べ替え：優先度、日付、カスタムフィールドで列内のカードを整理
• イベント：カード操作（タップ、ドラッグ、ドロップ）に対応する豊富なイベントモデル
• カスタマイズ：カード、ヘッダー、スイムレーンに対応する幅広いテンプレート
• テーマ：システムと連携するライトテーマとダークテーマを標準搭載
• ローカライズとRTL：複数言語と右から左への表示に対応

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

次の内容が必要な場合に使用してください：

• NuGet による初期設定とインストール
• 基本的なカンバンボードの作成
• ItemsSource バインディングの理解
• 既定の KanbanModel とカスタムデータモデルの使い分け
• 列の自動生成または手動定義の設定
• テーマ、ローカライズ、RTL サポートの適用

カードの設定

📄 参照： references/cards.md

次の内容が必要な場合に使用してください：

• カードの構造とプロパティの理解
• CardTemplate によるカードの外観のカスタマイズ
• カードのインジケーターとタグの操作
• 条件に応じたカードテンプレート（CardTemplateSelector）の実装
• カードのツールチップの有効化とカスタマイズ
• 単一または複数のカードの選択（CardSelectionType）
• タスクの一括移動に使う複数カードのドラッグアンドドロップ
• 選択したカードの外観のカスタマイズ（SelectedBorderBrush）
• 選択したカードのプログラムによる取得（GetSelectedCards）
• カードの表示に関する問題のトラブルシューティング

列の管理

📄 参照： references/columns.md

次の内容が必要な場合に使用してください：

• 列幅の設定（最小、最大、固定）
• 列の自動生成と手動定義の使い分け
• カテゴリと列のマッピング
• 列ヘッダーのカスタマイズ
• プログラムによる列の展開と折りたたみ
• 列ごとのドラッグアンドドロップの有効化と無効化
• ドラッグアンドドロップによる列の並べ替えの有効化（AllowColumnReorder）
• 複数カテゴリの列の設定
• 視覚的インジケーターを使用したWIP（仕掛かり作業）の上限設定
• ドラッグ／ドロップ時のプレースホルダーの外観のカスタマイズ

スイムレーンによる整理

📄 参照： references/swimlanes.md

次のような場合に使用します：

• カードをチーム、プロジェクト、またはユーザーごとにグループ化する
• スイムレーンを有効化して設定する
• スイムレーンのプロパティ（SwimlaneKey）をマッピングする
• スイムレーンのヘッダーの外観をカスタマイズする
• 階層的なカード整理を作成する
• チームまたはプロジェクトごとのビューを実装する

ワークフローと遷移

📄 参照： references/workflows.md

次のような場合に使用します：

• 列間で許可するカードの遷移を定義する
• 特定の状態間でのカードの移動を制限する
• ワークフローの検証ルールを実装する
• 特定の列へのドラッグ＆ドロップを防止する
• ステートマシンのようなワークフローを作成する
• 複雑なワークフローの遷移を管理する

カードの並べ替え

📄 参照： references/sorting.md

次のような場合に使用します：

• 列内のカードを優先度、日付、またはカスタムフィールドで並べ替える
• カスタムフィールドの並べ替え（昇順／降順）を実装する
• 正確な位置指定のためにインデックスベースの並べ替えを設定する
• ドラッグ＆ドロップ後に並べ替え順を動的に更新する
• 並べ替えの変更後に列の表示を更新する
• カスタムデータモデルでの並べ替えについて理解する

イベントと操作

📄 参照： references/events.md

次のような場合に使用します：

• カードのタップイベント（CardTapped）を処理する
• ドラッグイベント（CardDragStarting、CardDragOver）に応答する
• カードのドロップイベント（CardDrop）を処理する
• MVVM コマンド（CardTappedCommand）を実装する
• イベント引数とカードデータにアクセスする
• ドラッグ＆ドロップの動作を防止またはカスタマイズする
• カードの選択イベント（CardSelected、CardDeselected）を処理する
• 列の並べ替えイベント（ColumnDragStarting、ColumnDragOver、ColumnDrop）を処理する
• カード操作時のビジネスロジックを実装する

クイックスタートの例

基本的なカンバンの設定

<Window xmlns:kanban="clr-namespace:Syncfusion.UI.Xaml.Kanban;assembly=Syncfusion.SfKanban.WPF">
    <kanban:SfKanban x:Name="kanban" 
                     ItemsSource="{Binding TaskDetails}">
        <kanban:SfKanban.DataContext>
            <local:ViewModel/>
        </kanban:SfKanban.DataContext>
    </kanban:SfKanban>
</Window>

KanbanModel を使用する ViewModel

using Syncfusion.UI.Xaml.Kanban;

public class ViewModel
{
    public ObservableCollection<KanbanModel> TaskDetails { get; set; }

    public ViewModel()
    {
        TaskDetails = new ObservableCollection<KanbanModel>
        {
            new KanbanModel
            {
                Title = "UWP Issue",
                ID = "651",
                Description = "Fix crosshair label template issue",
                Category = "Open",
                ColorKey = "High",
                Tags = new string[] { "Bug Fixing" }
            },
            new KanbanModel
            {
                Title = "Kanban Feature",
                ID = "25678",
                Description = "Implement drag and drop support",
                Category = "In Progress",
                ColorKey = "Normal",
                Tags = new string[] { "New Feature" }
            }
        };
    }
}

列の手動定義

<kanban:SfKanban AutoGenerateColumns="False" 
                 ItemsSource="{Binding TaskDetails}">
    <kanban:KanbanColumn Title="To Do" Categories="Open" />
    <kanban:KanbanColumn Title="In Progress" Categories="In Progress" />
    <kanban:KanbanColumn Title="Done" Categories="Done" />
</kanban:SfKanban>

よくあるパターン

パターン 1：列の自動生成

条件： データから列を生成してすばやく設定したい場合

// Columns automatically generated from Category property values
kanban.AutoGenerateColumns = true;
kanban.ItemsSource = viewModel.TaskDetails;

結果： データ内の一意な Category 値に基づいて列が自動的に作成されます

パターン 2：視覚的なインジケーターを使った WIP 制限

条件： ステージごとのタスク数を制限し、視覚的なフィードバックを表示したい場合

<kanban:KanbanColumn Title="In Progress" 
                     Categories="In Progress"
                     MinimumLimit="2" 
                     MaximumLimit="5" />

結果：

• 件数が MaximumLimit を超えると、エラーバーが赤色で表示されます
• 件数が MinimumLimit を下回ると、エラーバーが黄色で表示されます
• ワークフローのボトルネックの防止に役立ちます

パターン 3：カスタムカードテンプレート

条件： デフォルト以外のカードの外観が必要な場合

<kanban:SfKanban.CardTemplate>
    <DataTemplate>
        <Border Background="#F3CFCE" 
                BorderThickness="1" 
                CornerRadius="3">
            <StackPanel Margin="10">
                <TextBlock Text="{Binding Title}" 
                          FontWeight="Bold" 
                          FontSize="14" />
                <TextBlock Text="{Binding Description}" 
                          FontSize="12" 
                          TextWrapping="Wrap" />
            </StackPanel>
        </Border>
    </DataTemplate>
</kanban:SfKanban.CardTemplate>

DataContext： KanbanModel インスタンス

パターン 4：チーム別のスイムレーン

条件： カードをチームまたはプロジェクトごとに整理したい場合

<kanban:SfKanban SwimlaneKey="Assignee" 
                 ItemsSource="{Binding TaskDetails}">
    
</kanban:SfKanban>

結果： 一意な Assignee 値ごとに 1 行ずつ、水平のスイムレーンが表示されます

パターン 5：ワークフローの制限

条件： 特定のカード遷移ルールを適用したい場合

<kanban:SfKanban.Workflows>
    <kanban:KanbanWorkflow Category="Open">
        <kanban:KanbanWorkflow.AllowedTransitions>
            <x:String>In Progress</x:String>
        </kanban:KanbanWorkflow.AllowedTransitions>
    </kanban:KanbanWorkflow>
    <kanban:KanbanWorkflow Category="In Progress">
        <kanban:KanbanWorkflow.AllowedTransitions>
            <x:String>Done</x:String>
            <x:String>Won't Fix</x:String>
        </kanban:KanbanWorkflow.AllowedTransitions>
    </kanban:KanbanWorkflow>
</kanban:SfKanban.Workflows>

結果：

• 「Open」のカードは「In Progress」にのみ移動できます
• 「In Progress」のカードは「Done」または「Won't Fix」にのみ移動できます
• 無効な状態遷移を防止します

パターン 6：カスタムデータモデル

条件： KanbanModel を使用せず、既存のデータモデルを使用する場合

// Custom model
public class TaskDetails
{
    public string Title { get; set; }
    public string Description { get; set; }
    public string Status { get; set; }
}

// XAML
<kanban:SfKanban ItemsSource="{Binding Tasks}"
                 ColumnMappingPath="Status">
    <kanban:SfKanban.CardTemplate>
        
    </kanban:SfKanban.CardTemplate>
</kanban:SfKanban>

重要： カスタムモデルを使用する場合は、CardTemplate を定義する必要があります

パターン 7：複数カードの選択と一括ドラッグ＆ドロップ

条件： 複数のカードを選択して、まとめてステージ間で移動したい場合

<kanban:SfKanban CardSelectionType="Multiple"
                 ItemsSource="{Binding TaskDetails}">
    <kanban:SfKanban.CardStyle>
        <kanban:KanbanCardStyle SelectedBorderBrush="Blue"
                                HoverBorderBrush="LightGray"/>
    </kanban:SfKanban.CardStyle>
</kanban:SfKanban>

結果：

• Ctrl + Click で個々のカードを選択に追加／削除できます
• Shift + Click で同じ列内のカード範囲を選択できます
• 選択したカードのいずれかをドラッグすると、選択中のすべてのカードが 1 つの操作として移動します
• ドロップ後も、選択したカードの相対的な順序は維持されます
• 無効なワークフロー遷移が発生すると、ドラッグ操作全体がキャンセルされます

コードで選択内容を取得する：

var selectedCards = kanban.GetSelectedCards();

パターン 8：列の並べ替え

使用する場面： 実行時にワークフローのステージを並べ替える必要がある場合

<kanban:SfKanban AllowColumnReorder="True"
                 AutoGenerateColumns="False"
                 ItemsSource="{Binding TaskDetails}">
    <kanban:KanbanColumn Title="To Do" Categories="Open" />
    <kanban:KanbanColumn Title="In Progress" Categories="In Progress" />
    <kanban:KanbanColumn Title="Done" Categories="Done" />
</kanban:SfKanban>

結果：

• 列ヘッダーをドラッグすると、列全体（ヘッダーとカード）が移動します
• 列はドロップした位置に挿入され、ほかの列は順に移動します
• AllowColumnReorder を設定しない場合は無効になります（既定値：false）

主なプロパティ

SfKanban のプロパティ

プロパティ	型	目的	使用する場面
ItemsSource	object	カードのデータソース	常に使用（必須）
AutoGenerateColumns	bool	Category から列を自動作成	手軽な設定とカスタム制御の使い分け
Columns	Collection	列を手動で定義	AutoGenerateColumns = false の場合
ColumnMappingPath	string	列の分類に使用するプロパティ	カスタムモデル（既定値："Category"）
SwimlaneKey	string	スイムレーンのグループ化に使用するプロパティ	チームやプロジェクトごとの整理
CardTemplate	DataTemplate	カードの外観をカスタマイズ	カスタムデータモデルやスタイル設定
ColumnHeaderTemplate	DataTemplate	列ヘッダーをカスタマイズ	ブランディングや追加情報の表示
SwimlaneHeaderTemplate	DataTemplate	スイムレーンヘッダーをカスタマイズ	スイムレーンの表示をカスタマイズ
MinColumnWidth	double	列の最小幅	レスポンシブレイアウト
MaxColumnWidth	double	列の最大幅	列のサイズ調整
ColumnWidth	double	列の固定幅	列幅の統一
SortingMappingPath	string	カードの並べ替えに使用するプロパティ	優先度や日付によるカードの並べ替え
SortingOrder	enum	昇順または降順	並べ替えの方向
Workflows	Collection	許可するカードの遷移	ワークフローの検証
IndicatorColorPalette	Collection	インジケーターの色の対応付け	優先度やステータスの色
IsToolTipEnabled	bool	カードのツールチップを有効化	カードにホバーしたときの追加情報
CardSelectionType	KanbanCardSelectionType	カードの選択モード（Single、Multiple、None）	単一または複数カードの選択
AllowColumnReorder	bool	ドラッグ＆ドロップによる列の並べ替えを有効化（既定値：false）	ユーザー定義の列順

KanbanColumn のプロパティ

プロパティ	型	目的	使用する場面
Title	string	列の表示名	列名のカスタマイズ
Categories	string	カンマ区切りのカテゴリ	データと列の対応付け
MinimumLimit	int	WIP の最小制限	ワークフロー管理
MaximumLimit	int	WIP の最大制限	過負荷の防止
AllowDrag	bool	列からのドラッグを有効化	カードの移動を制御
AllowDrop	bool	列へのドロップを有効化	ドロップを制限
IsExpanded	bool	列の折りたたみ／展開状態	UI の状態制御

KanbanModel のプロパティ

プロパティ	型	説明	表示位置
Title	string	カードの見出し	上部、太字のテキスト
ID	object	一意の識別子	既定の UI には表示されません
Description	string	詳細なテキスト	タイトルの下
Category	object	列の割り当て	列の配置を決定
Assignee	string	担当者	スイムレーンのグループ化に使用
ColorKey	object	優先度／ステータスのキー	カード上の色付きバー
Tags	string[]	ラベル／カテゴリ	カードの下部
ImageURL	Uri	アバター／アイコン	カードの右側

よくある使用例

1. ソフトウェア開発のタスクボード

シナリオ： バグや機能を開発ステージごとに追跡します

<kanban:SfKanban ItemsSource="{Binding Issues}">
    <kanban:KanbanColumn Title="Backlog" Categories="Open,New" />
    <kanban:KanbanColumn Title="In Development" 
                         Categories="In Progress" 
                         MaximumLimit="3" />
    <kanban:KanbanColumn Title="Testing" 
                         Categories="Testing" 
                         MaximumLimit="5" />
    <kanban:KanbanColumn Title="Done" 
                         Categories="Closed,Resolved" />
</kanban:SfKanban>

2. チーム単位のプロジェクト管理

シナリオ： スイムレーンを使って、チームメンバーごとにタスクを整理します

<kanban:SfKanban SwimlaneKey="Assignee" 
                 ItemsSource="{Binding ProjectTasks}">
    <kanban:SfKanban.SwimlaneHeaderTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal">
                <Image Source="{Binding Image}" Width="30" Height="30"/>
                <TextBlock Text="{Binding Title}" Margin="10,0"/>
            </StackPanel>
        </DataTemplate>
    </kanban:SfKanban.SwimlaneHeaderTemplate>
</kanban:SfKanban>

3. 優先度に基づく並べ替え

シナリオ： 各列内でカードを優先度順に並べ替えます

<kanban:SfKanban SortingMappingPath="Priority"
                 SortingOrder="Descending"
                 ItemsSource="{Binding Tasks}"
                 CardDragEnd="OnCardDrop">
    
</kanban:SfKanban>

 private void OnCardDrop(object sender, KanbanDragEndEventArgs e)
 {
     kanban.RefreshKanbanColumn(e.TargetKey.ToString());
 }

4. インタラクティブなカード操作

シナリオ： カードのタップを処理して詳細ダイアログを表示します

kanban.CardTapped += (s, e) => {
    var card = e.SelectedCard.DataContext as KanbanModel;
    var dialog = new TaskDetailsDialog(card);
    await dialog.ShowAsync();
};

トラブルシューティング

問題：列が表示されない

症状： カンバンボードが空で、列が表示されません

解決策：

1. AutoGenerateColumns が true であること、または Columns が手動で定義されていることを確認します
2. ItemsSource が正しくバインドされていることを確認します
3. データ内で Category プロパティに値が設定されていることを確認します
4. ColumnMappingPath を使用している場合は、モデルにそのプロパティが存在することを確認します

問題：カードが表示されない

症状： 列は表示されますが、カードがありません

解決策：

1. ItemsSource にデータがあることを確認します
2. Category の値が列の Categories と一致していることを確認します
3. カスタムモデルを使用している場合は、CardTemplate が定義されていることを確認します
4. DataContext が正しく設定されていることを確認します

問題：ドラッグ＆ドロップが機能しない

症状： 列間でカードを移動できません

解決策：

1. 移動元の列で AllowDrag=true になっていることを確認します（既定値は true です）
2. Workflows によって遷移が制限されていないことを確認します
3. 列に正しい Categories のマッピングが設定されていることを確認します

問題：WIP 制限が機能しない

症状： WIP 制限の視覚的なインジケーターが表示されません

解決策：

1. 列に MinimumLimit または MaximumLimit が設定されていることを確認します
2. カード数が実際に制限を超えている、または下回っていることを確認します
3. テーマリソースが正しく読み込まれていることを確認します

問題：スイムレーンでグループ化されない

症状： すべてのカードが単一の行に表示され、スイムレーンがありません

解決策：

1. SwimlaneKey プロパティが設定されていることを確認します
2. マッピングされたプロパティがデータモデルに存在することを確認します
3. データ内でプロパティにさまざまな値が設定されていることを確認します
4. KanbanModel を使用している場合、既定値は "Assignee" です

問題：並べ替えが適用されない

症状： ドラッグ＆ドロップ後にカードが並べ替えられません

解決策：

1. CardDrop イベントで RefreshKanbanColumn() を呼び出します
2. SortingMappingPath に有効なプロパティが設定されていることを確認します
3. プロパティの型が並べ替え可能（string、int、DateTime など）であることを確認します
4. SortingOrder（Ascending/Descending）が指定されていることを確認します

ベストプラクティス

1. すぐに始めるには KanbanModel を使用する：組み込みモデルと既定のカード UI により、開発時間を短縮できます
2. カスタムモデルにはテンプレートが必要です：カスタムデータモデルを使用する場合は、必ず CardTemplate を定義してください
3. WIP 制限を設定する：MinimumLimit/MaximumLimit を実装して、ワークフローのボトルネックを防ぎます
4. 並べ替えには CardDrop を処理する：並べ替えを使用する場合は、ドロップ後に RefreshKanbanColumn() を呼び出します
5. 検証には Workflows を使用する：Workflows プロパティを使って、無効な状態遷移を防ぎます
6. 列の幅を最適化する：レスポンシブレイアウトには MinColumnWidth/MaxColumnWidth を設定します
7. スイムレーンを活用する：論理的なカテゴリ（チーム、プロジェクト、優先度）ごとにカードをグループ化します
8. インジケーターをカスタマイズする：明確に視覚的な優先順位を示すには、IndicatorColorPalette を定義します
9. ツールチップを有効にする：カードの追加情報を表示するには、IsToolTipEnabled=true を設定します
10. テーマをテストする：ライトモードとダークモードの両方で表示を確認します

エッジケースと注意点

列ごとに複数のカテゴリを設定する場合：

• コンマ区切りの値を使用します：Categories="Open,New,Backlog"
• 一致するカードはすべて同じ列に表示されます

カスタムモデルの要件：

• CardTemplate を必ず定義してください（既定のテンプレートには KanbanModel が必要です）
• "Category" というプロパティ名を使用しない場合は、ColumnMappingPath を必ず設定してください
• テンプレートの DataContext はカスタムモデルのインスタンスです

ワークフローの制限：

• AllowedTransitions が空の場合、ドロップは許可されません
• カテゴリのワークフローを定義しない場合、すべての遷移が許可されます
• ワークフローの Category は、データ内の Category の値と完全に一致する必要があります

ドラッグ＆ドロップ時の並べ替え：

• ドロップ後に並べ替えは自動適用されません
• CardDrop イベントで RefreshKanbanColumn() を手動で呼び出す必要があります
• インデックスベースの並べ替えには、イベントハンドラーでのカスタム実装が必要です

スイムレーンのグループ化：

• KanbanModel の既定のスイムレーンキーは "Assignee" です
• カスタムモデルでは SwimlaneKey を明示的に設定する必要があります
• Null または空の値の場合は、単一の「未グループ化」スイムレーンが作成されます

---