简介：面向使用 DevExpress 控件进行 WinForm 桌面应用开发的程序员，这份压缩包的目标是在多个控件场景下快速获得可靠的 Excel 导出能力。包内是一套通用导出方法的完整工程，重点解决 GridControl 表格控件无法导出图片、多表头无法完整导出，以及 PivotGridControl 透视表格导出时自动分组等问题，实现所见即所得的导出效果；同时支持多个控件一次性导出到同一个 Excel 文件，并可把不同控件分放到不同工作表。资源以 zip 压缩包形式发布，共 179 个文件，包括 110 个 dll 程序集依赖库、23 个 xml 配置说明文件、10 个 cs 核心源码文件，另有若干图片、配置、工程备份和授权信息文件，整个压缩包约 35.09MB。目前已有 1020 人学习/下载。包内是完整的 Visual Studio 解决方案与源码工程，目录结构清晰，开发者可直接打开并集成到现有 WinForm 项目，也可参考封装思路处理多控件导出 Excel 的兼容性与布局细节，便于二次开发和问题排查。

1. 为什么Dev控件导出Excel值得做一套通用方法

做 WinForm 项目案例时最经常被追问的一句话是：“这个界面能不能导成 Excel？”只有一张 GridControl 时，三行代码就能解决；但界面上同时有 GridControl、PivotGridControl 和 ChartControl，客户还要求一次导出自动分工作表，问题就不一样了。

DevExpress 的控件自带 ExportToXlsx 方法，但每个控件的导出签名和选项类各不相同，复制粘贴拼出来的多控件导出代码，十有八九在第二个控件执行时就翻车。本文要给的是一套通用控件导出方案：不引入第三方 Excel 库，用 DevExpress 自带能力把多个控件分工作簿导出到同一个 Excel 文件，顺带把最常见的五个坑讲清楚。适合正在做报表模块的 WinForm 开发者，按步骤即可落地。

2. 导出选项的地基：XlsxExportOptionsEx与控制导出结果的三层干预点

在开始写导出代码之前，先花五分钟把 DevExpress 的导出选项体系捋清楚。这一层没看懂，后面碰到“第二个控件把第一个覆盖了”这类问题，会排查得很痛苦。

2.1 XlsxExportOptions与XlsxExportOptionsEx：该用哪个

DevExpress 里有两套 XLSX 导出选项类，一套叫XlsxExportOptions，一套叫XlsxExportOptionsEx。后者带“Ex”后缀，是为解决旧版选项无法处理多工作表追加、样式还原等问题而推出的，继承自前者，并且多出ExportMode、SheetName等关键属性。

我一般建议直接使用XlsxExportOptionsEx。原因有两点：第一，它在较新的 DevExpress 版本里是 GridControl、TreeList、PivotGridControl 等控件ExportToXlsx方法的标准参数类型，传旧的XlsxExportOptions反而要做一次隐式转换；第二，ExportMode.Append这个模式只在 Ex 类上可用，而它是多控件分工作簿导出的核心开关。

这里顺带解释一个常见误用：很多老代码里写的是gridControl.ExportToXlsx(filePath, new XlsxExportOptions())，当需要把第二个控件追加到同一个文件时，找不到追加参数，只能绕道用第三方库去合并 Excel 文件。其实只要换成XlsxExportOptionsEx并把ExportMode设为Append，这个问题就消失了，不需要额外引入任何依赖。

2.2 ExportMode三种模式：SingleFile、SingleFileV2与Append的分工

XlsxExportMode枚举有三种取值。理解它们之间的差别，是理解多控件分工作簿导出的前提。

SingleFile和SingleFileV2的差别主要体现在导出引擎内部的写入方式上，肉眼几乎看不出区别。平时可以统一用Append，因为它在文件不存在时会自动走“创建”分支，文件存在时走“追加”分支，行为比想象中更安全。

