syncfusion-aspnetcore-kanban

实现 Syncfusion ASP.NET Core Kanban

目录

• 快速入门
• 何时使用此技能
• 文档与导航指南
  • 设置与创建首个看板
  • 数据绑定
  • 卡片
  • 列
  • 泳道
  • 拖放
  • 卡片编辑对话框
  • 排序、优先级与验证
  • 工具提示、样式与尺寸
  • 持久化、本地化与响应式
  • 虚拟滚动与无障碍功能
  • 事件
  • 方法
  • 所有属性参考
  • 操作指南
• 常见模式
• 关键属性参考
• 数据模型

快速入门

// HomeController.cs
public IActionResult Index()
{
    ViewBag.data = new KanbanDataModels().KanbanTasks();
    return View();
}

<ejs-kanban id="Kanban" keyField="Status" dataSource="@ViewBag.data">
    <e-kanban-columns>
        <e-kanban-column headerText="To Do" keyField="Open"></e-kanban-column>
        <e-kanban-column headerText="In Progress" keyField="InProgress"></e-kanban-column>
        <e-kanban-column headerText="Testing" keyField="Testing"></e-kanban-column>
        <e-kanban-column headerText="Done" keyField="Close"></e-kanban-column>
    </e-kanban-columns>
    <e-kanban-cardsettings headerField="Title" contentField="Summary"></e-kanban-cardsettings>
</ejs-kanban>

先决条件：

• NuGet：Install-Package Syncfusion.EJ2.AspNet.Core
• _ViewImports.cshtml：@addTagHelper *, Syncfusion.EJ2
• _Layout.cshtml：Fluent CSS + ej2.min.js CDN 链接 + <ejs-scripts></ejs-scripts>

→ 如需完整的设置详情，请参阅 references/getting-started.md

何时使用此技能

在需要以下操作时使用此技能：

• 构建 Kanban 看板 — 可视化多列工作流
• 配置列 — 单键/多键列、堆叠标题、切换、拖动
• 添加泳道 — 按团队、用户或类别对卡片分组，并使用冻结行
• 启用拖放 — 在列、泳道或外部组件之间拖放
• 实现卡片对话框 — 带自定义字段、模板和 CRUD 持久化功能的编辑对话框
• 绑定远程数据 — 使用 OData、WebAPI、UrlAdaptor 执行 CRUD 操作
• 应用排序 — 按索引、数据源顺序或自定义字段排序
• 设置卡片优先级 — 通过数值排名字段，按确切位置放置卡片
• 添加列约束 — 验证每列卡片数量的最小值/最大值
• 显示工具提示 — 使用默认或基于模板的悬停提示
• 启用虚拟滚动 — 高效处理大型数据集（100k+ 张卡片）
• 配置无障碍功能 — WCAG 2.2 AA、键盘导航和屏幕阅读器支持
• 本地化或启用 RTL — 多语言支持和从右到左的布局
• 筛选或搜索卡片 — 使用 query 属性
• 动态更改列 — 在运行时更新列配置
• 处理事件 — 响应卡片点击、拖动、对话框打开/关闭、数据绑定等操作
• 以编程方式调用方法 — 添加/更新/删除卡片、打开对话框、显示/隐藏列、刷新看板
• 查阅所有属性 — 查看组件和子模型属性的完整列表、类型及默认值

文档与导航指南

设置与创建首个看板

📄 阅读： references/getting-started.md

• 安装 NuGet 并设置程序包
• 在 _ViewImports.cshtml 中注册 Tag Helper
• 在 _Layout.cshtml 中配置 CDN（CSS + JS）
• 包含 4 列的最简 Kanban 看板
• 泳道快速入门
• 注册许可证密钥

数据绑定

📄 阅读： references/data-binding.md

• 通过 @ViewBag.data 绑定本地数据
• 远程数据：OData、ODataV4、WebAPI、UrlAdaptor
• 配置 <e-data-manager>
• 使用 insertUrl、updateUrl、removeUrl、crudUrl 执行 CRUD 操作
• 自定义适配器模式
• 处理 actionFailure 事件
• Ajax 加载指示器行为

卡片

