syncfusion-winui-kanban-board

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WinUI Kanban (SfKanban)

实现Syncfusion WinUI Kanban (SfKanban)

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

本技能提供了实现Syncfusion® WinUI 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

当出现以下场景时可立即使用本技能：

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

Component Overview

组件概述

The Syncfusion WinUI 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 WinUI 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完成初始配置和安装
创建基础看板
理解ItemsSource绑定
使用默认KanbanModel与自定义数据模型的区别
设置自动生成或手动定义列
应用主题、本地化和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

当用户需要以下能力时使用：

配置列宽（最小值、最大值、固定值）
自动生成与手动定义列的区别
将类别映射到对应列
自定义列表头
通过代码控制列的展开/收起
为单列启用/禁用拖拽功能
设置多类别列
配置带视觉标识的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

基础看板配置

xml

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

xml

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

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

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

Manual Column Definition

手动定义列

xml

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

xml

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

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 HeaderText="In Progress" 
                     Categories="In Progress"
                     MinimumCount="2" 
                     MaximumCount="5" />

Result:

Error bar shows red when count exceeds MaximumCount
Error bar shows yellow when count is below MinimumCount
Helps prevent workflow bottlenecks

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

xml

<kanban:KanbanColumn HeaderText="In Progress" 
                     Categories="In Progress"
                     MinimumCount="2" 
                     MaximumCount="5" />

效果：

当任务数超过MaximumCount时错误栏显示红色
当任务数低于MinimumCount时错误栏显示黄色
有助于避免工作流瓶颈

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>

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

效果：

处于"Open"状态的卡片只能移动到"In Progress"
处于"In Progress"状态的卡片只能移动到"Done"或"Won't Fix"
避免无效的状态流转

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
`MinimumColumnWidth`	double	Minimum column width	Responsive layouts
`MaximumColumnWidth`	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自动生成列	快速配置与自定义控件切换
`Columns`	集合	手动定义列	当AutoGenerateColumns = false时
`ColumnMappingPath`	string	列分类对应的属性	自定义模型（默认值："Category"）
`SwimlaneKey`	string	泳道分组对应的属性	按团队/项目组织内容
`CardTemplate`	DataTemplate	自定义卡片外观	自定义数据模型或样式定制
`ColumnHeaderTemplate`	DataTemplate	自定义列表头	品牌定制或展示额外信息
`SwimlaneHeaderTemplate`	DataTemplate	自定义泳道表头	自定义泳道展示
`MinimumColumnWidth`	double	最小列宽	响应式布局
`MaximumColumnWidth`	double	最大列宽	控制列尺寸
`ColumnWidth`	double	固定列宽	统一列尺寸
`SortingMappingPath`	string	卡片排序对应的属性	按优先级/日期排序卡片
`SortingOrder`	枚举	升序或降序	排序方向
`Workflows`	集合	允许的卡片流转规则	工作流校验
`IndicatorColorPalette`	集合	标识的颜色映射	优先级/状态颜色配置
`IsToolTipEnabled`	bool	启用卡片提示框	hover时展示额外卡片信息

KanbanColumn Properties

KanbanColumn属性

Property	Type	Purpose	When to Use
`HeaderText`	string	Column display name	Custom column titles
`Categories`	string	Comma-separated categories	Mapping data to column
`MinimumCount`	int	WIP minimum limit	Workflow management
`MaximumCount`	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

属性	类型	用途	适用场景
`HeaderText`	string	列展示名称	自定义列标题
`Categories`	string	逗号分隔的类别	将数据映射到对应列
`MinimumCount`	int	WIP最小限制	工作流管理
`MaximumCount`	int	WIP最大限制	避免工作过载
`AllowDrag`	bool	允许从该列拖拽	控制卡片移动
`AllowDrop`	bool	允许放置到该列	限制放置行为
`IsExpanded`	bool	列收起/展开状态	UI状态控制

KanbanModel Properties

KanbanModel属性

Property	Type	Purpose
`Title`	string	Card title
`Id`	object	Unique identifier
`Description`	string	Card description
`Category`	object	Column assignment
`Assignee`	string	Person assigned (swim lane default)
`IndicatorColorKey`	object	Priority/status indicator
`Tags`	List<string>	Card labels
`Image`	Image	Card avatar/icon

属性	类型	用途
`Title`	string	卡片标题
`Id`	object	唯一标识
`Description`	string	卡片描述
`Category`	object	所属列
`Assignee`	string	负责人（泳道默认字段）
`IndicatorColorKey`	object	优先级/状态标识
`Tags`	List<string>	卡片标签
`Image`	Image	卡片头像/图标

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

场景： 跟踪Bug和功能在开发各阶段的进度

xml

<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. 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}"
                 CardDrop="OnCardDrop">
    <!-- Columns -->
</kanban:SfKanban>

csharp

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

场景： 每个列内的卡片按优先级排序

xml

<kanban:SfKanban SortingMappingPath="Priority"
                 SortingOrder="Descending"
                 ItemsSource="{Binding Tasks}"
                 CardDrop="OnCardDrop">
    <!-- 列配置 -->
</kanban:SfKanban>

csharp

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

4. Interactive Card Actions

4. 交互式卡片操作

Scenario: Handle card taps to show details dialog

csharp

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

场景： 处理卡片点击事件展示详情弹窗

csharp

kanban.CardTapped += async (s, e) => {
    var card = e.SelectedCard.Content 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

现象： 看板为空，没有可见的列

解决方案：

确认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）
确认工作流没有限制该流转
检查列的Categories映射是否正确

Issue: WIP Limits Not Working

问题：WIP限制不生效

Symptoms: Visual indicators not showing for WIP limits

Solutions:

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

现象： WIP限制的视觉标识不展示

解决方案：

确认列上已经设置了MinimumCount和/或MaximumCount
检查卡片数量确实超过/低于限制
确认主题资源加载正确

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设置为有效的属性
检查属性类型是可排序的（字符串、整数、DateTime等）
确认已经指定了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 MinimumCount/MaximumCount 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 MinimumColumnWidth/MaximumColumnWidth 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限制：配置MinimumCount/MaximumCount避免工作流瓶颈
排序场景处理CardDrop事件：使用排序功能时，拖拽放置后要调用RefreshKanbanColumn()
使用工作流做校验：通过Workflows属性避免无效的状态流转
优化列宽配置：设置MinimumColumnWidth/MaximumColumnWidth实现响应式布局
合理使用泳道：按逻辑类别（团队、项目、优先级）分组卡片
自定义标识：配置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

For detailed API reference, visit: Syncfusion WinUI Kanban Documentation

单列多类别：

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

自定义模型要求：

必须定义CardTemplate（默认模板依赖KanbanModel）
如果不使用"Category"作为属性名，必须设置ColumnMappingPath
模板的DataContext是你的自定义模型实例

工作流限制：

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

拖拽场景下的排序：

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

泳道分组：

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

详细API参考请访问：Syncfusion WinUI Kanban Documentation