需要注意一个细节：Append追加的是“新工作表”，不是“新工作簿”。如果你连续导出两个 GridControl，第一个工作表叫“Sheet1”，第二个工作表会追加为“Sheet2”。如果第二个控件在导出时指定了和第一个相同的SheetName，会抛出异常，这一点在后文避坑章节里单独展开。

2.3 控制导出结果的三层干预点：控件层、选项层、事件层

很多初学者把“导出的 Excel 内容和界面上不完全一样”归咎于控件 bug，其实是因为没有理解导出引擎的工作层次。导出结果受三层因素控制，从里到外依次是：

第一层是控件本身的状态。GridControl 里列是否隐藏、列的DisplayFormat是什么、GridView 是否处于分组状态，都会直接影响导出内容。DevExpress 导出时读取的是当前控件的可视结构，而不是原始 DataSource。所以“我在界面上看到的是 A，导出来却是 B”这类问题，八成出在这一层。

第二层是导出选项。XlsxExportOptionsEx里的SheetName、ExportMode、ExportHiddenColumns、TextExportMode这些属性，决定了写入文件时的整体行为。它们解决的是“写到哪、怎么组织、列要不要全出”这类结构性问题。

第三层是导出事件。CustomizeCell、CustomizeHeaderCell等事件允许你在导出过程中逐单元格干预，比如把特定列设为文本格式、给某行加背景色。这一层是调整样式的主要阵地，也是最后一层后悔药。后文第 6 章会专门演示。

这三层之间是递进关系：先设置控件状态，再配置选项，最后在事件里做单元格级微调。跳过任何一个层，都可能得到一份“能打开但没法用”的 Excel。

3. 单控件导出到Excel：最小代码与必调参数

3.1 最小可运行代码：GridControl导出到xlsx

从最基础的场景开始：界面上只有一个 GridControl，直接导出。最小代码就三行：

string filePath = @"D:\exports\grid_data.xlsx"; var options = new XlsxExportOptionsEx(); gridControl1.ExportToXlsx(filePath, options);

这段代码能跑通，但有两个隐患。第一，options没有设置ExportMode和SheetName，默认行为是覆盖式写出，工作表名由 DevExpress 自动生成。第二，gridControl1如果存在多个视图（比如 Master-Detail 结构），默认导出的是MainView，不是你界面上正在看的那一个。

更稳妥的最小写法是显式指定视图：

GridView view = gridControl1.MainView as GridView; if (view == null) return; var options = new XlsxExportOptionsEx { SheetName = "销售明细", ExportMode = XlsxExportMode.Append, TextExportMode = TextExportMode.Value }; view.ExportToXlsx(filePath, options);

代码说明：这里用view.ExportToXlsx而不是gridControl1.ExportToXlsx，是因为后者在复杂视图结构下可能导错视图。GridView本身继承自BaseView，导出方法在视图级别就有，所以直接用视图来导出，意图更明确。

3.2 必调参数：SheetName与ExportMode

SheetName决定工作表页签名，ExportMode决定是否覆盖原文件。这两个参数在单控件导出时看着可有可无，但必须在多控件导出前养成显式设置的习惯。

SheetName为空时，DevExpress 会生成类似“Sheet1”的默认名。如果你在业务系统里同时导出月报和年报，Excel 里出现三个“Sheet1”，用户根本分不清哪个是哪个。显式设置SheetName后，工作表名变成“2024年12月销售明细”这类业务名，这是报表导出最基本的人性化要求。

ExportMode用Append而非默认值，理由在前一章已经说过：Append在文件不存在时也会创建文件，行为自适应，适合做统一入口。唯一要注意的是，如果目标文件已经存在且里面有一张同名工作表，Append会抛异常。所以在多控件导出前，通常先删掉旧文件。

3.3 列、视图与数据的三个常见控制点

单控件导出时，有三个控制点需要掌握。

