简介面向使用 DevExpress 控件开发 WinForm 程序的工程师这份代码包提供一套完整通用的 Excel 导出方案。方案重点解决 GridControl 原生导出缺失图片、多表头无法完整呈现以及 PivotGridControl 默认分组导致版面错乱等痛点通过统一的封装逻辑做到所见即所得。导出过程支持同时勾选多个控件并可将不同控件输出到同一 Excel 文件的不同工作表适应汇总报表、分页存档等业务场景。压缩包内含一百七十九个文件其中包含程序集运行库、C# 源文件、XML 配置文件、样例图片、可执行演示工程、项目解决方案与授权文件等压缩包整体约三十五兆字节源码与项目目录组织清晰既可直接调用也便于按项目结构调整。已有 1022 人学习下载适合正在处理复杂导出、希望缩短开发周期的 WinForm 开发者使用。1. 别再把每个 Grid 单独写导出先搭一层能认控件的通用导出层做 WinForm 后台系统的时候导出 Excel 大概是报表需求里最不起眼、又最容易被反复复制粘贴的一段。GridControl 来一个窗体就把 gridView.ExportToXlsx() 抄一遍TreeList 接着来发现参数不一样又套一层等 PivotGrid 出现导出逻辑已经散落在七八个窗体里想统一加个页眉或换掉一处样式得全局搜索替换。这里想拆的是一套 DevExpress WinForm 通用控件导出方法核心就一件事把 GridView、TreeList、PivotGrid、Chart 这些互不相干的控件收敛到一个统一入口用托管模型描述“导出什么、导出到哪、按什么格式”并支持多个控件分别导出到不同工作簿文件也可以合并到同一工作簿的不同 Sheet。适合正在做报表模块、后台导出功能并且不想再为每个窗体单独维护导出代码的开发者。2. 通用导出器的模型设计导出源、上下文与单文件/多文件策略2.1 为什么直接调 ExportToXlsx 会在项目里失控先认清一件很现实的事DevExpress 各控件虽然都有导出能力但导出接口从来不是一套。GridView 有 ExportToXlsxTreeList 有 ExportToXlsxPivotGridControl 也有 ExportToXlsx可三个方法的选项类分别是 XlsxExportOptionsEx、TreeListXlsxExportOptions、PivotXlsxExportOptions。如果你只想在按钮事件里写一行 gridView.ExportToXlsx(path)看起来确实很爽可一旦出现下面几种情况这种写法就开始拖后腿。一是要统一给所有导出文件加页眉页脚、固定列宽、统一水印那就得去改每一个调用地方漏一个窗体就是两种风格。二是要控制导出列不把操作按钮列导出去每个窗体都得单独写一遍列过滤逻辑等于把同一件事复制了 N 次。三是要多张表一起输出直接调用只能一次导一个文件后续还得有人手动合并。更重要的是直接调用默认导出时很多细节行为并不符合业务预期。比如 GridView 默认导出会把分组状态、筛选状态一起带进 ExcelDataAware 和默认导出又有区别前者会尽量把单元格类型写成 Excel 原生类型后者更偏向文本。同一个 Grid在不同窗体里因为某个同事改了一个选项导出结果就可能不一致。这些选项如果不在一处收口后面接手的人根本不知道哪里设置了什么只能靠读代码猜。所以我一向建议先做一个“导出上下文”把每次导出可能会变的参数全部提炼出来而不是让业务代码直接去碰控件导出方法。导出上下文里至少要包含三样东西导出目标控件的引用、导出后的文件名或工作表名、以及一系列导出选项。控件引用用 object 接收就行实际分发时再按真实类型去匹配这也是“通用”的第一层含义。2.2 核心模型ExportSource、ExportOptions 与调度上下文先给出我常用的两个模型定义一个是单个导出源一个是整体导出上下文public class ExportSource { public object Control { get; set; } // GridView / TreeList / PivotGrid / ChartControl public string ExportName { get; set; } // 文件名前缀或合并后 Sheet 名 public bool KeepGrouping { get; set; } // 是否保留 Grid 分组 public bool IncludeAutoFilter { get; set; } // 是否加自动筛选 } public class ExportContext { public string OutputDir { get; set; } // 输出目录 public bool OneFilePerControl { get; set; } true; // 分工作簿true一个控件一个文件 public Actionstring LogAction { get; set; } // 日志回调 public Funcint, bool ProgressCallback { get; set; } // 进度回调返回 false 取消 }逻辑说明ExportSource 是描述“这一份导出到底导什么”的最小单元。Control 用 object 而不是具体控件类型就是为了让调用方不用关心底层分发逻辑分发时使用 C# 模式匹配逐个判断类型而不是写满 if-else 的长方法。ExportName 在 OneFilePerControltrue 时充当文件名前缀在合并场景里充当 Sheet 名业务代码只需要传一次。KeepGrouping 和 IncludeAutoFilter 是导出选项里最常见的两个变量其他像列宽、文字格式可以放在默认选项里业务侧极少改动。参数说明ProgressCallback 接收当前完成序号返回 true 继续、false 表示用户取消LogAction 是轻量日志钩子适合在批量导出时把每个文件路径打到状态栏或日志文件里。这里没有把文件路径直接写进 ExportSource是因为文件路径属于输出层职责业务代码不该知道具体目录规划导出器收到 ExportContext 之后统一计算路径既能防止路径散落也方便测试。2.3 先把“分工作簿”策略定下来后面调度才不会乱“多个控件分工作簿导出”这句话不同人理解不一样。有人想要一个控件导出一个 Excel 文件有人想要一个 Excel 文件里多个 Sheet。这个差别必须在设计阶段就定下来否则后面所有代码都会被带偏。我一般把两种策略叫做“独立工作簿”和“合并工作簿”策略输出形态适合场景实现成本独立工作簿一个控件一个 .xlsx报表导出、给不同负责人发不同明细低直接调各控件导出方法合并工作簿一个 .xlsx 多个 Sheet给业务方一次性汇总方便在同一个文件里翻看中需要二次处理文件为什么默认推荐独立工作簿原因在于 xlsx 本质是一个 zip 压缩包合并多个完整 xlsx 不是简单拼接文件而是要重写工作簿索引、内容类型、共享字符串表一步做错文件就损坏。早期我试过手动改 XML翻车概率非常高。所以第一版通用导出器只做“独立工作簿”每个控件各导各的文件最后用文件命名规则把多个文件串起来。合并工作簿作为进阶功能放到调度层做二次处理而不是让底层控件导出方法去感知。这样底层 API 单一、职责干净上层想合并时再单独写一段合并逻辑即可。在这个基础上导出的核心调度就变成非常朴素的一层循环遍历 ExportSource 集合逐个调用统一导出入口收集成功与失败的文件列表返回给调用方。至于每个控件的导出 API 怎么差异那么大就在统一导出入口里用模式匹配挡掉这正是下一章要做的事。3. GridView、TreeList、PivotGrid、Chart 统一出口控件分发与参数取舍3.1 GridView 导出DataAware 导出类型是默认首选GridView 是 WinForm 里最常出现的导出对象也是选项最多的一个。直接调 gridView.ExportToXlsx 当然能工作但有两个地方值得注意一是导出类型二是分组与筛选是否保留。我常用的写法是这样public static void ExportGridView(GridView gridView, ExportSource src, string targetFile) { var options new XlsxExportOptionsEx { ExportType ExportType.DataAware, // 尽量按 Excel 原生类型导出 SheetName src.ExportName, AllowGrouping src.KeepGrouping, // 保留分组时才为 true AllowSummaries false, // 不导出汇总行明细更干净 AutoFilterMode DevExpress.XtraExport.AutoFilterMode.AutoFilter }; using (var fs new FileStream(targetFile, FileMode.Create)) { gridView.ExportToXlsx(fs, options); } }逻辑说明ExportType.DataAware 的含义是让导出器识别每一列的真实数据类型数字列导出为数值单元格日期列导出为日期单元格而不是统一写成文本默认导出更偏向所见即所得很多列会变成文本后续在 Excel 里做透视或求和会遇到麻烦。SheetName 用于指定导出后工作表名如果你要把两个 Grid 合并到同一工作簿这个名字就是后面合并时的定位依据。AllowGrouping 为 true 时导出会保留分组结构在 Excel 里能看到小计和分组层级但这也会让单元格结构更复杂合并时需要额外处理。参数说明这里使用 FileStream 而不是直接传文件名字符串是为了控制文件流生命周期。using 包裹保证写完立刻释放避免文件被占用导致第二次导出失败。AutoFilter 参数按需开启如果业务方只需要静态数据把它去掉也可以节省一些文件体积。还要注意 GridView 的可见列过滤要提前准备好可以把需要排除的列先隐藏或使用 GridView.CustomExportCell 事件按列名跳过单元格内容。后者更可控推荐后一种方式因为隐藏列会影响界面上用户看到的列而 CustomExportCell 只影响导出结果。3.2 TreeList 与 PivotGrid树形和透视的导出参数差别TreeList 的导出核心不在样式而在“到底导出多少层节点”。TreeListExportOptions 里的 ExportMode 就是干这个的我一般用 AllNodes 而不是只导可见节点否则展开状态一变同一份数据导出结果就不一样。var treeOptions new TreeListXlsxExportOptions { ExportMode TreeListExportMode.AllNodes, SheetName src.ExportName }; using (var fs new FileStream(targetFile, FileMode.Create)) { treeList.ExportToXlsx(fs, treeOptions); }逻辑说明AllNodes 会按树的完整层级导出包括当前折叠的节点适合导存档、导全量数据VisibleNodesOnly 只导出当前展开的部分适合做“看到什么就导出什么”的临时导出。父节点层级在 Excel 里体现为相同的行顺序不会像 GridView 分组那样生成 Excel 原生分组所以后续处理起来更简单。PivotGrid 则是另一套思路它的数据形态是透视表导出后是横向列与纵向行的交叉结构列头是动态生成的var pivotOptions new PivotXlsxExportOptions(); using (var fs new FileStream(targetFile, FileMode.Create)) { pivotGridControl.ExportToXlsx(fs, pivotOptions); }参数说明PivotXlsxExportOptions 能调的主要是是否导出未折叠的字段区域默认行为已经比较合理。如果你要导出多个透视表注意每个透视表导出后的列宽是固定的列数由维度数量决定程序里不要写死读取列 A要先获取 UsedRange 再遍历。这里不推荐对 PivotGrid 做单元格级合并因为透视表行列位置会根据数据项数量变化非常容易定位错行。3.3 ChartControl图表先成图再落到 Sheet 里图表导出其实不是一个 Excel 功能ChartControl 的导出接口是 ExportToImage不带 Excel 选项。所以在这个通用入口里我先把它导成图片再用 Spreadsheet 文档 API 插入到工作簿指定 Sheet 上。using (var ms new MemoryStream()) { chartControl.ExportToImage(ms, System.Drawing.Imaging.ImageFormat.Png); ms.Position 0; // 把图片插入到已存在的 Sheet 单元格中 // 不同 DevExpress 版本插入 API 位置不同以下为示意 worksheet.Pictures.Add(ms, 5, 0, 800, 450); }逻辑说明图表图片是导出瞬间的快照Excel 里的图表不会跟随数据源刷新。如果业务方希望图表在 Excel 里仍然动态更新那就不能用这个方案而应该用 Spreadsheet 控件重新创建图表对象成本会高很多。通用导出器选择“快照”方案因为大多数报表需求只要求“看起来一致”并不要求联动。参数说明图片宽度、高度按像素传入插入位置以单元格行列坐标定位。导出前要确认 ChartControl 已经完成绘制如果是在窗口刚刚加载时立刻导出图表可能还是空白最简单的做法是调用一下 chartControl.RefreshData() 再导出。4. 避坑指南导出 Excel 时最容易翻车的 5 个点4.1 工作簿打开就报「文件损坏」现象导出的 xlsx 双击后Excel 弹出文件已损坏、需要修复的提示点修复可能恢复也可能直接打不开。原因最常见的是扩展名与真实格式不匹配比如用 ExportToXls 导出内容却把文件名写成 .xlsx另一个常见原因是导出时 Stream 没有关闭文件内容没有完整写入磁盘。解决统一走 FileStream using 的写法文件名后缀固定为 .xlsx并且保证调用 ExportToXlsx 而不是 ExportToXls。如果是从内存流导完再写文件先 flush 内存流再写或直接使用文件流一步到位。4.2 长数字变科学计数法后几位全变 0现象身份证号、订单号这类超过 15 位的数字列导出后显示成 1.23E17双击单元格看到的数字最后三四位变成了 0。原因GridView 列被绑定成了数值类型DataAware 导出后写入 Excel 的确实是数值单元格但 Excel 对超过 15 位的数字会截断精度这不是 DevExpress 的问题。解决在导出前把这类列强制转成字符串。常见做法是把列对应的 ColumnEdit 设为 TextEdit或者在数据源查询里把 ID 转成字符串再绑定也可以在 GridView.CustomExportCell 事件里对指定列把 e.Value 改成 e.Value.ToString()。三种方法我都试过自定义导出事件不影响界面显示、只影响导出结果是最干净的一种。4.3 大数据量导出时内存与性能双双失控现象一次性导出 30 万行数据程序内存涨到 1GB 以上界面假死导出过程可能长达几分钟。原因默认导出会把整个工作簿结构放到内存里行数越大内存开销越线性上升再加上导出时 UI 线程被占用连取消按钮都点不了。解决分两条路。一是启用导出器的流式能力尽量把 FileStream 作为导出目标而不是 MemoryStream二是把导出任务放到后台线程配合进度回调。如果超过几十万行建议在调度层按主键分页一个 Sheet 导一部分最后合并这样单次内存峰值可控得多。实际经验是 5 万行以内直接导出很稳10 万行以上就要开始做分页。4.4 多控件导出时文件互相覆盖现象一次注册两个 Grid 导出运行完只看到一个文件而且内容还是第二个 Grid 的第一个文件像没导出过一样。原因调度器里没有保证文件路径唯一两个控件共用了导出文件名或循环里连续使用了同一个 FileStream 变量。解决文件路径一定由调度器生成用“导出名 时间戳 序号”拼出来避免业务侧传文件名。序号取 ExportSource 在集合里的索引时间戳精确到秒基本不会再冲突。如果合并导出到同一个工作簿则在合并前把每个控件的导出文件放到临时目录合并完成后统一清理。4.5 日期列变成一串数字序列号现象日期列导出后显示 44231 这种数字设置单元格格式也恢复不了日期样式。原因DataAware 导出把日期值写成了 Excel 序列号而单元格没有带日期格式Excel 默认按常规格式显示。解决导出前在 GridView 列上设置 DisplayFormat如 gridView.Columns[CreateTime].DisplayFormat.FormatString yyyy-MM-dd HH:mm:ss。这个设置既影响界面显示也会带入导出。如果已经导出完了可以在验证环节用文档 API 扫描日期列批量设置 NumberFormat这个放到最后一章说。5. 多控件分工作簿导出调度一个方法批量输出多个文件5.1 最稳的默认方案一个控件对应一个工作簿文件在真实项目里我会把第 3 章的控件分发封装成一个总入口 ExportControl再把“多个控件”的调度逻辑封在 ExportAll 里。业务侧注册好 ExportSource 列表交给调度器就行public static class WorkbookExportScheduler { public static Liststring ExportAll( ListExportSource sources, ExportContext context) { var result new Liststring(); for (int i 0; i sources.Count; i) { if (context.ProgressCallback ! null !context.ProgressCallback(i)) break; var source sources[i]; var filePath Path.Combine(context.OutputDir, ${source.ExportName}_{DateTime.Now:yyyyMMddHHmmss}_{i 1}.xlsx); try { ControlExcelExporter.ExportControl(source.Control, filePath, source); result.Add(filePath); context.LogAction?.Invoke($已导出: {filePath}); } catch (Exception ex) { context.LogAction?.Invoke($导出失败: {source.ExportName} - {ex.Message}); } } return result; } }逻辑说明这里把“分工作簿”直接落成“一个控件导出一个 xlsx”文件名里带上导出名、时间戳和序号既能让用户看懂文件来源也避免互相覆盖。进度回调在每次导出前触发一次序号 i 从 0 开始业务侧可以把进度与列表 Count 相除得到百分比。单个控件导出失败不影响整体异常被捕获后记录日志最终返回成功文件列表业务侧可以决定是继续还是提示用户。参数说明OneFilePerControl 在 ExportContext 里保留了开关字段但当前版本只实现 true 的分支是为了让调用方明确“现在是分文件模式”。一旦后面要支持合并调度器只需要在 filePath 生成逻辑上换个分支把 list 传给 MergeToOneWorkbook 即可业务侧不需要大改。5.2 进阶合并用文档 API 把多个 Sheet 并进一个工作簿如果业务方坚持要“一个 Excel 文件看到所有控件”就在调度器最后加一步合并。常见的做法是先用 5.1 的方法导出多个临时 xlsx再逐个读入把第一个工作表的内容复制到一个目标工作簿里。之所以单独拿出一节来写是因为这里有很多版本差异和玄学问题。public static void MergeToOneWorkbook(Liststring xlsxFiles, string outputFile) { using (Workbook target new Workbook()) using (Workbook temp new Workbook()) { foreach (string file in xlsxFiles) { temp.LoadDocument(file); if (temp.Worksheets.Count 0) continue; Worksheet src temp.Worksheets[0]; Worksheet dst target.Worksheets.Add(src.Name); // 单元格级复制保留值和格式不同版本暴露的 API 位置不一样 // 有的是 Cell.CopyFrom有的是 Range.CopyTo以当前 DevExpress 版本为准 var range src.GetUsedRange(); for (int r 0; r range.RowCount; r) { for (int c 0; c range.ColumnCount; c) { var srcCell range[r, c]; var dstCell dst.Cells[r, c]; dstCell.SetValue(srcCell.Value); dstCell.NumberFormat srcCell.NumberFormat; } } } target.SaveDocument(outputFile); } }逻辑说明这样合并出来的工作簿Sheet 名默认用控件导出名Sheet 内容是最初导出的快照。单元格级复制不会保留列宽、合并单元格、图片这些复杂元素所以如果你的控件里包含 Chart 或合并表头建议保留独立工作簿输出不要强行合并。写入临时文件而不是内存流是为了减少内存占用多文件合并时尤其明显。参数说明row/col 双重循环在大数据量下会比较慢10 万单元格以内可以接受超过这个量级建议用 Range 拷贝而不是遍历单元格。合并后记得调用 workbook.SaveDocument如果目标文件已存在先备份或确认覆盖策略。5.3 调度参数调优进度回调、失败跳过与并行边界多控件导出最容易犯的毛病是无脑并行。DevExpress 导出过程不是线程安全的多个控件同时导出到同一个目录没有问题但无论是否并行底层都会各自创建工作簿内存开销非常高。我的经验是串行导出不要并行除非每个控件的数据量都在 1 万行以内且机器内存足够。并行省下的时间会被 GC 压力抵消翻车概率却直线上升。提示DevExpress 导出器不是线程安全的同一进程内不建议并行导出多个控件。进度回调尽量走 SynchronizationContext 转到 UI 线程不要在回调里直接访问控件属性。失败跳过策略按业务决定导出清单里有 10 个控件第 3 个失败是继续还是终止我建议默认继续把所有失败文件汇总到最后一起提示这样用户一次性拿到结果不用反复操作。日志里至少要记录失败控件名和异常堆栈这类问题通常不是格式错误就是数据源问题看日志比猜快得多。6. 导出完再读回来验证列格式与工作表结构的自动化检查导出的程序写完了不代表文件就一定能用。我见过太多“代码能跑、导出的文件业务方一打开就骂人”的案例所以后来把验证做成了导出的固定环节。6.1 用 Spreadsheet API 回读文件并修复格式验证脚本做的事情很简单重新打开刚导出的 xlsx检查第一个 Sheet 的前 50 行遇到科学计数法文本或日期数字序列号就现场修掉public static bool ValidateAndFix(string filePath) { using (Workbook wb new Workbook()) { wb.LoadDocument(filePath); Worksheet ws wb.Worksheets[0]; var range ws.GetUsedRange(); if (range null) return false; for (int r 0; r Math.Min(range.RowCount, 50); r) { var cell ws.Cells[r, 0]; string text cell.DisplayText; if (text.Contains(E)) { cell.SetValue(text); cell.NumberFormat ; } } wb.SaveDocument(filePath); } return true; }逻辑说明这一段主要是“兜底修复”不是把导出逻辑重做一遍。DisplayText 会把单元格当前显示值字符串化如果里面有 E说明 Excel 显示成了科学计数法SetValue 把原始字符串写回去NumberFormat 设置为文本这样身份证号就不会再被截断。只检查前 50 行因为科学计数法是否触发跟数据值有关扫前几十行足够发现问题。参数说明LoadDocument 支持 xlsx在工作簿打开后文件句柄还在控制中using 保证释放。这个验证方法我一般放在自动化测试或打包脚本里而不是每次导完都弹出来。6.2 强制走一遍的验收清单从那以后凡是交给业务方的批量导出我都会强制走一遍导出前先列出控件-工作表名-文件名的映射表导出后用上面这个方法读回文件核对 Sheet 数量、首行数据、长数字列、日期列格式全过了再交付。这个过程看着多花几分钟但省掉的是“导出后才发现用不了”的返工。希望帮到你。本文还有配套的精品资源点击获取
