syncfusion-wpf-kanban-board

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF Kanban (SfKanban)

实现Syncfusion WPF Kanban（SfKanban）控件

This skill provides comprehensive guidance for implementing the Syncfusion® WPF Kanban (SfKanban) control, a powerful visual workflow management system that displays tasks as cards organized across columns representing different workflow stages.

本技能提供了实现Syncfusion® WPF Kanban（SfKanban）控件的全面指导，这是一个强大的可视化工作流管理系统，可将任务以卡片形式展示，并按不同工作流阶段划分的列进行组织。

When to Use This Skill

何时使用本技能

Use this skill immediately when:

User wants to create a Kanban board for task or project management
Building workflow visualization systems (to-do, in-progress, done)
Implementing agile project tracking boards
Need work-in-progress (WIP) limits per workflow stage
Creating task boards with drag-and-drop functionality
Organizing tasks by teams, projects, or custom criteria using swim lanes
Managing software development workflows or issue tracking systems
Need to visualize task status across multiple stages

在以下场景下立即使用本技能：

用户需要创建用于任务或项目管理的Kanban看板
构建工作流可视化系统（待办、进行中、已完成）
实现敏捷项目跟踪看板
需要为每个工作流阶段设置在制品（WIP）限制
创建具备拖放功能的任务看板
使用泳道按团队、项目或自定义标准组织任务
管理软件开发工作流或问题跟踪系统
需要可视化多阶段任务状态

Component Overview

组件概述

The Syncfusion WPF Kanban (SfKanban) provides an efficient way to visualize workflows at each stage of completion. It offers:

Core Features:

Cards: Visual representation of tasks with title, description, tags, images, and priority indicators
Columns: Organize work into workflow stages (e.g., Open, In Progress, Done)
Swim Lanes: Group cards by projects, teams, users, or custom categories
Work-in-Progress (WIP) Limits: Set minimum/maximum task limits per column to prevent overload
Drag and Drop: Intuitive card movement between columns and swim lanes
Workflows: Define allowed card transitions between specific states
Sorting: Organize cards within columns by priority, date, or custom fields
Events: Rich event model for card interactions (tap, drag, drop)
Customization: Extensive template support for cards, headers, and swim lanes
Theming: Built-in light and dark themes with system integration
Localization & RTL: Support for multiple languages and right-to-left rendering

Syncfusion WPF Kanban（SfKanban）提供了一种高效的方式来可视化每个完成阶段的工作流。它具备以下特性：

核心功能：

卡片：以标题、描述、标签、图片和优先级指示器可视化展示任务
列：将工作按工作流阶段（如：待处理、进行中、已完成）进行组织
泳道：按项目、团队、用户或自定义类别对卡片进行分组
在制品（WIP）限制：为每个列设置最小/最大任务限制，防止过载
拖放：在列和泳道之间直观地移动卡片
工作流：定义卡片在特定状态之间的允许转换规则
排序：按优先级、日期或自定义字段对列内的卡片进行组织
事件：丰富的事件模型，用于处理卡片交互（点击、拖动、放置）
自定义：对卡片、标题和泳道提供丰富的模板支持
主题：内置明暗两种主题，支持系统集成
本地化与RTL：支持多语言和从右到左的渲染方式

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Use when user needs:

Initial setup and installation via NuGet
Creating basic Kanban board
Understanding ItemsSource binding
Using default KanbanModel vs custom data models
Setting up auto-generated or manual columns
Applying themes, localization, and RTL support

📄 阅读： references/getting-started.md

适用于以下场景：

通过NuGet进行初始设置和安装
创建基础Kanban看板
理解ItemsSource绑定
使用默认KanbanModel vs 自定义数据模型
设置自动生成或手动定义的列
应用主题、本地化和RTL支持

Cards Configuration

卡片配置

📄 Read: references/cards.md

Use when user needs:

Understanding card structure and properties
Customizing card appearance with CardTemplate
Working with card indicators and tags
Implementing conditional card templates (CardTemplateSelector)
Enabling and customizing card tooltips
Troubleshooting card display issues

📄 阅读： references/cards.md

适用于以下场景：

理解卡片结构和属性
使用CardTemplate自定义卡片外观
处理卡片指示器和标签
实现条件卡片模板（CardTemplateSelector）
启用和自定义卡片工具提示
排查卡片显示问题

Columns Management

列管理

📄 Read: references/columns.md

Use when user needs:

