Back to Details

syncfusion-react-kanban

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion React Kanban

实现Syncfusion React Kanban

A comprehensive skill for working with Syncfusion's React Kanban component to build flexible task management boards with cards, columns, swimlanes, and drag-and-drop interactions.
这是一项用于使用Syncfusion的React Kanban组件构建灵活任务管理看板的综合技能，支持卡片、列、泳道和拖放交互。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Install and set up the Kanban component with Syncfusion
  • Create a basic Kanban board with columns and cards
  • Organize cards in swimlanes (group by category/assignee)
  • Implement drag-and-drop functionality between columns and swimlanes
  • Configure card displays with headers, content, templates, and tags
  • Bind data from arrays or APIs (DataManager, OData, REST)
  • Handle user interactions (card selection, drag events, double-click to edit)
  • Add dialogs for card creation and editing
  • Customize appearance with themes, CSS, and responsive design
  • Validate card counts with WIP (work-in-progress) min/max limits
  • Configure sorting, filtering, and search functionality
  • Apply custom tooltips, templates, and styling
  • Implement virtual scrolling for large datasets
  • Save board state and configuration
当你需要完成以下操作时可使用本技能：
  • 安装并配置Syncfusion的Kanban组件
  • 创建带有列和卡片的基础Kanban看板
  • 以泳道形式组织卡片（按类别/处理人分组）
  • 实现列与泳道之间的拖放功能
  • 配置卡片展示效果，包括头部、内容、模板和标签
  • 绑定数组或API（DataManager、OData、REST）中的数据
  • 处理用户交互（卡片选中、拖放事件、双击编辑）
  • 添加用于卡片创建和编辑的对话框
  • 通过主题、CSS和响应式设计自定义外观
  • 用WIP（在制品）最小/最大限制校验卡片数量
  • 配置排序、筛选和搜索功能
  • 应用自定义提示框、模板和样式
  • 为大型数据集实现虚拟滚动
  • 保存看板状态和配置

Component Overview

组件概览

The Kanban component provides a visual task management system with these core concepts:
Cards: Represent tasks or items. Each card displays a header (from a field) and content (from another field). Cards can have tags, custom templates, and be selected individually or in groups.
Columns: Define workflow stages (e.g., "To Do", "In Progress", "Done"). Each column has a header, can display item counts, and control drag/drop behavior independently.
Swimlanes: Optional horizontal grouping layers that organize cards by category (e.g., by user, priority, or team). Swimlanes help with organization and can have custom headers.
Drag-and-Drop: Built-in support for moving cards between columns, within columns, across swimlanes, or to external sources. Fully configurable per column.
Data Binding: Connect to static arrays or dynamic sources (DataManager with OData/REST APIs) for real-time updates.
Templates: Customize card layout, column headers, swimlane headers, tooltips, and dialogs with your own HTML/JSX.
Kanban组件提供了可视化任务管理系统，核心概念如下：
卡片：代表任务或条目。每张卡片展示头部（取自某个字段）和内容（取自另一个字段）。卡片可以携带标签、使用自定义模板，也可单独或批量选中。
列：定义工作流阶段（例如“待办”、“进行中”、“已完成”）。每列都有头部，可展示条目数量，独立控制拖放行为。
泳道：可选的水平分组层，可按类别（例如用户、优先级、团队）组织卡片。泳道有助于内容组织，也可自定义头部。
拖放：内置支持在列之间、列内部、跨泳道移动卡片，或移动到外部源。可针对每列完全自定义配置。
数据绑定：连接静态数组或动态源（对接OData/REST API的DataManager）实现实时更新。
模板：使用你自己的HTML/JSX自定义卡片布局、列头部、泳道头部、提示框和对话框。

Documentation and Navigation Guide

文档和导航指南

