syncfusion-blazor-gantt-chart

实现 Syncfusion Blazor 甘特图

何时使用此技能

当用户需要执行以下操作时，请使用此技能：

• 实现项目排期界面，类似 Microsoft Project，具有可视化时间线和任务管理功能
• 显示分层任务结构，包含父子关系、依赖关系和进度跟踪
• 启用交互式时间线编辑，支持通过拖放任务条、调整大小和链接依赖关系进行编辑
• 管理项目资源，包括人员分配、工作量跟踪和超额分配检测
• 配置复杂时间线，包括自定义缩放级别、工作时间、节假日、时区和工期单位
• 将项目数据导出为 Excel、CSV 或 PDF 格式，并自定义布局和样式
• 处理远程数据，通过 Entity Framework、Dapper、自定义适配器或 REST API 连接进行操作
• 实现关键路径分析，以识别会影响项目完成日期的任务
• 创建资源视图，显示团队成员和设备的任务分配与利用率

此技能全面介绍 SfGantt<TValue> 组件，涵盖从基本设置到拆分任务、基线跟踪和自定义 PDF 导出等高级功能的所有方面。

---

文档与导航指南

此技能分为 14 个主要部分。每个部分都包含针对特定功能的参考文件。请使用此导航指南，根据用户需求确定要阅读的参考资料。

---

1. 入门

阅读时机： 初始设置、安装、平台专属配置

📄 阅读： references/getting-started-webassembly.md

• 为 Blazor WebAssembly 安装 NuGet 包
• 基本组件设置和注册
• CSS 主题导入和配置
• 首个精简甘特图示例
• 任务数据模型和字段映射

📄 阅读： references/getting-started-server.md

• Blazor Server 专属设置和服务
• 在 Program.cs 中注册服务
• 组件初始化方面的差异

---

2. 数据绑定与远程数据

阅读时机： 设置数据源、连接数据库、自定义数据适配器

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

• 分层和自引用数据结构
• GanttTaskFields 配置和映射
• 必需字段与可选字段
• SfDataManager 集成
• 大型数据集的按需加载

📄 阅读： references/remote-data-adaptors.md

• 用于 REST API 的 UrlAdaptor
• 自定义 DataAdaptor 实现
• 处理 CRUD、搜索、筛选和排序操作
• 注入服务和传递参数

---

3. 任务管理

阅读时机： 创建、编辑、删除任务，管理依赖关系和计划，以及撤销/重做和关键路径

📄 阅读： references/task-scheduling-and-hierarchy.md

• 嵌套层级数据结构与自引用（ParentID）数据结构
• 任务类型：父任务（汇总）、子任务（工作项）、里程碑（持续时间为零）、未排期任务
• 自动排期和手动排期方式
• 持续时间单位：Day、Hour、Minute
• 层级影响：父任务汇总、展开/折叠、缩进/取消缩进

📄 阅读： references/task-crud-operations.md

• 启用编辑 — GanttEditSettings（AllowAdding、AllowEditing、AllowDeleting、AllowTaskbarEditing）
• 编辑模式 — Auto、Dialog、Taskbar
• 通过工具栏、上下文菜单或编程 API 添加任务
• 自定义对话框 — 在编辑表单中仅显示所选字段
• 远程 CRUD — InsertUrl、UpdateUrl、RemoveUrl、BatchUrl
• 删除行为 — 级联规则和子任务处理方式

📄 阅读： references/task-dependencies-and-validation.md

• 依赖类型：FS、SS、FF、SF
• 通过 GanttTaskFields.Dependency 映射前置任务字段
• 依赖字符串格式（例如，3FS、5SS+2d）
• 检测循环依赖
• 自动排期与依赖关系变更的交互

📄 阅读： references/critical-path-and-analysis.md

