syncfusion-vue-kanban

实现 Syncfusion Vue Kanban

基于列的任务看板，按状态字段对卡片进行分组，支持拖放重排、泳道行分组、列验证（WIP 限制），以及针对大型数据集的虚拟滚动。

何时使用此技能

• 用户需要带有状态列（待办、进行中、已完成等）的 Kanban / 冲刺看板
• 用户希望在列之间或泳道行之间拖放卡片
• 用户需要将 Kanban 绑定到 REST API、OData 或本地 JSON 数据集
• 用户希望按负责人、团队或任意字段对卡片分组（泳道）
• 用户需要 WIP 限制（每列卡片数量的最小值 / 最大值）
• 用户希望在不影响性能的情况下，对 1000 张以上的卡片进行虚拟滚动
• 用户希望使用模板自定义卡片布局或应用自定义 CSS

组件概览

概念	功能
keyField	看板级字段，用于将数据记录映射到列（例如 "Status"）
cardSettings	指定 headerField（唯一 ID）和 contentField（正文文本）
<e-columns>	声明每个看板列；列上的 keyField 与数据值匹配
swimlaneSettings	按数据字段将卡片分组到水平行中
allowDragAndDrop	启用 / 禁用列间卡片拖动（默认值：true）
enableVirtualization	为大型数据集启用虚拟滚动

文档和导航指南

组件概览

📄 阅读： references/overview.md

• 完整的功能列表及说明（拖放、泳道、WIP、虚拟滚动等）
• 将用户需求与功能匹配的使用场景决策表
• 软件包安装和所有必需的 CSS 导入项
• 最小可运行示例

无障碍访问

📄 阅读： references/accessibility.md

• WCAG 2.2 和 Section 508 合规性摘要
• 所有 WAI-ARIA 属性（aria-label、aria-expanded、aria-selected、aria-grabbed 等）
• 完整的键盘快捷键参考
• 禁用键盘交互（allowKeyboard: false）
• 屏幕阅读器支持详情
• 使用 enableRtl 实现 RTL 无障碍访问
• 使用 axe-core 和无障碍检查工具进行测试

入门指南

📄 阅读： references/getting-started.md

• Vite + Vue 3 项目设置
• 软件包安装（@syncfusion/ej2-vue-kanban）
• CSS 导入项（tailwind3 主题）
• 带列的最小 Kanban
• 从本地数据数组填充卡片
• 首次渲染时启用泳道

数据绑定

📄 阅读： references/data-binding.md

• 绑定本地 JSON 数组
• 使用 DataManager + ODataAdaptor / ODataV4Adaptor 绑定远程数据
• 使用 WebApiAdaptor 绑定 Web API
• 使用 UrlAdaptor 执行 CRUD 操作（insertUrl、updateUrl、removeUrl）
• 通过扩展 ODataAdaptor 创建自定义适配器
• 使用 Query.addParams 发送额外查询参数
• 通过 Ajax 动态加载数据
• 使用 actionFailure 处理 HTTP 错误

卡片

📄 阅读： references/cards.md

• headerField（必需的唯一 ID）和 contentField
• 使用 showHeader: false 隐藏卡片标题
• 使用 Vue 组件模板自定义卡片布局
• 卡片选择：无 / 单选 / 多选（selectionType）
• 使用 Ctrl+单击 / Shift+单击进行多选

列

📄 阅读： references/columns.md

• 单键和多键列映射
• 列标题文本和标题模板
• 使用 allowToggle 切换列（展开 / 折叠）
• 初始以折叠状态呈现列（isExpanded: false）
• 将多个列分组的堆叠标题
• 列级别的拖放重排（allowColumnDragAndDrop）

对话框（添加 / 编辑 / 删除卡片）

📄 阅读： references/dialog.md

• 默认内置对话框（双击打开）
• 使用 dialogSettings.fields 自定义对话框字段
• 自定义字段标签和字段类型
• 使用 validationRules 验证字段
• 使用 Vue 组件创建完整对话框模板
• 使用 dialogOpen 事件阻止打开对话框
• 以编程方式调用 openDialog() 和 closeDialog()

