syncfusion-angular-kanban

实现 Syncfusion Angular Kanban

何时使用此技能

在以下场景中，Syncfusion Angular Kanban 组件不可或缺：

• 可视化工作流 - 展示任务阶段（待办 → 进行中 → 测试 → 已完成）
• 实现任务管理 - 让用户能够在多个列之间整理和跟踪工作
• 实现拖放 - 让用户在列之间移动卡片以更改任务状态
• 对任务分组 - 使用泳道按负责人、优先级或类别整理卡片
• 设置限制 - 通过最小/最大卡片数量强制执行 WIP（进行中工作）限制
• 自定义外观 - 为卡片和列应用模板、主题及自定义样式
• 处理事件 - 监听卡片点击、拖动操作和状态变化
• 持久化状态 - 保存看板配置和卡片位置

组件概览

Kanban 看板是一种可视化工作流管理工具，由以下部分构成：

• 卡片 - 表示单个任务（通过 cardSettings 映射到 dataSource）
• 列 - 定义工作流阶段（使用 keyField 和列配置进行映射）
• 泳道 - 按类别对卡片分组（员工、优先级等）
• 拖放 - 默认启用（allowDragAndDrop: true）
• 数据绑定 - 支持本地数组和远程 DataManager
• 模板 - 自定义卡片、列标题、泳道标题和工具提示的渲染
• 响应式 - 自动适配桌面和移动设备布局
• 主题 - 五种内置主题：Material、Bootstrap 3、Bootstrap 4、Fabric、High Contrast

主要功能

✓ 多列工作流，支持自定义标题
✓ 列与列之间及列内的流畅拖放
✓ 按任意数据字段进行泳道分组
✓ WIP 验证（每列/泳道的最小/最大卡片数量）
✓ 卡片、列、泳道、对话框和工具提示的模板
✓ 本地和远程数据绑定，集成 DataManager
✓ 键盘导航和完整的无障碍支持
✓ 用于用户交互的事件（点击、拖动、选择、打开/关闭对话框）
✓ 用于程序化控制的方法（添加/删除卡片、显示/隐藏列）
✓ 多种选择模式（单选或多选卡片）
✓ 用于分组相关列的堆叠标题
✓ 内置主题，支持 CSS 自定义

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 npm 包设置
• Angular 模块导入和配置
• CSS 导入和主题注册
• 使用最简示例初始化 Kanban
• 使用示例数据创建首个可运行看板

核心结构：列和泳道

📄 阅读： references/columns-and-swimlanes.md

• 使用 keyField 映射配置列
• 单键与多键列映射
• 列标题和堆叠标题
• 按字段进行泳道分组
• 动态添加/删除/显示/隐藏列

卡片和数据绑定

📄 阅读： references/cards-and-data-binding.md

• 卡片结构：标题字段、内容字段、抓取器字段
• 卡片模板和自定义渲染
• 本地数组数据绑定
• 使用 DataManager 进行远程数据绑定
• 支持 OData v4
• 卡片选择模式（单选/多选）

拖放和交互

📄 阅读： references/drag-and-drop.md

• 拖放功能（默认启用）
• 在列之间移动卡片
• 在列内重新排序
• 使用 transitionColumns 控制有效转换
• 拖动事件（beforeDragStart、dragStart、dragStop）
• WIP 限制：强制执行最小/最大卡片数量
• 支持键盘导航

功能与自定义

📄 阅读： references/features-and-customization.md

• 对卡片进行排序、筛选和搜索
• 验证规则和对话框
• 移动设备响应式模式
• 自定义对话框模板
• 工具提示模板和配置
• 优先级指示器和颜色选择器
• 列的切换与折叠

属性参考

📄 阅读： references/properties.md

• 核心属性：allowDragAndDrop、allowKeyboard、allowSelection
• 卡片配置：cardSettings（headerField、contentField、template 等）
• 列设置：包含 ColumnsModel 的 columns 数组
• 泳道配置：swimlaneSettings
• 对话框和工具提示模板
• WIP 限制：每列的 minCount、maxCount
• 响应式断点和高度

方法参考

📄 阅读： references/methods.md

• 卡片操作：addCard()、deleteCard()、updateCard()、getSelectedCards()
• 列操作：addColumn()、removeColumn()、hideColumn()、showColumn()
• 看板操作：refresh()、getCardCount()
• 泳道操作：getSwimlaneData()
• 对话框控制：openDialog()、closeDialog()
• 搜索/筛选：search()、filter()、sortBy()

事件参考

📄 阅读： references/events.md

• 操作事件：actionBegin、actionComplete、actionFailure
• 卡片事件：cardClick、cardDoubleClick、cardSelection
• 拖动事件：dragStart、dragStop、beforeDragStart
• 对话框事件：dialogOpen、dialogClose
• 列/泳道事件：columnClick、swimlaneClick
• 事件参数类型和数据结构

数据持久化与状态

📄 阅读： references/data-persistence.md