Choose the reference that matches your current need:
选择符合你当前需求的参考资料：

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installing @syncfusion/ej2-react-kanban
  • CSS theme imports (Material, Bootstrap, Fluent, Tailwind)
  • Basic Kanban component setup
  • Configuring dataSource and field mappings
  • First working example
📄 阅读： references/getting-started.md
  • 安装 @syncfusion/ej2-react-kanban
  • CSS主题导入（Material、Bootstrap、Fluent、Tailwind）
  • 基础Kanban组件配置
  • 配置dataSource和字段映射
  • 第一个可运行示例

Core Structure (Cards, Columns, Key Fields)

核心结构（卡片、列、关键字段）

📄 Read: references/core-structure.md
  • Card properties and cardSettings configuration
  • Column definition and properties
  • keyField mapping (linking cards to columns)
  • showHeader, showAddButton, showItemCount
  • Card templates and styling options
  • When to use default vs custom card layouts
📄 阅读： references/core-structure.md
  • 卡片属性和cardSettings配置
  • 列定义和属性
  • keyField映射（将卡片关联到对应列）
  • showHeader、showAddButton、showItemCount配置
  • 卡片模板和样式选项
  • 何时使用默认卡片布局 vs 自定义卡片布局

Swimlanes (Grouping Cards by Category)

泳道（按类别分组卡片）

📄 Read: references/swimlanes.md
  • What swimlanes are and when to use them
  • swimlaneSettings configuration
  • Grouping cards by category, user, priority, or team
  • Swimlane headers and custom rendering
  • Nested vs flat layout variations
📄 阅读： references/swimlanes.md
  • 什么是泳道以及何时使用泳道
  • swimlaneSettings配置
  • 按类别、用户、优先级或团队分组卡片
  • 泳道头部和自定义渲染
  • 嵌套布局与平级布局变体

Drag-and-Drop (Moving Cards and Managing Flow)

拖放（移动卡片和管理流程）

📄 Read: references/drag-and-drop.md
  • Internal drag-and-drop (column-to-column, within columns)
  • External drag-and-drop (Kanban-to-Kanban, to external sources)
  • allowDragAndDrop, allowDrag, allowDrop per column
  • transitionColumns to control valid transitions
  • Drag event handlers and preventing drops
📄 阅读： references/drag-and-drop.md
  • 内部拖放（列到列、列内部）
  • 外部拖放（看板到看板、拖到外部源）
  • 每列的allowDragAndDrop、allowDrag、allowDrop配置
  • transitionColumns控制合法移动路径
  • 拖放事件处理和禁止投放设置

Data Binding (Connecting to Data Sources)

数据绑定（连接数据源）

📄 Read: references/data-binding.md
  • Binding to static JSON arrays
  • DataManager integration with OData and REST APIs
  • Remote data sources and refresh patterns
  • Modifying data and triggering updates
  • Real-time data synchronization
📄 阅读： references/data-binding.md
  • 绑定静态JSON数组
  • DataManager对接OData和REST API
  • 远程数据源和刷新机制
  • 修改数据和触发更新
  • 实时数据同步

Templates and Dialogs (Custom Content and Card Editing)

模板和对话框（自定义内容和卡片编辑）

📄 Read: references/dialogs-and-templates.md
  • Card templates (custom card layout)
  • Column header templates
  • Swimlane header templates
  • Tooltip templates and configuration
  • Dialog setup for adding/editing cards
  • Template syntax and event handling
📄 阅读： references/dialogs-and-templates.md
  • 卡片模板（自定义卡片布局）
  • 列头部模板
  • 泳道头部模板
  • 提示框模板和配置
  • 新增/编辑卡片的对话框配置
  • 模板语法和事件处理

Sorting, Filtering, and Work-in-Progress (WIP) Validation

排序、筛选和在制品（WIP）校验

📄 Read: references/sorting-filtering-and-search.md
  • Sort settings and card ordering
  • Min/max card count per column (WIP limits)
  • Allow sorting and searching
  • Filtering and search patterns
  • Selection modes (Single/Multiple)
  • Handling validation errors