尺寸（高度和宽度）

📄 阅读： references/dimensions.md

• 自动高度 / 宽度（默认）
• 像素尺寸（height="550px"、:width="650"）
• 百分比尺寸（width="100%"、height="100%"）
• 各模式的适用场景

事件

📄 阅读： references/events.md

• 操作事件：actionBegin、actionComplete、actionFailure
• 卡片事件：cardClick、cardDoubleClick、cardRendered
• 列拖动事件：columnDragStart、columnDrag、columnDrop
• 数据事件：dataBinding、dataBound、dataSourceChanged、dataStateChange
• 对话框事件：dialogOpen、dialogClose
• 卡片拖动事件：dragStart、drag、dragStop
• 生命周期：created、queryCellInfo

泳道

📄 阅读： references/swimlane.md

• 使用 swimlaneSettings.keyField 渲染泳道行
• 使用 textField 自定义行标签文本
• 自定义泳道标题模板
• 对行进行排序（升序 / 降序）
• 跨行拖放（在 swimlaneSettings 中设置 allowDragAndDrop: true）
• 显示空行（showEmptyRow）
• 卡片计数徽标（showItemCount）
• 滚动时固定泳道标题（enableFrozenRows）

拖放

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

• 全局禁用拖放（allowDragAndDrop: false）
• 按列控制拖放（allowDrag、allowDrop）
• 跨泳道拖放
• Kanban 到 Kanban 的拖放（externalDropId、dragStop、addCard、deleteCard）
• Kanban 到 TreeView 的拖放
• Kanban 到 Scheduler 的拖放

本地化和 RTL

📄 阅读： references/localization.md

• 所有区域设置键参考表
• 使用 L10n.load() 加载翻译
• 在看板上设置 locale 属性
• 使用 enableRtl 启用从右到左（RTL）模式

公共方法

📄 阅读： references/methods.md

• 卡片 CRUD：addCard、updateCard、deleteCard、getCardDetails
• 列方法：addColumn、deleteColumn、showColumn、hideColumn、getColumnData
• 对话框：openDialog、closeDialog
• 数据：getSwimlaneData
• 选择：getSelectedCards
• UI：refreshHeader、refreshUI、showSpinner、hideSpinner、destroy

状态持久化

📄 阅读： references/persistence.md

• 启用 enablePersistence，将状态保存到 localStorage
• 持久化的状态：数据源、列的展开 / 折叠、泳道的展开 / 折叠
• 设置唯一的 id 以避免键冲突
• 清除持久化状态

优先级和排序设置

📄 阅读： references/priority-and-sort.md

• 使用 cardSettings.priority 按排名定位卡片
• sortSettings.sortBy：'Index'、'DataSourceOrder'、'Custom'
• 使用 sortSettings.field 映射排序字段
• sortSettings.direction：'Ascending' / 'Descending'

响应式模式

📄 阅读： references/responsive-mode.md

• 移动端布局：列尺寸、滑动导航、长按拖动
• 移动端泳道弹出菜单
• 在触屏设备上单选和多选卡片

工具提示

📄 阅读： references/tooltip.md

• 启用默认卡片工具提示（enableTooltip）
• 使用 e-tooltip-text 类为自定义元素显示工具提示
• 通过 tooltipTemplate 设置自定义工具提示模板

自定义与故障排除

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

• CSS 类参考表
• 粘性／固定列标题
• 列 WIP 验证（minCount、maxCount、constraintType）
• WAI-ARIA 属性
• 完整的键盘快捷键参考
• 主题工作室

虚拟滚动

📄 阅读： references/virtual-scrolling.md

• 启用虚拟化（enableVirtualization: true）
• 以像素为单位设置 cardHeight
• 虚拟滚动的远程数据服务配置
• 已知限制（泳道与虚拟化、卡片位置、% 高度）

操作指南

📄 阅读： references/how-to.md

• 在运行时动态更改列属性
• 在运行时替换所有列
• 使用 Query 筛选卡片
• 使用 Query.search() 按文本搜索卡片
• 处理列标题双击事件

属性参考

📄 阅读： references/properties.md

