syncfusion-winui-kanban-board

Syncfusion WinUI Kanban（SfKanban）の実装

このスキルでは、タスクをワークフローの各段階を表す列にカードとして配置して表示する、強力なビジュアルワークフロー管理システムである Syncfusion® WinUI Kanban（SfKanban）コントロールの実装方法を包括的に説明します。

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

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

• タスクやプロジェクトを管理する Kanban ボードを作成する
• ワークフロー可視化システム（未着手、進行中、完了）を構築する
• アジャイルプロジェクト管理用のボードを実装する
• ワークフローの各段階で仕掛かり作業（WIP）の上限を設ける
• ドラッグ＆ドロップ機能を備えたタスクボードを作成する
• スイムレーンを使用して、チーム、プロジェクト、または独自の条件でタスクを整理する
• ソフトウェア開発のワークフローや課題追跡システムを管理する
• 複数の段階にわたるタスクのステータスを視覚化する

コンポーネントの概要

Syncfusion WinUI Kanban（SfKanban）を使用すると、完了までの各段階におけるワークフローを効率的に視覚化できます。次の機能を備えています。

主な機能：

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

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

はじめに

📄 参照： references/getting-started.md

次のことが必要な場合に使用します。

• NuGet による初期セットアップとインストール
• 基本的な Kanban ボードの作成
• ItemsSource のバインドについて理解する
• 既定の KanbanModel と独自のデータモデルを使用する
• 列を自動生成または手動で設定する
• テーマ、ローカライズ、RTL サポートを適用する

カードの設定

📄 参照： references/cards.md

次のことが必要な場合に使用します。

• カードの構造とプロパティについて理解する
• CardTemplate を使用してカードの外観をカスタマイズする
• カードのインジケーターとタグを扱う
• 条件に応じたカードテンプレート（CardTemplateSelector）を実装する
• カードのツールチップを有効化してカスタマイズする
• カードの表示に関する問題をトラブルシューティングする

列の管理

📄 参照： references/columns.md

次のことが必要な場合に使用します。

• 列の幅（最小、最大、固定）を設定する
• 列を自動生成するか、手動で定義する
• カテゴリーを列にマッピングする
• 列のヘッダーをカスタマイズする
• プログラムから列を展開または折りたたむ
• 列ごとにドラッグ＆ドロップを有効化または無効化する
• 複数カテゴリーの列を設定する
• 視覚的なインジケーターを備えた WIP（仕掛かり作業）の上限を設定する
• ドラッグ／ドロップ時のプレースホルダーの外観をカスタマイズする

スイムレーンによる整理

📄 参照： references/swimlanes.md

次のことが必要な場合に使用します。

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

ワークフローと遷移

📄 参照： references/workflows.md

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

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

カードの並べ替え

📄 参照： references/sorting.md

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

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

イベントとインタラクション

📄 参照： references/events.md

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

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

クイックスタートの例

基本的なカンバンの設定

<Window xmlns:kanban="using:Syncfusion.UI.Xaml.Kanban">
    <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",
                IndicatorColorKey = "High",
                Tags = new List<string> { "Bug Fixing" }
            },
            new KanbanModel
            {
                Title = "Kanban Feature",
                Id = "25678",
                Description = "Implement drag and drop support",
                Category = "In Progress",
                IndicatorColorKey = "Normal",
                Tags = new List<string> { "New Feature" }
            }
        };
    }
}

列の手動定義

<kanban:SfKanban AutoGenerateColumns="False" 
                 ItemsSource="{Binding TaskDetails}">
    <kanban:KanbanColumn HeaderText="To Do" Categories="Open" />
    <kanban:KanbanColumn HeaderText="In Progress" Categories="In Progress" />
    <kanban:KanbanColumn HeaderText="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 HeaderText="In Progress" 
                     Categories="In Progress"
                     MinimumCount="2" 
                     MaximumCount="5" />

結果：

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

パターン 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 値ごとに、横方向のスイムレーン行が作成されます

パターン 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 を定義する必要があります

主なプロパティ

SfKanban のプロパティ

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

KanbanColumn のプロパティ

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

KanbanModel のプロパティ

プロパティ	型	目的
Title	string	カードのタイトル
Id	object	一意の識別子
Description	string	カードの説明
Category	object	列の割り当て
Assignee	string	割り当てられた担当者（スイムレーンの既定値）
IndicatorColorKey	object	優先度／ステータスのインジケーター
Tags	List	カードのラベル
Image	Image	カードのアバター／アイコン

一般的なユースケース

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

シナリオ： バグや機能を開発段階ごとに追跡します

<kanban:SfKanban ItemsSource="{Binding Issues}">
    <kanban:KanbanColumn HeaderText="Backlog" Categories="Open,New" />
    <kanban:KanbanColumn HeaderText="In Development" 
                         Categories="In Progress" 
                         MaximumCount="3" />
    <kanban:KanbanColumn HeaderText="Testing" 
                         Categories="Testing" 
                         MaximumCount="5" />
    <kanban:KanbanColumn HeaderText="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}"
                 CardDrop="OnCardDrop">
    
</kanban:SfKanban>

private void OnCardDrop(object sender, KanbanCardDropEventArgs e)
{
    kanban.RefreshKanbanColumn(e.TargetColumn.AllowedTransitionCategory.ToString());
}

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

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

kanban.CardTapped += (s, e) => {
    var card = e.SelectedCard.Content 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. 列に MinimumCount および／または MaximumCount が設定されていることを確認します
2. カード数が実際に制限を超えている、または下回っていることを確認します
3. テーマリソースが正しく読み込まれていることを確認します

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

症状： すべてのカードが 1 つの行に表示され、スイムレーンがない

解決方法：

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 制限を設定する：MinimumCount／MaximumCount を実装して、ワークフローのボトルネックを防ぎます
4. 並べ替えには CardDrop を処理する：並べ替えを使用する場合は、ドロップ後に RefreshKanbanColumn() を呼び出します
5. 検証にはワークフローを使用する：Workflows プロパティを使って、無効な状態遷移を防ぎます
6. 列幅を最適化する：レスポンシブなレイアウトには MinimumColumnWidth／MaximumColumnWidth を設定します
7. スイムレーンを活用する：論理的なカテゴリ（チーム、プロジェクト、優先度）ごとにカードをグループ化します
8. インジケーターをカスタマイズする：明確な視覚的な優先順位付けのために IndicatorColorPalette を定義します
9. ツールチップを有効にする：カードの追加情報を表示するには IsToolTipEnabled=true を設定します
10. テーマをテストする：ライトモードとダークモードの両方で外観を確認します

エッジケースと注意点

1 列に複数のカテゴリを指定する場合：

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

カスタムモデルの要件：

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

ワークフローの制限：

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

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

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

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

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

---

API リファレンスの詳細については、Syncfusion WinUI Kanban のドキュメントをご覧ください