• EnableCriticalPath — 自动以红色突出显示关键任务
• GanttCriticalPathSettings.SlackValue — 扩大关键区域，将近关键任务纳入其中
• “CriticalPath”工具栏项 — 面向用户的切换开关
• QueryChartRowInfo + GanttTaskModel.IsCritical — 自定义关键任务栏颜色/样式
• GetCriticalTasksAsync() — 以编程方式获取关键任务列表
• 计算规则：进度 < 100%，由依赖关系驱动，每次变更时重新计算

📄 阅读： references/undo-redo-and-state.md

• EnableUndoRedo + UndoRedoActions 列表 — 跟踪 23 种操作类型（Add、Edit、Delete、TaskbarEdit、Sort、Filter、ZoomIn/Out、Indent/Outdent、RowDragAndDrop 等）
• MaxUndoRedoSteps — 限制历史记录大小（默认值：20）
• UndoAsync() / RedoAsync() — 以编程方式撤销/重做
• “Undo” / “Redo”工具栏项 — 键盘快捷键 Ctrl+Z / Ctrl+Y
• OnUndoRedo 事件 — 撤销/重做后通过 CanUndo/CanRedo 状态作出响应
• 状态保留模式 — 展开/折叠、选择、缩放、筛选器、滚动位置

---

4. 时间线配置

何时阅读： 时间线视图、缩放级别、工作时间、节假日、时区、工作量跟踪

📄 阅读： references/timeline-configuration.md

• 单层与双层时间线布局
• GanttTimelineSettings、GanttTopTierSettings、GanttBottomTierSettings
• TimelineViewMode 单位：Hour、Day、Week、Month、Year
• TimelineUnitSize — 控制单元格宽度／密度
• 层级标签的格式字符串
• 用于设置可见日期范围的 ProjectStartDate / ProjectEndDate

📄 阅读： references/zooming-and-view-control.md

• ZoomIn、ZoomOut、ZoomToFit 工具栏项
• ZoomToFit — 将整个日程安排适配到可见视口
• 通过工具栏或代码以编程方式缩放
• 建议的默认设置：运营视图使用日／周，路线图视图使用周／月

📄 阅读： references/working-time-holidays-timezone.md

• DayWorkingTime — 定义每天的工作时间（例如，8 小时工作日）
• WorkWeek — 指定哪些日子是工作日
• GanttHolidays / GanttHoliday — 使用 From/To/Label 设置非工作日期
• 多地区团队的时区注意事项
• 对任务工期计算和自动排程的影响

📄 阅读： references/work-and-effort-tracking.md

• GanttTaskFields.Work 中的 Work 字段映射
• 任务类型：FixedDuration、FixedWork、FixedUnit
• Work = Duration × WorkingHoursPerDay × (Unit / 100)
• 资源分配单位会影响工作量计算
• WorkUnit 属性（Hour、Day、Minute）

---

5. 资源

何时阅读： 资源分配、资源视图、超额分配检测、分配项的 CRUD 操作

📄 阅读： references/resources-and-allocation.md

• GanttResource — DataSource、Id、Name、MaxUnits、Group 字段映射
• GanttAssignmentFields — PrimaryKey、TaskID、ResourceID、Units
• ResourceData 模型（ResourceId、ResourceName、MaxUnit）+ AssignmentModel（PrimaryId、TaskID、ResourceId、Unit）
• 通过单元格编辑（GanttResourceColumn）、对话框或编程方式分配资源
• AddResourceAssignmentAsync / UpdateResourceAssignmentAsync / DeleteResourceAssignmentAsync
• 带资源的任务类型：FixedDuration、FixedWork、FixedUnit
• ViewType.ResourceView — 以资源为中心的层级结构（资源为父项，任务为子项）
• ShowOverallocation="true" — 在资源视图中突出显示超额分配的日期范围
• 超额分配 = 所有任务的每日工作量 > DayWorkingHours × MaxUnits / 100
• GanttLabelSettings.RightLabel="Resources" — 在任务条标签中显示资源名称