• 完整的根级属性表（所有类型、默认值和说明）
• cardSettings 子属性（headerField、contentField、selectionType、priority 等）
• columns 子属性（keyField、allowToggle、minCount、maxCount、transitionColumns 等）
• dialogSettings 和 DialogFieldsModel 字段
• sortSettings、swimlaneSettings、stackedHeaders 接口
• 所有枚举值：SelectionType、ConstraintType、SortOrderBy、SortDirection

样式与 CSS 自定义

📄 阅读： references/style.md

• 标题单元格和 WIP 限制指示器的完整 CSS 类参考表
• 卡片元素的 CSS 类（标题、内容、页脚、标签、颜色条）
• 泳道行和单元格的 CSS 选择器
• 紧凑型表格作用域选择器变体
• 固定／粘性看板标题（基于高度和 position: sticky）
• 用于生成自定义主题的主题工作室

验证（WIP 限制）

📄 阅读： references/validation.md

• minCount — 每列／单元格所需的最少卡片数
• maxCount — 每列／单元格允许的最多卡片数
• constraintType：'Column'（默认）或 'Swimlane' 作用范围
• 视觉反馈：超出限制时的高亮颜色
• 用于自定义验证高亮颜色的 CSS 类

快速开始

<template>
  <div id="app">
    <ejs-kanban id="kanban" keyField="Status" :dataSource="kanbanData" :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>
  </div>
</template>

<script setup>
import { KanbanComponent as EjsKanban, ColumnDirective as EColumn, ColumnsDirective as EColumns }
  from '@syncfusion/ej2-vue-kanban';
import { extend } from '@syncfusion/ej2-base';

const rawData = [
  { Id: 1, Status: 'Open',       Summary: 'Analyze requirements', Assignee: 'Nancy' },
  { Id: 2, Status: 'InProgress', Summary: 'Improve performance',  Assignee: 'Andrew' },
  { Id: 3, Status: 'Testing',    Summary: 'Fix IE browser bug',   Assignee: 'Janet' },
  { Id: 4, Status: 'Close',      Summary: 'Deploy to production', Assignee: 'Nancy' },
];

const kanbanData = extend([], rawData, null, true);
const cardSettings = { contentField: 'Summary', headerField: 'Id' };
</script>

<style>
@import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css';
@import '../node_modules/@syncfusion/ej2-vue-kanban/styles/tailwind3.css';
</style>

常见模式

添加泳道（按负责人分组）

<ejs-kanban keyField="Status" :dataSource="kanbanData"
  :cardSettings="cardSettings" :swimlaneSettings="swimlaneSettings">
  ...columns...
</ejs-kanban>

<script setup>
const swimlaneSettings = { keyField: 'Assignee' };
</script>

绑定到远程 OData 服务

<script setup>
import { DataManager, ODataAdaptor } from '@syncfusion/ej2-data';

const kanbanData = new DataManager({
  url: 'https://your-api.com/api/Tasks',
  adaptor: new ODataAdaptor(),
  crossDomain: true
});
</script>

在列上启用 WIP 限制

<e-column headerText="In Progress" keyField="InProgress" :maxCount="5" :minCount="1"></e-column>

为大型数据集启用虚拟滚动

<ejs-kanban :enableVirtualization="true" keyField="Status" :dataSource="largeDataset"
  :cardSettings="{ headerField: 'Id', contentField: 'Summary' }">
  ...
</ejs-kanban>

关键属性参考

属性	类型	用途
keyField	String	将记录映射到列的数据字段
dataSource	Array / DataManager	卡片数据源
cardSettings	Object	headerField（必需）、contentField、template、selectionType
swimlaneSettings	Object	keyField、textField、allowDragAndDrop、showEmptyRow、enableFrozenRows
allowDragAndDrop	Boolean	看板级卡片拖放（默认：true）
allowColumnDragAndDrop	Boolean	通过拖动标题重新排列列
enableVirtualization	Boolean	为大型数据集启用虚拟滚动
enableTooltip	Boolean	鼠标悬停在卡片上时显示工具提示
constraintType	String	用于 WIP 验证的 'Column' 或 'Swimlane'