第一个是视图选择。用MainView还是FocusedView，取决于业务语义。MainView是 GridControl 默认绑定的视图，通常稳定可靠；FocusedView跟随界面焦点，在带 Master-Detail 的复杂网格里更符合用户直觉。我一般建议用MainView，因为焦点位置在导出过程中可能变化，导出结果跟随焦点会出现不确定性。

第二个是隐藏列。默认情况下，DevExpress 会把隐藏列一并导出，导致 Excel 里出现界面上一辈子看不到的 ID 列。解决方案是在选项上关掉隐藏列导出：

options.ExportHiddenColumns = false;

设置后，导出的列顺序就和 GridView 上可见列的顺序完全一致，这个顺序同时会反映到 CustomizeCell 事件的列索引里，后文讲样式时会用到。

第三个是数据格式。TextExportMode有两个值：Text表示所有单元格都按字符串写入，Value表示按原始值类型写入。数字保持数字、日期保持日期，单元格在 Excel 里才能正常参与排序和求和。绝大多数报表场景都用Value，只有遇到超长数字 ID 时才需要把特定列切回文本格式，这个坑在第 5 章单独讲。

4. 多控件分工作簿导出：追加模式装配和两个典型场景

4.1 多控件导出的正确顺序：先建文件，再追加sheet

多个控件导出到同一个 Excel 文件和“往一个 zip 包里持续加文件”的思路类似：第一个控件建文件，后面的控件往文件里追加工作表。只不过 DevExpress 里不需要手动区分“第一个”和“后续”，因为 Append 模式本身就做了自适应。

顺序上有三个硬性要求：

第一，先删除旧文件。如果目标路径下已经存在一个带同名工作表的 xlsx，Append 会直接抛异常。删掉旧文件等于给每一次导出都留了干净起点。

第二，每个控件都要新建一个XlsxExportOptionsEx实例。不要把同一个 options 对象传给多个控件的导出方法，因为导出引擎在调用过程中会修改选项内部状态，复用实例极大概率造成第二个工作表内容串到第一个工作表里。

第三，目标文件不能被 Excel 锁定占用。Append 模式需要打开文件写入，如果用户已经用 Excel 打开了这个文件，第二次追加会失败。这个属于人机交互层面的问题，导出前提示用户关闭相关文件即可。

4.2 完整代码：GridControl + PivotGridControl 导出到同一个工作簿

下面给出一段可以直接拿去改造的完整实现。它接收一个控件数组，把所有控件依次导出到一个 xlsx 文件，每个控件占一个工作表。

using DevExpress.XtraExport; using DevExpress.XtraPivotGrid; using DevExpress.XtraTreeList; using DevExpress.XtraGrid; public static class ExcelExporter { private static void PrepareFile(string filePath) { string dir = Path.GetDirectoryName(filePath); if (!string.IsNullOrEmpty(dir) && !Directory.Exists(dir)) Directory.CreateDirectory(dir); if (File.Exists(filePath)) File.Delete(filePath); } public static void ExportToWorkbook(object[] controls, string filePath) { PrepareFile(filePath); for (int i = 0; i < controls.Length; i++) { var options = new XlsxExportOptionsEx { SheetName = $"Sheet{i + 1}", ExportMode = XlsxExportMode.Append, TextExportMode = TextExportMode.Value, ShowGridLines = false }; ExportSingle(controls[i], filePath, options); } } private static void ExportSingle(object control, string filePath, XlsxExportOptionsEx options) { switch (control) { case GridControl grid: grid.ExportToXlsx(filePath, options); break; case PivotGridControl pivot: pivot.ExportToXlsx(filePath, options); break; case TreeList tree: tree.ExportToXlsx(filePath, options); break; default: throw new NotSupportedException($"暂不支持的控件类型: {control?.GetType().Name}"); } } }

调用方式：

var controls = new object[] { gridControl1, pivotGridControl1, treeList1 }; ExcelExporter.ExportToWorkbook(controls, @"D:\exports\月度报表.xlsx");