📄 阅读： references/assignment-fields-and-resource-mapping.md

• GanttAssignmentFields<TValue, TAssignment> 类及其属性
• 资源分配集合和外键关系
• AddResourceAssignmentAsync、UpdateResourceAssignmentAsync、DeleteResourceAssignmentAsync
• 多对多任务与资源映射模式
• 资源分配单位和百分比跟踪

---

6. 任务分段与拆分

何时阅读： 拆分任务、任务分段、中断的日程安排、暂停的工作

📄 阅读： references/segment-fields-and-split-tasks.md

• GanttSegmentFields<TValue, TSegments> — PrimaryKey、TaskID、StartDate、EndDate 字段映射
• 分段数据模型：独立集合，通过 TaskID 与任务关联
• SplitTaskAsync — 以编程方式在指定日期拆分任务
• MergeTaskAsync — 将分段合并回单个任务
• 通过上下文菜单或对话框进行 UI 拆分
• 分段任务条渲染 — 多个带间隔的连接条
• 使用场景：计划内休息、资源不可用、审批暂停

---

7. 可视化

阅读时机： 任务条模板、基线、标记、标签、交互式任务条编辑

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

• GanttTemplates.TaskbarTemplate — 用于任务条内容的自定义 RenderFragment
• GanttTooltipSettings.TaskbarTemplate — 自定义工具提示内容
• ShowBaseline / BaselineColor / BaselineStart / BaselineEnd — 比较计划与实际情况
• TaskbarHeight / RowHeight — 尺寸控制
• 性能提示：将复杂模板与 EnableVirtualization 配合使用

📄 阅读： references/markers-and-labels.md

• GanttEventMarkers / GanttEventMarker — 带有 Date、Text、CssClass 的垂直时间线
• GanttLabelSettings — LeftLabel、RightLabel、TopLabel，使用字段名或模板
• 通过 TaskbarTemplate 添加数据标记 — 根据任务属性显示条件图标
• 将标记限制在关键日期，避免时间线过于杂乱

📄 阅读： references/taskbar-editing.md

• 在 GanttEditSettings 中设置 AllowTaskbarEditing="true"
• 拖动以移动任务 — 更新 StartDate 和 EndDate
• 调整左侧/右侧手柄大小 — 调整开始日期或结束日期
• 拖动进度手柄 — 更新 Progress 字段
• TaskbarEdited 事件 — 接收 TaskbarEditedEventArgs<TValue>
• OnActionBegin — 通过 args.Cancel 验证或取消任务条编辑

---

8. 网格列

阅读时机： 列配置、类型、格式化、显示/隐藏、自适应、验证、重新排序、调整大小、冻结列、列菜单

📄 阅读： references/column-basics-and-formatting.md

• GanttColumn 定义（Field、HeaderText、Width、TextAlign、Format、Type、Visible）
• 列类型包括 DateOnly、TimeOnly、Checkbox
• 数字格式（N、C、P 变体）和日期格式（自定义模式字符串）
• 列自适应 — 在 DataBound 事件中调用 AutoFitColumnsAsync
• 以编程方式显示或隐藏列 — ShowColumnsAsync / HideColumnsAsync
• TreeColumnIndex — 将展开/折叠树形图标移动到其他列
• HideAtMedia — 通过 CSS 媒体查询实现响应式列
• 按列设置操作控件：AllowEditing、AllowFiltering、AllowSorting、AllowReordering、AllowResizing

📄 阅读： references/column-interactions.md