📄 阅读： references/sorting-filtering-and-search.md
  • 排序设置和卡片排序规则
  • 每列的最小/最大卡片数量（WIP限制）
  • 启用排序和搜索
  • 筛选和搜索机制
  • 选中模式（单选/多选）
  • 校验错误处理

Customization and Styling (Themes, Responsive, Advanced Features)

自定义和样式（主题、响应式、高级功能）

📄 Read: references/customization-and-styling.md
  • Built-in themes (Material, Bootstrap, Fluent, Tailwind)
  • CSS customization and variables
  • Responsive design behavior
  • Virtual scrolling for large datasets
  • Persistence (saving card state to storage)
  • Localization (multi-language support)
  • Accessibility (ARIA, keyboard navigation)
📄 阅读： references/customization-and-styling.md
  • 内置主题（Material、Bootstrap、Fluent、Tailwind）
  • CSS自定义和变量
  • 响应式设计行为
  • 大型数据集的虚拟滚动
  • 持久化（将卡片状态保存到存储）
  • 本地化（多语言支持）
  • 无障碍功能（ARIA、键盘导航）

Properties (Configuration and Settings)

属性（配置和设置）

📄 Read: references/properties.md
  • All configurable properties with type definitions
  • cardSettings, columns, swimlaneSettings configuration
  • Core properties (allowDragAndDrop, keyField, dataSource)
  • Dialog settings and advanced options
  • Complete configuration examples
  • Decision trees for common configuration patterns
📄 阅读： references/properties.md
  • 所有可配置属性及类型定义
  • cardSettings、columns、swimlaneSettings配置
  • 核心属性（allowDragAndDrop、keyField、dataSource）
  • 对话框设置和高级选项
  • 完整配置示例
  • 常见配置场景的决策树

Methods (Programmatic Control and Actions)

方法（程序化控制和操作）

📄 Read: references/methods.md
  • Card management (addCard, updateCard, deleteCard)
  • Column management (addColumn, deleteColumn, hideColumn, showColumn)
  • Data access methods (getSelectedCards, getCardDetails, getColumnData, getSwimlaneData)
  • UI control methods (showSpinner, hideSpinner, refreshUI, openDialog, closeDialog)
  • Common programmatic patterns (bulk operations, reordering, duplication)
  • Using refs to access methods from parent components
📄 阅读： references/methods.md
  • 卡片管理（addCard、updateCard、deleteCard）
  • 列管理（addColumn、deleteColumn、hideColumn、showColumn）
  • 数据访问方法（getSelectedCards、getCardDetails、getColumnData、getSwimlaneData）
  • UI控制方法（showSpinner、hideSpinner、refreshUI、openDialog、closeDialog）
  • 常见程序化操作模式（批量操作、重排序、复制）
  • 使用refs从父组件调用方法

Events (Handling User Interactions and Data Changes)

事件（处理用户交互和数据变更）

📄 Read: references/events.md
  • Card events (cardClick, cardDoubleClick, cardRendered, cardSelectionChanging)
  • Dialog events (dialogOpen, dialogClose)
  • Drag-drop events (dragStart, drag, dragStop)
  • Data events (dataBinding, dataBound, actionBegin, actionComplete, actionFailure)
  • Lifecycle events (created)
  • Event validation and prevention patterns
📄 阅读： references/events.md
  • 卡片事件（cardClick、cardDoubleClick、cardRendered、cardSelectionChanging）
  • 对话框事件（dialogOpen、dialogClose）
  • 拖放事件（dragStart、drag、dragStop）
  • 数据事件（dataBinding、dataBound、actionBegin、actionComplete、actionFailure）
  • 生命周期事件（created）
  • 事件校验和拦截机制

Quick Start Example

快速开始示例