📄 阅读： references/cards.md

• headerField（必需的唯一卡片 ID）
• showHeader — 显示/隐藏卡片标题
• contentField — 卡片正文文本字段
• 使用 jsrender 语法的卡片模板
• selectionType — None、Single、Multiple
• 通过 colorField 自定义卡片颜色

列

📄 阅读： references/columns.md

• 单键和多键 keyField 映射
• headerText — 列显示名称
• 列标题模板
• allowToggle — 可折叠列
• isExpanded — 初始展开／折叠状态
• 分组标题（<e-kanban-stackedheaders>）
• 列级拖动（allowColumnDragAndDrop）
• showItemCount — 在标题中显示卡片数量

泳道

📄 阅读： references/swimlane.md

• keyField — 用于分组的数据字段
• textField — 显示标签字段
• 泳道标题模板
• sortBy — 对泳道行排序
• allowDragAndDrop — 启用跨泳道卡片拖动
• showEmptyRow — 显示空泳道行
• showItemCount — 每条泳道中的卡片数量
• enableFrozenRows — 滚动时固定泳道标题

拖放

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

• 内部列拖动（默认启用）
• allowDragAndDrop="false" — 禁用所有拖动
• 每列的 allowDrag/allowDrop 标志
• transitionColumns — 限制允许的列间转换
• 通过 swimlaneSettings.allowDragAndDrop 跨泳道拖动
• 外部拖动：externalDropId 属性
• Kanban 到 Kanban 的拖动（dragStop 事件 + deleteCard/addCard）
• Kanban 与 Treeview 和 Schedule 的集成

卡片编辑对话框

📄 阅读： references/dialog.md

• 默认对话框（双击卡片）
• 通过 <e-kanban-dialogsettings fields="..."> 设置自定义对话框字段
• 字段类型：String、Numeric、TextArea、DropDown、TextBox、Input
• 使用 EJ2 组件初始化的自定义对话框模板
• 通过 dialogOpen 事件 + args.cancel = true 阻止打开对话框
• 以编程方式添加：kanbanObj.openDialog('Add', data)
• 通过 UrlAdaptor 和服务器端 EditParams 类实现 CRUD 持久化

排序、优先级和验证

📄 阅读： references/sorting-priority-validation.md

• 使用 sortBy、field、direction 的 <e-kanban-sortsettings>
• sortBy 值：Index、DataSourceOrder、Custom
• 优先级字段：<e-kanban-cardsettings priority="RankId">，用于精确位置放置
• 列的卡片数量最小值／最大值：<e-kanban-column> 上的 minCount、maxCount
• 约束类型：Column（默认）或 Swimlane
• 违反约束时显示颜色提示

工具提示、样式和尺寸

📄 阅读： references/tooltip-style-dimensions.md

• enableTooltip="true" — 悬停卡片时显示工具提示
• tooltipTemplate — 自定义 HTML 工具提示模板
• 所有 Kanban 元素的 CSS 类参考
• 固定标题模式
• width 和 height — 自动、像素、百分比值

持久化、本地化和响应式

📄 阅读： references/persistence-localization-responsive.md

• enablePersistence="true" — 保存状态到 localStorage
• locale 属性 + ej.base.L10n.load() 脚本
• Kanban 字符串的所有区域设置键名
• enableRtl="true" — 从右向左布局
• 移动端响应行为（滑动、轻触并按住、泳道菜单）

虚拟滚动和无障碍功能

📄 阅读： references/virtual-scrolling-accessibility.md

• enableVirtualization="true" — 按需渲染卡片
• cardHeight — 虚拟化需要固定高度
• 服务器端 KanbanVirtualization 参数处理
• WCAG 2.2 AA 合规性表格
• WAI-ARIA 属性（aria-label、aria-expanded、aria-selected 等）
• 键盘快捷键参考
• AllowKeyboard="false" — 禁用键盘交互

事件

📄 阅读： references/events.md