• 列重新排序 — 在 SfGantt 上设置 AllowReordering，并可按列覆盖
• 调整列大小 — AllowResizing、MinWidth、MaxWidth；双击以自适应列宽
• 冻结列 — FrozenColumns（前 N 列）与按列设置 IsFrozen（不可组合使用）
• 冻结方向 — 将 FreezeDirection.Left / FreezeDirection.Right 与 IsFrozen 配合使用
• 可拖动的冻结线 — AllowFreezeLineMoving
• 列菜单 — 在 SfGantt 上设置 ShowColumnMenu，并搭配必需选项（AllowSorting、AllowFiltering、AllowResizing）
• 内置列菜单项：升序排序、降序排序、自适应列宽、自适应所有列宽、列选择器、筛选
• 按列禁用列菜单 — GanttColumn.ShowColumnMenu="false"
• 列选择器 — ShowColumnChooser + "ColumnChooser" 工具栏项

📄 阅读： references/column-validation-and-editing.md

• 启用编辑 — GanttEditSettings，在键列上设置 IsPrimaryKey
• 内联 ValidationRules — Required、RangeLength、Range、Number、Min、Max、Messages 字典
• 数据注解验证 — 在模型类上使用 [Required]、[StringLength]、[Range]
• 自定义验证属性 — 继承 ValidationAttribute，并重写 IsValid()
• 自定义验证器组件 — GanttEditSettings.Validator + ValidatorTemplateContext + ShowValidationMessage + IDisposable
• 按列设置 EditType — DefaultEdit、NumericEdit、DatePickerEdit、DateTimePickerEdit、BooleanEdit、DropDownEdit
• 注意：资源列不支持验证

9. 行与选择

阅读时机： 行操作、单元格/行选择模式

📄 阅读： references/rows-and-height.md

• RowHeight 配置
• AutoFitRows 功能
• 行模板自定义
• 行级样式

📄 阅读： references/selection-modes.md

• SelectionSettings（Mode、Type、CellSelectionMode）
• 行选择（单选/多选）
• 单元格选择（Box/Flow/BoxWithBorder）
• 以编程方式选择的 API（SelectRow、SelectCell）

---

10. 交互

阅读时机： 用户交互、筛选、排序、搜索

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

• FilterSettings（Type：Menu、Excel）
• FilterHierarchyMode（Parent、Child、Both、None）
• 搜索功能（SearchSettings）
• 列级筛选

📄 阅读： references/sorting-operations.md

• AllowSorting 配置
• 单列和多列排序
• SortSettings（Columns 集合）
• 以编程方式排序的 API

📄 阅读： references/context-menu-and-toolbar.md

• 工具栏内置项（18 项）和支持 Align 的自定义项
• 使用 List<Object> 混合内置项与自定义工具栏项
• 通过 EnableItems 方法动态启用/禁用工具栏项
• 上下文菜单 — EnableContextMenu、内置项、自定义项、子菜单
• 通过 ContextMenuOpen 事件禁用特定列的上下文菜单
• 用于处理自定义项的 ContextMenuItemClicked 事件

📄 阅读： references/touch-and-interaction-modes.md

• 支持触控交互
• EnableTouch 属性
• 用于调整网格/图表窗格大小的分隔条
• SplitterSettings 配置

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

• 复制/粘贴功能
• 剪贴板模块集成
• 键盘导航
• 无障碍功能

---

11. 性能

阅读时机： 优化策略、大型数据集

📄 阅读： references/virtualization-and-performance.md

• 为大型数据集启用 EnableRowVirtualization
• 行和列虚拟化
• 冻结列（FrozenColumns 属性）
• WebAssembly 性能优化技巧
• 处理 10,000+ 个任务的最佳实践

---

12. 导出

阅读时机： PDF 和 Excel 导出功能

📄 阅读： references/pdf-export.md

• PdfExport() 方法
• PdfExportProperties 配置
• 多页 PDF 导出
• 页眉和页脚自定义
• PDF 中的页面大小和样式
• 基于模板的 PDF 导出

📄 阅读： references/excel-export.md

• ExcelExport() 方法
• ExcelExportProperties 配置
• Excel 中的列格式设置
• 层级数据导出
• 自定义单元格样式

---

13. API 参考

适合阅读的场景： 查阅详细的 API 文档

📄 阅读： references/gantt-methods-properties.md