Configuring column widths (minimum, maximum, exact)
Auto-generating vs manually defining columns
Mapping categories to columns
Customizing column headers
Expanding/collapsing columns programmatically
Enabling/disabling drag-and-drop per column
Setting up multi-category columns
Configuring WIP (Work-in-Progress) limits with visual indicators
Customizing drag/drop placeholder appearance

📄 阅读： references/columns.md

适用于以下场景：

配置列宽（最小、最大、固定）
自动生成 vs 手动定义列
将类别映射到列
自定义列标题
以编程方式展开/折叠列
为单个列启用/禁用拖放
设置多类别列
配置带可视化指示器的WIP（在制品）限制
自定义拖放占位符外观

Swim Lanes Organization

泳道组织

📄 Read: references/swimlanes.md

Use when user needs:

Grouping cards by teams, projects, or users
Enabling and configuring swim lanes
Mapping swim lane properties (SwimlaneKey)
Customizing swim lane header appearance
Creating hierarchical card organization
Implementing team-based or project-based views

📄 阅读： references/swimlanes.md

适用于以下场景：

按团队、项目或用户对卡片进行分组
启用和配置泳道
映射泳道属性（SwimlaneKey）
自定义泳道标题外观
创建分层卡片组织
实现基于团队或项目的视图

Workflows and Transitions

工作流与转换

📄 Read: references/workflows.md

Use when user needs:

Defining allowed card transitions between columns
Restricting card movement between specific states
Implementing workflow validation rules
Preventing drag-and-drop to specific columns
Creating state machine-like workflows
Managing complex workflow transitions

📄 阅读： references/workflows.md

适用于以下场景：

定义卡片在列之间的允许转换规则
限制卡片在特定状态之间的移动
实现工作流验证规则
禁止拖放到特定列
创建类似状态机的工作流
管理复杂的工作流转换

Card Sorting

卡片排序

📄 Read: references/sorting.md

Use when user needs:

Sorting cards within columns by priority, date, or custom fields
Implementing custom field sorting (ascending/descending)
Setting up index-based sorting for precise positioning
Dynamically updating sort order after drag-and-drop
Refreshing column display after sorting changes
Understanding sorting with custom data models

📄 阅读： references/sorting.md

适用于以下场景：

按优先级、日期或自定义字段对列内的卡片进行排序
实现自定义字段排序（升序/降序）
设置基于索引的排序以精确定位
拖放后动态更新排序顺序
排序更改后刷新列显示
理解自定义数据模型的排序方式

Events and Interactions

事件与交互

📄 Read: references/events.md

Use when user needs:

Handling card tap events (CardTapped)
Responding to drag events (CardDragStarting, CardDragOver)
Processing card drop events (CardDrop)
Implementing MVVM commands (CardTappedCommand)
Accessing event arguments and card data
Preventing or customizing drag-and-drop behavior
Implementing business logic on card interactions

📄 阅读： references/events.md

适用于以下场景：

处理卡片点击事件（CardTapped）
响应拖动事件（CardDragStarting、CardDragOver）
处理卡片放置事件（CardDrop）
实现MVVM命令（CardTappedCommand）
访问事件参数和卡片数据
阻止或自定义拖放行为
在卡片交互时执行业务逻辑

Quick Start Example

快速入门示例

Basic Kanban Setup

基础Kanban设置

xml

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

xml

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

ViewModel with KanbanModel

基于KanbanModel的ViewModel

csharp

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" }
            }
        };
    }
}

csharp

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" }
            }
        };
    }
}

Manual Column Definition

手动定义列

xml

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

xml

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

Common Patterns

常见模式

Pattern 1: Auto-Generated Columns

模式1：自动生成列

When: User wants quick setup with columns generated from data

csharp

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

Result: Columns created automatically based on unique Category values in data

适用场景： 用户希望通过数据快速设置列

csharp

// 从Category属性值自动生成列
kanban.AutoGenerateColumns = true;
kanban.ItemsSource = viewModel.TaskDetails;

结果： 根据数据中的唯一Category值自动创建列

Pattern 2: WIP Limits with Visual Indicators

模式2：带可视化指示器的WIP限制

When: User needs to limit tasks per stage and show visual feedback

xml

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

Result:

Error bar shows red when count exceeds MaximumLimit
Error bar shows yellow when count is below MinimumLimit
Helps prevent workflow bottlenecks

适用场景： 用户需要限制每个阶段的任务数量并显示视觉反馈

xml

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

结果：