• 将看板状态持久化到本地存储
• 保存卡片位置和列状态
• ObservableCollection 集成
• 页面重新加载后恢复状态
• 手动保存/恢复状态的模式

样式、主题与外观

📄 阅读： references/styling-and-theming.md

• 内置主题（Material、Bootstrap 3/4、Fabric、High Contrast）
• 自定义 CSS 变量
• 自定义卡片和列样式
• 支持深色模式
• 支持 RTL（从右向左）语言
• 集成 Theme Studio

无障碍与国际化

📄 阅读： references/accessibility-and-localization.md

• 符合 WCAG 标准并支持键盘导航
• 面向屏幕阅读器的 ARIA 属性
• 焦点管理和键盘快捷键
• 国际化（i18n）设置
• 多语言支持
• 区域设置数据配置

迁移与最佳实践

📄 阅读： references/migration-and-best-practices.md

• EJ1 到 EJ2 的迁移指南
• 性能优化策略
• 大型数据集的虚拟滚动
• 常见模式和代码示例
• 常见问题排查
• 常见问题解答和注意事项

快速入门示例

1. 安装软件包

npm install @syncfusion/ej2-angular-kanban

2. 导入并设置组件

import { Component } from '@angular/core';
import { KanbanModule } from '@syncfusion/ej2-angular-kanban';
import { CardSettingsModel } from '@syncfusion/ej2-angular-kanban';

@Component({
  selector: 'app-kanban-board',
  standalone: true,
  imports: [KanbanModule],
  template: `
    <ejs-kanban 
      keyField="Status" 
      [dataSource]="data"
      [cardSettings]="cardSettings">
      <e-columns>
        <e-column headerText="To Do" keyField="Open"></e-column>
        <e-column headerText="In Progress" keyField="InProgress"></e-column>
        <e-column headerText="Testing" keyField="Testing"></e-column>
        <e-column headerText="Done" keyField="Close"></e-column>
      </e-columns>
    </ejs-kanban>
  `
})
export class KanbanBoardComponent {
  data = [
    { Id: 1, Status: 'Open', Summary: 'Analyze the new requirements gathered from the customer.', Type: 'Epic' },
    { Id: 2, Status: 'InProgress', Summary: 'Improve application performance', Type: 'Epic' },
    { Id: 3, Status: 'Testing', Summary: 'Fix the issues reported in the IE browser', Type: 'Bug' },
    { Id: 4, Status: 'Close', Summary: 'Fix the issue reported by the customer.', Type: 'Bug' }
  ];

  cardSettings: CardSettingsModel = {
    headerField: 'Id',
    contentField: 'Summary'
  };
}

3. 添加样式

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-kanban/styles/material3.css';

常见模式

模式 1：按负责人启用泳道

按指定的团队成员对卡片分组：

swimlaneSettings: { keyField: 'Assignee' }

模式 2：强制执行 WIP 限制

设置每列卡片的最小/最大数量：

columns: [
  { headerText: 'To Do', keyField: 'Open', minCount: 1, maxCount: 5 },
  { headerText: 'In Progress', keyField: 'InProgress', minCount: 0, maxCount: 3 }
]

模式 3：处理卡片点击事件

监听卡片交互：

onCardClick(args: CardClickEventArgs): void {
  console.log('Card clicked:', args.data);
}

模式 4：以编程方式添加卡片

使用方法 API：

@ViewChild('kanban') kanban: KanbanComponent;

addNewCard(): void {
  this.kanban.addCard({
    Id: 5,
    Status: 'Open',
    Summary: 'New task'
  });
}

关键属性参考

属性	类型	用途
keyField	string	根据字段值将卡片映射到列
dataSource	Object[] | DataManager	包含卡片数据的数组或 DataManager 实例
cardSettings	CardSettingsModel	标题、内容和模板字段映射
columns	ColumnsModel[]	包含标题和键字段的列定义
swimlaneSettings	SwimlaneSettingsModel	按字段对泳道分组
allowDragAndDrop	boolean	启用卡片拖放（默认值：true）
allowKeyboard	boolean	启用键盘导航（默认值：true）
allowSelection	boolean	允许选择卡片
selectionType	'Single' | 'Multiple'	选择模式
height	string	看板高度
width	string	看板宽度

常见用例

1. 项目管理 - 跟踪任务从待办到完成的进度
2. Bug 跟踪 - 按状态（开放、进行中、测试中、已关闭）整理问题
3. 客户支持 - 管理工单直至解决
4. 敏捷冲刺看板 - 展示用户故事在各冲刺阶段的进展
5. 销售流程 - 跟踪潜在客户从意向客户到成交客户的进展
6. 内容工作流 - 管理文章从草稿到发布的流程
7. 招聘 - 按招聘阶段整理候选人
8. DevOps 流程 - 跟踪各环境中的部署

---

后续步骤： 根据当前需求，从上方导航指南中选择一个参考文件，或从入门指南开始设置你的第一个 Kanban 看板。