• SfGantt 主组件
• GanttTaskFields 映射
• GanttColumn 配置
• GanttResource 属性
• 用于拆分任务的 GanttSegment

📄 阅读： references/api-settings-classes.md

• GanttEditSettings（AllowAdding、AllowEditing、AllowDeleting、Mode）
• GanttSelectionSettings（Mode、Type、CellSelectionMode）
• GanttFilterSettings（Type、HierarchyMode）
• GanttSortSettings 和 GanttSearchSettings
• GanttTimelineSettings 和 GanttSplitterSettings

📄 阅读： references/api-event-args.md

• GanttActionEventArgs
• BeforeTooltipRenderEventArgs
• BeforeCopyEventArgs
• 其他事件参数类

📄 阅读： references/api-enums-and-types.md

• EditMode（Auto、Dialog、Taskbar）
• DependencyType（FS、SF、FF、SS）
• DurationUnit（Day、Hour、Minute）
• FilterType、ViewType、GridLine 枚举
• 其他枚举类型

---

快速入门示例

@page "/gantt"
@using Syncfusion.Blazor.Gantt

<SfGantt DataSource="@TaskCollection" Height="450px" Width="100%">
    <GanttTaskFields Id="TaskId" 
                     Name="TaskName" 
                     StartDate="StartDate" 
                     EndDate="EndDate"
                     Duration="Duration" 
                     Progress="Progress" 
                     ParentID="ParentId"
                     Dependency="Predecessor">
    </GanttTaskFields>
</SfGantt>

@code {
    private List<TaskData> TaskCollection { get; set; }

    protected override void OnInitialized()
    {
        TaskCollection = new List<TaskData>
        {
            new TaskData { TaskId = 1, TaskName = "Project Initiation", StartDate = new DateTime(2024, 04, 01), EndDate = new DateTime(2024, 04, 05), Progress = 100 },
            new TaskData { TaskId = 2, TaskName = "Identify Site location", StartDate = new DateTime(2024, 04, 01), Duration = 4, Progress = 50, ParentId = 1 },
            new TaskData { TaskId = 3, TaskName = "Perform Soil test", StartDate = new DateTime(2024, 04, 01), Duration = 3, Progress = 70, Predecessor = "2", ParentId = 1 },
        };
    }

    public class TaskData
    {
        public int TaskId { get; set; }
        public string TaskName { get; set; }
        public DateTime StartDate { get; set; }
        public DateTime? EndDate { get; set; }
        public int? Duration { get; set; }
        public int Progress { get; set; }
        public int? ParentId { get; set; }
        public string Predecessor { get; set; }
    }
}

---

常见模式

模式 1：使用对话框编辑实现完整的 CRUD

<SfGantt DataSource="@TaskCollection" Toolbar="@ToolbarItems">
    <GanttTaskFields Id="TaskId" Name="TaskName" StartDate="StartDate" 
                     EndDate="EndDate" Duration="Duration" Progress="Progress" 
                     ParentID="ParentId" Dependency="Predecessor">
    </GanttTaskFields>
    <GanttEditSettings AllowAdding="true" 
                       AllowEditing="true" 
                       AllowDeleting="true"
                       AllowTaskbarEditing="true"
                       Mode="EditMode.Dialog">
    </GanttEditSettings>
</SfGantt>

@code {
    private List<string> ToolbarItems = new List<string> { "Add", "Edit", "Delete" };
}

模式 2：结合资源分配的关键路径

<SfGantt DataSource="@TaskCollection" 
         Resources="@ResourceCollection"
         EnableCriticalPath="true">
    <GanttTaskFields Id="TaskId" Name="TaskName" StartDate="StartDate" 
                     EndDate="EndDate" Duration="Duration" 
                     ResourceInfo="Resources" Work="Work">
    </GanttTaskFields>
    <GanttResource DataSource="@ResourceCollection" 
                   Id="ResourceId" 
                   Name="ResourceName">
    </GanttResource>
    <GanttCriticalPathSettings SlackValue="1"></GanttCriticalPathSettings>