当任务数量超过MaximumLimit时，显示红色错误条
当任务数量低于MinimumLimit时，显示黄色错误条
有助于防止工作流瓶颈

Pattern 3: Custom Card Template

模式3：自定义卡片模板

When: User needs custom card appearance beyond default

xml

<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 instance

适用场景： 用户需要超出默认样式的自定义卡片外观

xml

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

数据上下文： KanbanModel实例

Pattern 4: Swim Lanes by Team

模式4：按团队划分泳道

When: User wants to organize cards by teams or projects

xml

<kanban:SfKanban SwimlaneKey="Assignee" 
                 ItemsSource="{Binding TaskDetails}">
    <!-- Cards grouped by Assignee property -->
</kanban:SfKanban>

Result: Horizontal swim lane rows, one per unique Assignee value

适用场景： 用户希望按团队或项目组织卡片

xml

<kanban:SfKanban SwimlaneKey="Assignee" 
                 ItemsSource="{Binding TaskDetails}">
    <!-- 按Assignee属性对卡片进行分组 -->
</kanban:SfKanban>

结果： 水平泳道行，每个唯一Assignee值对应一行

Pattern 5: Workflow Restrictions

模式5：工作流限制

When: User wants to enforce specific card transition rules

xml

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

Result:

Cards in "Open" can only move to "In Progress"
Cards in "In Progress" can only move to "Done" or "Won't Fix"
Prevents invalid state transitions

适用场景： 用户希望强制执行特定的卡片转换规则

xml

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

结果：

"待处理"状态的卡片只能移动到"进行中"
"进行中"状态的卡片只能移动到"已完成"或"不修复"
防止无效的状态转换

Pattern 6: Custom Data Model

模式6：自定义数据模型

When: User has existing data model, not using KanbanModel

csharp

// 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>
        <!-- Define custom template -->
    </kanban:SfKanban.CardTemplate>
</kanban:SfKanban>

Important: Must define CardTemplate when using custom model

适用场景： 用户已有现有数据模型，不使用KanbanModel

csharp

// 自定义模型
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

Key Properties

关键属性

SfKanban Properties

SfKanban属性

Property	Type	Purpose	When to Use
`ItemsSource`	object	Data source for cards	Always (required)
`AutoGenerateColumns`	bool	Auto-create columns from Category	Quick setup vs custom control
`Columns`	Collection	Manual column definitions	When AutoGenerateColumns = false
`ColumnMappingPath`	string	Property for column categorization	Custom models (default: "Category")
`SwimlaneKey`	string	Property for swim lane grouping	Organizing by teams/projects
`CardTemplate`	DataTemplate	Custom card appearance	Custom data models or styling
`ColumnHeaderTemplate`	DataTemplate	Custom column header	Branding or additional info
`SwimlaneHeaderTemplate`	DataTemplate	Custom swim lane header	Custom swim lane display
`MinColumnWidth`	double	Minimum column width	Responsive layouts
`MaxColumnWidth`	double	Maximum column width	Controlling column size
`ColumnWidth`	double	Fixed column width	Uniform column sizing
`SortingMappingPath`	string	Property for sorting cards	Ordering cards by priority/date
`SortingOrder`	enum	Ascending or Descending	Sort direction
`Workflows`	Collection	Allowed card transitions	Workflow validation
`IndicatorColorPalette`	Collection	Color mapping for indicators	Priority/status colors
`IsToolTipEnabled`	bool	Enable card tooltips	Additional card info on hover

