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();
};

故障排除

问题：列未显示

症状： Kanban 看板为空，没有显示任何列

解决方案：

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. 确认已设置 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. 测试主题：确认在浅色和深色模式下的外观

边界情况与注意事项

每列包含多个类别：

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

自定义模型要求：

• 必须定义 CardTemplate（默认模板需要 KanbanModel）
• 如果未使用 "Category" 属性名称，必须设置 ColumnMappingPath
• 模板的 DataContext 是自定义模型实例

工作流限制：

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

拖放排序：

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

泳道分组：

• KanbanModel 的默认泳道键为 "Assignee"
• 自定义模型必须显式设置 SwimlaneKey
• 空值或 Null 值会创建一个“未分组”泳道

---

如需查看详细的 API 参考，请访问：Syncfusion WinUI Kanban 文档