</SfGantt>

模式 3：使用 Entity Framework 的远程数据

<SfGantt TValue="TaskData">
    <SfDataManager Adaptor="Adaptors.UrlAdaptor" Url="api/gantt"></SfDataManager>
    <GanttTaskFields Id="TaskId" Name="TaskName" StartDate="StartDate" 
                     EndDate="EndDate" Duration="Duration" ParentID="ParentId">
    </GanttTaskFields>
</SfGantt>

模式 4：使用自定义样式导出

<SfGantt @ref="GanttRef" 
         DataSource="@TaskCollection" 
         AllowPdfExport="true" 
         AllowExcelExport="true"
         Toolbar="@ToolbarItems">
    <GanttTaskFields Id="TaskId" Name="TaskName" StartDate="StartDate" EndDate="EndDate">
    </GanttTaskFields>
    <GanttEvents TValue="TaskData" OnToolbarClick="ToolbarClickHandler"></GanttEvents>
</SfGantt>

@code {
    private SfGantt<TaskData> GanttRef;
    private List<string> ToolbarItems = new List<string> { "PdfExport", "ExcelExport" };

    private async Task ToolbarClickHandler(ClickEventArgs args)
    {
        if (args.Item.Id == "PdfExport")
            await GanttRef.ExportToPdfAsync();
        else if (args.Item.Id == "ExcelExport")
            await GanttRef.ExportToExcelAsync();
    }
}

---

关键配置要点

必要属性

• DataSource：任务集合（分层或自引用）
• GanttTaskFields：映射任务属性（Id、Name、StartDate、Duration、ParentID、Dependency）
• Height/Width：组件尺寸
• Toolbar：内置操作（添加、编辑、删除、搜索、导出）
• GanttEditSettings：CRUD 权限和编辑模式

时间线配置

• DurationUnit：默认时长单位（Day、Hour、Minute）
• ProjectStartDate/ProjectEndDate：时间线边界
• GanttTimelineSettings：时间线级别、格式、缩放级别
• DayWorkingTime：每天的工作时间
• Holidays：非工作日期

视觉自定义

• GanttTaskbarSettings：任务栏高度和样式
• GanttLabelSettings：左侧、右侧和顶部标签
• GanttTemplates：自定义任务栏、工具提示和里程碑模板
• BaselineColor/ConnectorLineBackground：视觉样式

性能优化

• EnableRowVirtualization：用于大型数据集（1000+ 个任务）
• EnableColumnVirtualization：用于列数较多的情况
• LoadChildOnDemand：按需延迟加载子任务
• TreeColumnIndex：指定层级列

---

常见用例

1. 项目管理仪表板：完整的 CRUD、依赖关系、关键路径、资源分配
2. 施工进度安排：基线跟踪、拆分任务、节假日、自定义工作时间
3. 资源规划：资源视图、超额分配检测、基于工作量的排期
4. 冲刺规划：时间线缩放、里程碑跟踪、进度指示器
5. 制造业时间线：多级层级结构、依赖关系验证、PDF 导出

---

后续步骤

阅读本导航指南后：

1. 初始设置：根据你的平台，从第 1 节（开始使用）入手
2. 数据连接：根据数据源类型，查看第 2 节（数据绑定）
3. 特定功能：导航到相关章节并阅读对应的参考文件
4. API 详情：查阅第 13 节（API 参考）了解属性、方法和类

事件参考： 事件参数类型记录在 references/api-event-args.md 中。各个功能文件（例如 taskbar-editing.md、filtering-and-search.md、sorting-operations.md、selection-modes.md）均介绍该功能相关的事件，并提供处理程序签名和示例。

每个参考文件都提供对应主题的完整实现详情、代码示例、边缘情况和故障排除指南。