syncfusion-react-kanban

实现 Syncfusion React Kanban

一份全面的技能指南，介绍如何使用 Syncfusion 的 React Kanban 组件，构建灵活的任务管理看板，支持卡片、列、泳道和拖放交互。

何时使用此技能

在以下情况下使用此技能：

• 使用 Syncfusion 安装和设置 Kanban 组件
• 创建包含列和卡片的基础 Kanban 看板
• 在泳道中组织卡片（按类别/负责人分组）
• 实现列和泳道之间的拖放功能
• 配置卡片显示内容，包括标题、正文、模板和标签
• 绑定来自数组或 API（DataManager、OData、REST）的数据
• 处理用户交互（卡片选择、拖动事件、双击编辑）
• 添加用于创建和编辑卡片的对话框
• 使用主题、CSS 和响应式设计自定义外观
• 使用 WIP（进行中）最小值/最大值限制验证卡片数量
• 配置排序、筛选和搜索功能
• 应用自定义工具提示、模板和样式
• 为大型数据集实现虚拟滚动
• 保存看板状态和配置

组件概览

Kanban 组件提供了一个可视化任务管理系统，包含以下核心概念：

卡片：表示任务或事项。每张卡片都会显示标题（取自一个字段）和正文（取自另一个字段）。卡片可以包含标签、自定义模板，也可以单独或成组选择。

列：定义工作流阶段（例如“待办”、“进行中”、“已完成”）。每列都有标题，可以显示事项数量，并可独立控制拖放行为。

泳道：可选的水平分组层，用于按类别（例如用户、优先级或团队）组织卡片。泳道有助于整理卡片，也可以设置自定义标题。

拖放：内置支持在列之间、列内、泳道之间移动卡片，也支持拖放到外部来源。可按列进行完整配置。

数据绑定：连接到静态数组或动态数据源（使用 OData/REST API 的 DataManager），以便实时更新。

模板：使用自己的 HTML/JSX 自定义卡片布局、列标题、泳道标题、工具提示和对话框。

文档和导航指南

选择与当前需求相符的参考资料：

入门

📄 阅读： references/getting-started.md

• 安装 @syncfusion/ej2-react-kanban
• 导入 CSS 主题（Material、Bootstrap、Fluent、Tailwind）
• 设置基础 Kanban 组件
• 配置 dataSource 和字段映射
• 第一个可运行示例

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

📄 阅读： references/core-structure.md

• 卡片属性和 cardSettings 配置
• 列定义和属性
• keyField 映射（将卡片关联到列）
• showHeader、showAddButton、showItemCount
• 卡片模板和样式选项
• 何时使用默认卡片布局，何时使用自定义布局

泳道（按类别对卡片分组）

📄 阅读： references/swimlanes.md

• 泳道的定义及适用场景
• swimlaneSettings 配置
• 按类别、用户、优先级或团队对卡片分组
• 泳道标题和自定义渲染
• 嵌套与扁平布局的变化形式

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

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

• 内部拖放（列与列之间、列内）
• 外部拖放（Kanban 到 Kanban、拖放到外部来源）
• 按列设置 allowDragAndDrop、allowDrag、allowDrop
• 使用 transitionColumns 控制有效转换
• 拖动事件处理程序和阻止放置

数据绑定（连接数据源）

📄 阅读： references/data-binding.md

• 绑定到静态 JSON 数组
• 集成使用 OData 和 REST API 的 DataManager
• 远程数据源和刷新模式
• 修改数据并触发更新
• 实时数据同步

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

📄 阅读： references/dialogs-and-templates.md

• 卡片模板（自定义卡片布局）
• 列标题模板
• 泳道标题模板
• 工具提示模板和配置
• 添加/编辑卡片的对话框设置
• 模板语法和事件处理

排序、筛选和进行中（WIP）验证

📄 阅读： references/sorting-filtering-and-search.md

• 排序设置和卡片排序
• 每列的卡片数量下限/上限（WIP 限制）
• 允许排序和搜索
• 筛选和搜索模式
• 选择模式（单选/多选）
• 处理验证错误

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

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

• 内置主题（Material、Bootstrap、Fluent、Tailwind）
• CSS 自定义和变量
• 响应式设计行为
• 大型数据集的虚拟滚动
• 持久化（将卡片状态保存到存储中）
• 本地化（多语言支持）
• 无障碍功能（ARIA、键盘导航）

属性（配置和设置）

📄 阅读： references/properties.md

• 所有可配置属性及其类型定义
• cardSettings、columns、swimlaneSettings 配置
• 核心属性（allowDragAndDrop、keyField、dataSource）
• 对话框设置和高级选项
• 完整配置示例
• 常见配置模式的决策树

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

📄 阅读： references/methods.md

• 卡片管理（addCard、updateCard、deleteCard）
• 列管理（addColumn、deleteColumn、hideColumn、showColumn）
• 数据访问方法（getSelectedCards、getCardDetails、getColumnData、getSwimlaneData）
• UI 控制方法（showSpinner、hideSpinner、refreshUI、openDialog、closeDialog）
• 常见程序化模式（批量操作、重新排序、复制）
• 使用 refs 从父组件访问方法

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

📄 阅读： references/events.md

• 卡片事件（cardClick、cardDoubleClick、cardRendered、cardSelectionChanging）
• 对话框事件（dialogOpen、dialogClose）
• 拖放事件（dragStart、drag、dragStop）
• 数据事件（dataBinding、dataBound、actionBegin、actionComplete、actionFailure）
• 生命周期事件（created）
• 事件验证和阻止模式

快速入门示例

以下是一个包含 3 列和 5 张卡片的最简看板：

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 张卡片及其 Summary 文本
• 默认启用拖放

常见模式

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

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 字段水平分组，方便查看每位用户的任务。

模式 2：禁止在特定列中拖放

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” 后将被锁定（只读）。

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

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

<ColumnsDirective>
  <ColumnDirective 
    keyField="InProgress" 
    headerText="In Progress" 
    maxCount={5}
    minCount={1}
  />
</ColumnsDirective>

如果某列的卡片少于 1 张或多于 5 张，看板会向用户发出警告，以强制执行进行中工作的限制。

模式 4：处理卡片双击以进行编辑

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>

此模式支持内联编辑工作流。

模式 5：将看板绑定到远程 API

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>