• ActionBegin / ActionComplete / ActionFailure — 生命周期和错误处理
• CardClick / CardDoubleClick / CardRendered — 卡片交互钩子
• ColumnDrag / ColumnDragStart / ColumnDrop — 列重新排序事件
• Created / DataBinding / DataBound / DataSourceChanged — 初始化和数据事件
• DialogOpen / DialogClose — 拦截或取消对话框（使用 args.cancel = true）
• Drag / DragStart / DragStop — 卡片拖动生命周期（跨 Kanban 场景使用 DragStop）
• QueryCellInfo — 在渲染前自定义列单元格元素

方法

📄 阅读： references/methods.md

• AddCard / UpdateCard / DeleteCard — 卡片的 CRUD 操作
• AddColumn / DeleteColumn — 动态管理列
• OpenDialog / CloseDialog — 以编程方式控制对话框
• ShowColumn / HideColumn — 切换列的可见性
• GetCardDetails / GetColumnData / GetSelectedCards / GetSwimlaneData — 检索数据
• ShowSpinner / HideSpinner — 控制加载指示器
• Refresh / RefreshHeader / RefreshUI — 看板重新渲染辅助方法
• DataBind / Destroy / AppendTo / Inject — 组件生命周期实用方法

所有属性参考

📄 阅读： references/properties.md

• <ejs-kanban> 根属性的完整列表，包含类型、默认值和示例
• 子模型属性：CardSettings、Columns、SwimlaneSettings、SortSettings、DialogSettings、StackedHeaders
• 枚举值：ConstraintType、SelectionType、SortOrderBy、SortDirection

操作指南

📄 阅读： references/how-to.md

• 在运行时动态更改列
• 使用下拉菜单通过 query 属性筛选卡片
• 根据字段值使用文本输入搜索卡片
• 添加标题双击事件处理程序

常见模式

使用远程数据的泳道看板

适用场景： 需要按用户或团队对卡片分组，并从 API 端点（OData、WebAPI 等）加载数据，而不是从本地集合加载数据。

<ejs-kanban id="Kanban" keyField="Status">
    <e-data-manager url="/api/tasks" adaptor="ODataV4Adaptor"></e-data-manager>
    <e-kanban-columns>
        <e-kanban-column headerText="To Do" keyField="Open"></e-kanban-column>
        <e-kanban-column headerText="In Progress" keyField="InProgress"></e-kanban-column>
        <e-kanban-column headerText="Done" keyField="Close"></e-kanban-column>
    </e-kanban-columns>
    <e-kanban-cardsettings headerField="Title" contentField="Summary"></e-kanban-cardsettings>
    <e-kanban-swimlanesettings keyField="Assignee" textField="Assignee"></e-kanban-swimlanesettings>
</ejs-kanban>

带列约束的看板

适用场景： 需要执行 WIP（进行中）限制，防止某列中堆叠的卡片过少或过多。

<ejs-kanban id="Kanban" keyField="Status" dataSource="@ViewBag.data">
    <e-kanban-columns>
        <e-kanban-column headerText="To Do" keyField="Open"></e-kanban-column>
        <e-kanban-column headerText="In Progress" keyField="InProgress"
            minCount="3" maxCount="5" showItemCount="true"></e-kanban-column>
        <e-kanban-column headerText="Done" keyField="Close"></e-kanban-column>
    </e-kanban-columns>
    <e-kanban-cardsettings headerField="Title" contentField="Summary"></e-kanban-cardsettings>
</ejs-kanban>

带卡片编辑对话框和 CRUD 操作的看板

适用场景： 用户需要通过对话框表单创建、编辑或删除卡片，并通过 UrlAdaptor 将更改保存到服务器。

<ejs-kanban id="Kanban" keyField="Status">
    <e-data-manager url="/Home/UpdateData" adaptor="UrlAdaptor"
        crudUrl="/Home/UpdateData"></e-data-manager>
    <e-kanban-columns>
        <e-kanban-column headerText="To Do" keyField="Open"></e-kanban-column>
        <e-kanban-column headerText="Done" keyField="Close"></e-kanban-column>
    </e-kanban-columns>
    <e-kanban-cardsettings headerField="Title" contentField="Summary"></e-kanban-cardsettings>
    <e-kanban-dialogsettings fields="@ViewBag.dialogFields"></e-kanban-dialogsettings>