Here's a minimal Kanban board with 3 columns and 5 cards:
tsx
import React from 'react';
import { KanbanComponent, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-kanban';
import '@syncfusion/ej2-react-kanban/styles/material.css';


export default function KanbanQuickStart(): JSX.Element {
  const kanbanData: { [key: string]: Object } = [
    { Id: '1', Status: 'Open', Summary: 'Analyze requirements' },
    { Id: '2', Status: 'Open', Summary: 'Design UI mockups' },
    { Id: '3', Status: 'InProgress', Summary: 'Implement backend API' },
    { Id: '4', Status: 'InProgress', Summary: 'Build frontend components' },
    { Id: '5', Status: 'Closed', Summary: 'Deploy to production' }
  ];

  return (
    <KanbanComponent
      dataSource={kanbanData}
      keyField="Status"
      cardSettings={{ contentField: 'Summary' }}
    >
      <ColumnsDirective>
        <ColumnDirective key="0" keyField="Open" headerText="Open" />
        <ColumnDirective key="1" keyField="InProgress" headerText="In Progress" />
        <ColumnDirective key="2" keyField="Closed" headerText="Closed" />
      </ColumnsDirective>
    </KanbanComponent>
  );
}
What this does:
  • Creates 3 workflow columns (Open, InProgress, Closed)
  • Maps cards to columns using the 
    Status
    field
  • Displays 5 cards with their Summary text
  • Enables drag-and-drop by default
以下是包含3列和5张卡片的最简Kanban看板：
tsx
import React from 'react';
import { KanbanComponent, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-kanban';
import '@syncfusion/ej2-react-kanban/styles/material.css';


export default function KanbanQuickStart(): JSX.Element {
  const kanbanData: { [key: string]: Object } = [
    { Id: '1', Status: 'Open', Summary: 'Analyze requirements' },
    { Id: '2', Status: 'Open', Summary: 'Design UI mockups' },
    { Id: '3', Status: 'InProgress', Summary: 'Implement backend API' },
    { Id: '4', Status: 'InProgress', Summary: 'Build frontend components' },
    { Id: '5', Status: 'Closed', Summary: 'Deploy to production' }
  ];

  return (
    <KanbanComponent
      dataSource={kanbanData}
      keyField="Status"
      cardSettings={{ contentField: 'Summary' }}
    >
      <ColumnsDirective>
        <ColumnDirective key="0" keyField="Open" headerText="Open" />
        <ColumnDirective key="1" keyField="InProgress" headerText="In Progress" />
        <ColumnDirective key="2" keyField="Closed" headerText="Closed" />
      </ColumnsDirective>
    </KanbanComponent>
  );
}
代码功能：
  • 创建3个工作流列（Open、InProgress、Closed）
  • 使用
    Status
    字段将卡片映射到对应列
  • 展示5张卡片及其摘要文本
  • 默认启用拖放功能

Common Patterns

常见模式

Pattern 1: Add Swimlanes to Group Cards by User

模式1：添加泳道按用户分组卡片

tsx
import { KanbanComponent, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-kanban';

<KanbanComponent
  dataSource={kanbanData}
  keyField="Status"
  cardSettings={{ contentField: 'Summary' }}
  swimlaneSettings={{ keyField: 'Assignee' }}
>
  <ColumnsDirective>
    <ColumnDirective keyField="Open" headerText="Open" />
    <ColumnDirective keyField="InProgress" headerText="In Progress" />
    <ColumnDirective keyField="Closed" headerText="Closed" />
  </ColumnsDirective>
</KanbanComponent>
Cards are now grouped horizontally by the 
Assignee
field, making it easy to see each user's tasks.
tsx
import { KanbanComponent, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-kanban';

<KanbanComponent
  dataSource={kanbanData}
  keyField="Status"
  cardSettings={{ contentField: 'Summary' }}
  swimlaneSettings={{ keyField: 'Assignee' }}
>
  <ColumnsDirective>
    <ColumnDirective keyField="Open" headerText="Open" />
    <ColumnDirective keyField="InProgress" headerText="In Progress" />
    <ColumnDirective keyField="Closed" headerText="Closed" />
  </ColumnsDirective>
</KanbanComponent>
现在卡片会按
Assignee
字段水平分组，方便查看每个用户的任务。

Pattern 2: Prevent Drag-Drop in Specific Columns

模式2：禁止特定列的拖放操作

tsx
import { ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-kanban';

<ColumnsDirective>
  <ColumnDirective keyField="Open" headerText="Open" allowDrag={true} allowDrop={true} />
  <ColumnDirective keyField="Closed" headerText="Closed" allowDrag={false} allowDrop={false} />
</ColumnsDirective>
Users can drag cards into "Open", but once in "Closed", cards are locked (read-only).
tsx
import { ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-kanban';

<ColumnsDirective>
  <ColumnDirective keyField="Open" headerText="Open" allowDrag={true} allowDrop={true} />
  <ColumnDirective keyField="Closed" headerText="Closed" allowDrag={false} allowDrop={false} />
</ColumnsDirective>
用户可将卡片拖入“Open”列，但卡片一旦进入“Closed”列就会被锁定（只读）。

Pattern 3: Validate Card Counts with WIP Limits

模式3：使用WIP限制校验卡片数量

tsx
import { ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-kanban';

<ColumnsDirective>
  <ColumnDirective 
    keyField="InProgress" 
    headerText="In Progress" 
    maxCount={5}
    minCount={1}
  />
</ColumnsDirective>
The board will warn users if column has fewer than 1 or more than 5 cards, enforcing work-in-progress limits.
tsx
import { ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-kanban';

<ColumnsDirective>
  <ColumnDirective 
    keyField="InProgress" 
    headerText="In Progress" 
    maxCount={5}
    minCount={1}
  />
</ColumnsDirective>
如果列内卡片少于1张或多于5张，看板会向用户发出警告，强制遵守在制品数量限制。

Pattern 4: Handle Card Double-Click to Edit

模式4：处理卡片双击编辑事件

tsx
import { CardClickEventArgs } from '@syncfusion/ej2-react-kanban';

const handleCardDoubleClick = (args: CardClickEventArgs): void => {
  console.log('Card clicked:', args.data);
  // Open a dialog or form to edit the card
};

<KanbanComponent
  dataSource={kanbanData}
  cardDoubleClick={handleCardDoubleClick}
>
  {/* ... */}
</KanbanComponent>
This pattern enables inline editing workflows.
tsx
import { CardClickEventArgs } from '@syncfusion/ej2-react-kanban';

const handleCardDoubleClick = (args: CardClickEventArgs): void => {
  console.log('Card clicked:', args.data);
  // Open a dialog or form to edit the card
};

<KanbanComponent
  dataSource={kanbanData}
  cardDoubleClick={handleCardDoubleClick}
>
  {/* ... */}
</KanbanComponent>
该模式可实现内嵌编辑工作流。

Pattern 5: Bind Kanban to a Remote API

模式5：将Kanban绑定到远程API

tsx
import { DataManager, UrlAdaptor } from '@syncfusion/ej2-data';

const dataManager: DataManager = new DataManager({
  url: 'https://api.example.com/tasks',
  adaptor: new UrlAdaptor()
});

<KanbanComponent
  dataSource={dataManager}
  keyField="Status"
  cardSettings={{ contentField: 'Summary' }}
>
  {/* ... */}
</KanbanComponent>
tsx
import { DataManager, UrlAdaptor } from '@syncfusion/ej2-data';

const dataManager: DataManager = new DataManager({
  url: 'https://api.example.com/tasks',
  adaptor: new UrlAdaptor()
});

<KanbanComponent
  dataSource={dataManager}
  keyField="Status"
  cardSettings={{ contentField: 'Summary' }}
>
  {/* ... */}
</KanbanComponent>