属性	类型	用途	适用场景
`ItemsSource`	object	卡片的数据源	始终需要（必填）
`AutoGenerateColumns`	bool	从Category自动创建列	快速设置 vs 自定义控制
`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	启用卡片工具提示	悬停时显示附加卡片信息

KanbanColumn Properties

KanbanColumn属性

Property	Type	Purpose	When to Use
`Title`	string	Column display name	Custom column titles
`Categories`	string	Comma-separated categories	Mapping data to column
`MinimumLimit`	int	WIP minimum limit	Workflow management
`MaximumLimit`	int	WIP maximum limit	Preventing overload
`AllowDrag`	bool	Enable dragging from column	Controlling card movement
`AllowDrop`	bool	Enable dropping to column	Restricting drops
`IsExpanded`	bool	Column collapsed/expanded state	UI state control

属性	类型	用途	适用场景
`Title`	string	列的显示名称	自定义列标题
`Categories`	string	逗号分隔的类别	将数据映射到列
`MinimumLimit`	int	WIP最小限制	工作流管理
`MaximumLimit`	int	WIP最大限制	防止过载
`AllowDrag`	bool	启用从该列拖动	控制卡片移动
`AllowDrop`	bool	允许向该列放置	限制放置操作
`IsExpanded`	bool	列的折叠/展开状态	UI状态控制

KanbanModel Properties

KanbanModel属性

Property	Type	Description	Display Location
`Title`	string	Card heading	Top, bold text
`ID`	object	Unique identifier	Not displayed in default UI
`Description`	string	Detailed text	Below title
`Category`	object	Column assignment	Determines column placement
`Assignee`	string	Assigned person	Used for swim lane grouping
`ColorKey`	object	Priority/status key	Color bar on card
`Tags`	string[]	Labels/categories	Bottom of card
`ImageURL`	Uri	Avatar/icon	Right side of card

属性	类型	描述	显示位置
`Title`	string	卡片标题	顶部粗体文本
`ID`	object	唯一标识符	默认UI中不显示
`Description`	string	详细文本	标题下方
`Category`	object	列分配	决定卡片所在列
`Assignee`	string	负责人	用于泳道分组
`ColorKey`	object	优先级/状态键	卡片上的颜色条
`Tags`	string[]	标签/类别	卡片底部
`ImageURL`	Uri	头像/图标	卡片右侧

Common Use Cases

常见用例

1. Software Development Task Board

1. 软件开发任务看板

Scenario: Track bugs and features through development stages

xml

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

场景： 跟踪缺陷和功能的开发阶段

xml

<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. Team-Based Project Management

2. 基于团队的项目管理

Scenario: Organize tasks by team members with swim lanes

xml

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

场景： 使用泳道按团队成员组织任务

xml

<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. Priority-Based Sorting

3. 基于优先级的排序

Scenario: Sort cards by priority within each column

xml

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

csharp

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

场景： 在每个列内按优先级对卡片进行排序

xml

<kanban:SfKanban SortingMappingPath="Priority"
                 SortingOrder="Descending"
                 ItemsSource="{Binding Tasks}"
                 CardDragEnd="OnCardDrop">
    <!-- 列定义 -->
</kanban:SfKanban>

csharp

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

4. Interactive Card Actions

4. 交互式卡片操作

Scenario: Handle card taps to show details dialog

csharp

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

场景： 处理卡片点击以显示详情对话框

csharp

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

Troubleshooting

故障排除

Issue: Columns Not Showing

问题：列未显示

Symptoms: Kanban board is empty, no columns visible

Solutions:

Verify AutoGenerateColumns is true OR Columns are manually defined
Check ItemsSource is bound correctly
Ensure Category property has values in data
If using ColumnMappingPath, verify property exists in model

症状： Kanban看板为空，看不到列

解决方案：

确认AutoGenerateColumns为true 或已手动定义Columns
检查ItemsSource是否正确绑定
确保数据中的Category属性有值
如果使用ColumnMappingPath，验证模型中存在该属性

Issue: Cards Not Displaying

问题：卡片未显示

Symptoms: Columns show but cards are missing

Solutions:

Check ItemsSource has data
Verify Category values match column Categories
If using custom model, ensure CardTemplate is defined
Check DataContext is set correctly

症状： 显示列但看不到卡片

解决方案：

检查ItemsSource是否有数据
验证Category值与列的Categories匹配
如果使用自定义模型，确保已定义CardTemplate
检查DataContext是否正确设置

Issue: Drag-and-Drop Not Working

问题：拖放功能无效

Symptoms: Cannot move cards between columns

Solutions:

Verify AllowDrag=true on source column (default is true)
Ensure Workflows don't restrict the transition
Check if columns have correct Categories mapping

症状： 无法在列之间移动卡片

解决方案：

验证源列的AllowDrag=true（默认值为true）
确保Workflows未限制该转换
检查列是否有正确的Categories映射

Issue: WIP Limits Not Working

问题：WIP限制无效

Symptoms: Visual indicators not showing for WIP limits

Solutions:

Verify MinimumLimit and/or MaximumLimit are set on columns
Check card count actually exceeds/is below limits
Ensure theme resources are loaded correctly

症状： WIP限制的可视化指示器未显示

解决方案：

确认已在列上设置MinimumLimit和/或MaximumLimit
检查卡片数量确实超过/低于限制
确保主题资源已正确加载

Issue: Swim Lanes Not Grouping

问题：泳道未分组

Symptoms: All cards in single row, no swim lanes

Solutions:

Verify SwimlaneKey property is set
Check mapped property exists in data model
Ensure property has varying values in data
If using KanbanModel, default is "Assignee"

症状： 所有卡片都在同一行，没有泳道

解决方案：

确认已设置SwimlaneKey属性
检查映射的属性是否存在于数据模型中
确保数据中的该属性有不同的值
如果使用KanbanModel，默认值为"Assignee"

Issue: Sorting Not Applied

问题：排序未生效

Symptoms: Cards not sorted after drag-and-drop

Solutions:

Call RefreshKanbanColumn() in CardDrop event
Verify SortingMappingPath is set to valid property
Check property type is sortable (string, int, DateTime, etc.)
Ensure SortingOrder is specified (Ascending/Descending)

症状： 拖放后卡片未排序

解决方案：

在CardDrop事件中调用RefreshKanbanColumn()
验证SortingMappingPath已设置为有效属性
检查属性类型是否可排序（字符串、整数、日期时间等）
确保已指定SortingOrder（升序/降序）

Best Practices

最佳实践

Use KanbanModel for Quick Start: Built-in model with default card UI saves development time
Custom Models Require Templates: Always define CardTemplate when using custom data models
Set WIP Limits: Implement MinimumLimit/MaximumLimit to prevent workflow bottlenecks
Handle CardDrop for Sorting: Call RefreshKanbanColumn() after drop when using sorting
Use Workflows for Validation: Prevent invalid state transitions with Workflows property
Optimize Column Width: Set MinColumnWidth/MaxColumnWidth for responsive layouts
Leverage Swim Lanes: Group cards by logical categories (teams, projects, priorities)
Customize Indicators: Define IndicatorColorPalette for clear visual prioritization
Enable Tooltips: Set IsToolTipEnabled=true for additional card information
Test Themes: Verify appearance in both light and dark modes

使用KanbanModel快速入门：内置模型和默认卡片UI可节省开发时间
自定义模型需要模板：使用自定义数据模型时始终定义CardTemplate
设置WIP限制：实现MinimumLimit/MaximumLimit以防止工作流瓶颈
为排序处理CardDrop事件：使用排序时，放置后调用RefreshKanbanColumn()
使用Workflows进行验证：通过Workflows属性防止无效状态转换
优化列宽：设置MinColumnWidth/MaxColumnWidth以实现响应式布局
利用泳道：按逻辑类别（团队、项目、优先级）对卡片进行分组
自定义指示器：定义IndicatorColorPalette以实现清晰的视觉优先级
启用工具提示：设置IsToolTipEnabled=true以显示附加卡片信息
测试主题：验证明暗两种模式下的外观

Edge Cases and Gotchas

边缘情况与注意事项

Multiple Categories per Column:

Use comma-separated values:
```
Categories="Open,New,Backlog"
```
All matching cards appear in single column

Custom Model Requirements:

MUST define CardTemplate (default template requires KanbanModel)
MUST set ColumnMappingPath if not using "Category" property name
DataContext for template is your custom model instance

Workflow Restrictions:

Empty AllowedTransitions = no drops allowed
Not defining workflow for a category = allows all transitions
Workflow Category must match exact Category value in data

Sorting with Drag-Drop:

Sorting doesn't auto-apply after drop
Must manually call RefreshKanbanColumn() in CardDrop event
Index-based sorting requires custom implementation in event handlers

Swim Lane Grouping:

Default swim lane key is "Assignee" for KanbanModel
Custom models must set SwimlaneKey explicitly
Null or empty values create single "ungrouped" swim lane

多类别列：

使用逗号分隔的值：
```
Categories="Open,New,Backlog"
```
所有匹配的卡片都会显示在同一列中

自定义模型要求：

必须定义CardTemplate（默认模板依赖KanbanModel）
如果不使用"Category"属性名，必须设置ColumnMappingPath
模板的数据上下文是自定义模型实例

工作流限制：

空的AllowedTransitions = 不允许任何放置操作
不为某个类别定义工作流 = 允许所有转换
工作流中的Category必须与数据中的Category值完全匹配

拖放排序：

排序不会在放置后自动应用
必须在CardDrop事件中手动调用RefreshKanbanColumn()
基于索引的排序需要在事件处理程序中自定义实现

泳道分组：

KanbanModel的默认泳道键是"Assignee"
自定义模型必须显式设置SwimlaneKey
空值或空字符串会创建单个"未分组"泳道