</ejs-kanban>

虚拟滚动看板

适用场景： 数据集较大（数百到数千张卡片），一次性渲染所有卡片会导致性能问题。

<ejs-kanban id="Kanban" keyField="Status" dataSource="@ViewBag.data"
    enableVirtualization="true">
    <e-kanban-columns>
        <e-kanban-column headerText="To Do" keyField="Open"></e-kanban-column>
        <e-kanban-column headerText="In Progress" keyField="InProgress"></e-kanban-column>
        <e-kanban-column headerText="Done" keyField="Close"></e-kanban-column>
    </e-kanban-columns>
    <e-kanban-cardsettings headerField="Title" contentField="Summary"
        selectionType="Multiple"></e-kanban-cardsettings>
</ejs-kanban>

关键属性参考

属性	标签	值	用途
keyField	<ejs-kanban>	字段名称字符串	按状态值将卡片映射到列
dataSource	<ejs-kanban>	@ViewBag.data	本地数据集合
enableVirtualization	<ejs-kanban>	true/false	针对大型数据的虚拟滚动
enableTooltip	<ejs-kanban>	true/false	卡片悬停提示
tooltipTemplate	<ejs-kanban>	模板 ID 字符串	自定义提示 HTML 模板
allowDragAndDrop	<ejs-kanban>	true/false	全局拖放开关
externalDropId	<ejs-kanban>	元素 ID 数组	外部放置的目标 ID
enablePersistence	<ejs-kanban>	true/false	将状态保存到 localStorage
locale	<ejs-kanban>	区域设置字符串（例如 "de"）	界面字符串本地化
enableRtl	<ejs-kanban>	true/false	从右向左布局
width	<ejs-kanban>	auto/px/%	看板宽度
height	<ejs-kanban>	auto/px/%	看板高度
AllowKeyboard	<ejs-kanban>	true/false	键盘导航开关
headerField	<e-kanban-cardsettings>	字段名称字符串	卡片唯一 ID 字段（必填）
contentField	<e-kanban-cardsettings>	字段名称字符串	卡片正文文本字段
template	<e-kanban-cardsettings>	模板 ID 字符串	自定义卡片 HTML 模板
selectionType	<e-kanban-cardsettings>	None/Single/Multiple	卡片选择模式
priority	<e-kanban-cardsettings>	字段名称字符串	用于排序的数值排名字段
showHeader	<e-kanban-cardsettings>	true/false	显示/隐藏卡片标题
keyField	<e-kanban-column>	状态值	列卡片筛选条件（单个或逗号分隔）
headerText	<e-kanban-column>	显示文本	列标题
allowToggle	<e-kanban-column>	true/false	可折叠列
isExpanded	<e-kanban-column>	true/false	初始展开状态
minCount	<e-kanban-column>	整数	卡片数量下限
maxCount	<e-kanban-column>	整数	卡片数量上限
showItemCount	<e-kanban-column>	true/false	显示卡片数量徽标
allowDrag	<e-kanban-column>	true/false	允许从列中拖动卡片
allowDrop	<e-kanban-column>	true/false	允许将卡片放入列中
keyField	<e-kanban-swimlanesettings>	字段名称字符串	泳道分组字段
textField	<e-kanban-swimlanesettings>	字段名称字符串	泳道显示标签字段
sortBy	<e-kanban-sortsettings>	Index/DataSourceOrder/Custom	卡片排序策略
field	<e-kanban-sortsettings>	字段名称字符串	排序依据字段
direction	<e-kanban-sortsettings>	Ascending/Descending	排序方向

数据模型

所有示例使用的标准 KanbanDataModels 类：

public class KanbanDataModels
{
    public string Id { get; set; }
    public string Title { get; set; }
    public string Status { get; set; }      // Maps to keyField
    public string Summary { get; set; }     // Card body content
    public string Type { get; set; }
    public string Priority { get; set; }
    public string Tags { get; set; }
    public double Estimate { get; set; }
    public string Assignee { get; set; }    // Used for swimlane grouping
    public int RankId { get; set; }         // Numeric rank for priority ordering
    public string Color { get; set; }       // Optional card color field
}