逻辑说明：PrepareFile负责建目录、删旧文件，避免残留数据干扰。循环内每次新建 options，是因为导出引擎会往选项里写入本次导出的状态信息，复用同一个实例会让第二次导出读到上一次的残留状态。SheetName在这里用Sheet{i+1}做占位，实际项目中建议改成有业务含义的名称，比如“销售明细”“部门汇总”。

参数说明：ShowGridLines = false关闭 Excel 网格线，让导出的表格更接近界面的显示效果。TextExportMode.Value保证数字列仍为数值类型，日期列仍为日期类型，方便用户在 Excel 里做后续处理。如果发现导出结果里长数字变成科学计数法，把对应列单独设置文本格式，而不是全局切到Text模式。

4.3 每控件一个独立工作簿：文件命名与临时目录策略

不是所有场景都要求合并到一个工作簿。有些客户希望“销售明细.xlsx”“部门汇总.xlsx”分开交付，这时候用追加模式反而不合适，应该每个控件单独导出成一个文件。

public static void ExportToSeparateFiles( Dictionary<string, object> controlMap, string directory, string filePrefix) { Directory.CreateDirectory(directory); foreach (var kvp in controlMap) { string safeName = CleanSheetName(kvp.Key, 0); string filePath = Path.Combine(directory, $"{filePrefix}_{safeName}_{DateTime.Now:yyyyMMdd_HHmmss}.xlsx"); var options = new XlsxExportOptionsEx { SheetName = kvp.Key, ExportMode = XlsxExportMode.SingleFile, TextExportMode = TextExportMode.Value }; ExportSingle(kvp.Value, filePath, options); } }

调用时注意两点。第一，文件名里的时间戳不要用HH:mm:ss，Windows 文件名不允许冒号，用HHmmss即可。第二，多文件导出过程中一旦中间某个控件抛异常，前面已经生成的文件不会自动回滚，用户会拿到半套结果。稳妥做法是先导出到临时目录，全部成功后再统一移动到正式目录：

string tmpDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N")); ExcelExporter.ExportToSeparateFiles(map, tmpDir, "temp"); foreach (var file in Directory.GetFiles(tmpDir, "*.xlsx")) { File.Copy(file, Path.Combine(finalDir, Path.GetFileName(file)), true); }

这套“先临时后正式”的策略不仅适用于多文件，也适用于单文件合并场景。导出 Excel 的代码本身不复杂，复杂的是失败时怎么不给用户留下半成品。

5. 导出Excel的避坑指南：5个最常见的翻车现场

5.1 追加导出时第二个sheet写不进去

现象：多个控件用Append模式导出后，用 Excel 打开文件发现只有第一个工作表，第二个及以后的 sheet 消失了，或者第二个 sheet 是一堆空行。

常见原因：第一种是复用了同一个XlsxExportOptionsEx实例，第二次导出时内部状态没有重置，导致内容写进了第一个工作表。第二种是目标文件正被 Excel 程序占用，Append 模式打不开文件，DevExpress 在部分版本里静默跳过而不是抛异常。第三种是第二个控件本身没有数据，比如 PivotGridControl 的数据源为空，导出结果自然是一张空白表。

解决办法：每次导出都新建 options 实例，这是唯一靠得住的写法。同时，在ExportSingle里对控件做数据检查：

case GridControl grid: var view = grid.MainView as GridView; if (view == null || view.RowCount == 0) throw new InvalidOperationException("GridView 没有数据，无法导出。"); grid.ExportToXlsx(filePath, options); break;

这个检查很有价值。真实项目里“控件没数据”不是异常，但导出一张空白工作表反而会让用户误以为程序出 bug 了。主动报错比默默给空表好得多。

5.2 长数字变成科学计数法，一长串ID显示成1.23457E+17

现象：数据库里的订单号、客户ID 是 18 位数字，导出到 Excel 后显示成1.23457E+17，点开单元格一看，最后几位变成了 0。

常见原因：Excel 对超过 11 位的数字默认启用科学计数法，超过 15 位时数值精度丢失，末尾自动补零。DevExpress 以TextExportMode.Value导出时，长整数被写成数值单元格，于是触发了 Excel 的默认数字格式。

解决办法：把超长数字列改成文本格式。推荐的做法是使用CustomizeCell事件，只针对指定列设置文本格式，而不是全局切Text模式：

GridView view = gridControl1.MainView as GridView; int orderColIndex = view.VisibleColumns.IndexOf(view.Columns["OrderNo"]); var options = new XlsxExportOptionsEx { SheetName = "销售明细", ExportMode = XlsxExportMode.Append, TextExportMode = TextExportMode.Value }; options.CustomizeCell += (s, e) => { if (e.RowHandle >= 0 && e.ColumnIndex == orderColIndex) e.Cell.Formatting.SetNumberFormat("@"); // Excel文本格式 }; gridControl1.ExportToXlsx(filePath, options);

代码说明：SetNumberFormat("@")将指定列设为 Excel 的文本格式，Excel 会原样显示数字，不做科学计数法转换。e.RowHandle >= 0用于过滤分组行，分组行的行号是负数，不应该参与样式设置。

5.3 隐藏列被导出来了

现象：设计时把“创建人ID”“更新时间”这些列设为Visible = false，导出 Excel 后发现它们又出现了，还排在所有列的最前面。

常见原因：DevExpress 导出引擎默认导出所有列，包括隐藏列。很多人不知道这个行为，以为界面上看不见的列，导出时也不会出现。

解决办法：在选项上关闭隐藏列导出：

options.ExportHiddenColumns = false;

设置后，导出的列顺序与 GridView 可见列顺序一致。这一点同时影响 CustomizeCell 事件里的列索引，所以只要设置了ExportHiddenColumns = false，后文第 6 章里通过VisibleColumns.IndexOf定位列的方式才是对的。

如果项目用的 DevExpress 版本比较老，ExportHiddenColumns属性可能不存在。这时只能导出前遍历grid.Columns，把要隐藏的列临时设为Visible = false，导出结束再恢复。注意恢复操作要包裹在GridView.BeginUpdate()和EndUpdate()之间，否则界面会闪烁。

5.4 ChartControl不能追加到同一个工作簿

现象：把 GridControl 和 ChartControl 放进同一个控件数组调用通用导出方法，执行到 ChartControl 时抛异常，或者导出的 Excel 文件结构损坏。

常见原因：ChartControl.ExportToXlsx使用的是ChartExportOptions，不是XlsxExportOptionsEx。图表控件的导出选项里没有SheetName，也不支持Append模式。它和网格、透视表、树形列表的导出机制不是一套。

解决办法：实际项目中我一般把图表先导出成图片，再通过 DevExpress 的 SpreadsheetControl 把图片插到目标工作簿里：

using var ms = new MemoryStream(); chartControl1.ExportToImage(ms, System.Drawing.Imaging.ImageFormat.Png); ms.Position = 0; spreadsheetControl1.LoadDocument(filePath, DocumentFormat.Xlsx); using var image = Image.FromStream(ms); var worksheet = spreadsheetControl1.Document.Worksheets[0]; worksheet.Pictures.AddPicture(worksheet.Cells["A1"], image); spreadsheetControl1.SaveDocument(filePath, DocumentFormat.Xlsx);

这段代码依赖DevExpress.Spreadsheet程序集。如果项目里不想引入 SpreadsheetControl，另一个常见做法是让图表单独导出一个独立 xlsx 文件，再由业务侧的 Excel 自动化或 VBA 合并。缺点是不够自动化，胜在实现简单，不增加依赖。

5.5 工作表名称非法导致导出失败

现象：SheetName来自业务字段，比如“2024/11 销售明细”或“汇总:华北区”，导出时抛ArgumentException或InvalidOperationException。

常见原因：Excel 工作表名不能包含\ / ? * [ ] :这七个字符，长度不能超过 31 个字符，不能为空。业务字段直接拿来当工作表名，很容易踩中。

解决办法：写一个清洗函数，把非法字符替换成下划线并截断长度：

private static string CleanSheetName(string name, int fallbackIndex) { if (string.IsNullOrWhiteSpace(name)) return $"Sheet{fallbackIndex}"; name = name.Trim(); foreach (char c in Path.GetInvalidFileNameChars()) name = name.Replace(c, '_'); name = name.Replace(':', '_').Replace('/', '_').Replace('\\', '_'); if (name.Length > 31) name = name.Substring(0, 31); return string.IsNullOrWhiteSpace(name) ? $"Sheet{fallbackIndex}" : name; }

调用时把CleanSheetName的返回值赋给SheetName，而不是直接传业务字段。这样“2024/11 销售明细”会变成“2024_11 销售明细”，既保留了可读性，又避开了 Excel 的命名限制。

6. 进阶用法：用CustomizeCell事件控制单元格样式

导出选项上绑定CustomizeCell事件，是 DevExpress 导出引擎暴露的最后一个干预点。这个事件在导出过程中逐单元格触发，你可以对任意单元格设置背景色、字体、边框和数字格式。很多“导出结果不好看”的问题，最终都是在这里解决的。

我的做法是把样式逻辑收敛到一个静态方法里，按列名做配置，而不是在事件里写死列索引。这样即使列顺序调整，样式也不会错位：

private static void ApplyCellStyles(XlsxExportOptionsEx options, GridView view) { int amountIndex = view.VisibleColumns.IndexOf(view.Columns["Amount"]); int statusIndex = view.VisibleColumns.IndexOf(view.Columns["Status"]); options.CustomizeCell += (s, e) => { if (e.RowHandle < 0) return; // 金额列：两位小数，背景浅黄，负数标红 if (e.ColumnIndex == amountIndex && e.Cell.Value != null) { e.Cell.Formatting.SetNumberFormat("0.00"); e.Cell.Formatting.Fill.BackgroundColor.SetColor(Color.LightYellow); if (decimal.TryParse(e.Cell.Value.ToString(), out decimal amount) && amount < 0) e.Cell.Formatting.Font.Color.SetColor(Color.Red); } // 状态列：完成=绿色，未完成=橙色 if (e.ColumnIndex == statusIndex) { string status = e.Cell.Value?.ToString(); if (status == "完成") e.Cell.Formatting.Fill.BackgroundColor.SetColor(Color.LightGreen); else if (status == "未完成") e.Cell.Formatting.Fill.BackgroundColor.SetColor(Color.Orange); } }; }

使用方式很简单，把样式方法和普通导出参数放在一起：

var options = new XlsxExportOptionsEx { SheetName = "销售明细", ExportMode = XlsxExportMode.Append, TextExportMode = TextExportMode.Value, ExportHiddenColumns = false }; ApplyCellStyles(options, view); gridControl1.ExportToXlsx(filePath, options);

这里要注意一个前置条件：VisibleColumns.IndexOf拿到的列索引，只有在前文设置了ExportHiddenColumns = false时才和导出事件里的ColumnIndex对齐。如果隐藏列也在导出范围内，索引位会被隐藏列占用，样式就会跑到错误的列上。

我在这套方案上吃过一次亏，所以养成了两个固定习惯：一是所有 options 都在方法内新建，绝不抽成静态字段复用，避免导出状态串味；二是所有样式规则都按列名定位，不按列索引硬编码。前者解决了很多玄学问题，后者让代码在列顺序调整后依然能稳定运行。

希望这篇文章能帮你把 DevExpress 导出 Excel 这套逻辑理顺，少走我走过的弯路。

本文还有配套的精品资源，点击获取