简介：面向需要在C#程序中自动化生成Word报表的.NET开发者，这份PDF演示了如何借助OpenXml SDK为Word文档添加表格。内容从引入DocumentFormat.OpenXml命名空间开始，逐步讲解AddTable方法的封装、TableGrid列数定义、表格边框样式设置，以及表头和数据行的循环创建逻辑，并配有可直接运行的示例代码和运行效果，便于迁移到批量生成、数据导出等实际场景。资源共1个PDF文件，大小121KB，目前已有326人学习下载，适合具备基础C#语法、希望以轻量方式操作Word文档的读者快速查阅。
1. C# 用 OpenXml 给 Word 加表格：为什么我不再碰 COM 自动化
实际做报表导出的人多半经历过这种场景：程序需要往 Word 文档里插入一张表格，数据量不大，但要求格式规整、边框齐全。常见做法是直接调 COM 自动化控制 Word 进程，开发机上跑得很好，一旦部署到没装 Office 的服务器上就各种罢工。换成开源的 OpenXml SDK 后，直接操作 docx 底层的 XML 结构，不依赖 Office，批量生成带表格的 Word 文档变得干净可控。这篇文章围绕一个具体需求展开：用 C# 的 OpenXml 给 Word 文档添加表格，覆盖表头、数据行、边框、单元格样式和最常见的坑。适合用 .NET 做报告生成、合同填充、批量导出功能的开发者，尤其是需要在 Windows 服务里跑批处理的场景。
2. 先摸清 Word 表格的 XML 骨架，再写第一段可运行代码
在写第一行代码之前，建议花十分钟把 OpenXml 的 Word 文档模型过一遍。很多人直接抄一份代码就改，结果要么列宽失效，要么表格插不进正文，最后绕回来补基础，反而更慢。这一章的思路是从打开文档的方式讲起，再看 Table 的层级，最后给出一段能直接跑通的最小代码。
2.1 WordprocessingDocument 打开文档的三种方式，别只会 Open(path, true)
OpenXml SDK 的操作入口是WordprocessingDocument，它指向的是一个 .docx 包，很多人把它当普通文件流用，结果在生命周期管理上翻车。最常见的打开方式有三个。
第一种，打开已经存在的文档并允许修改：
using (WordprocessingDocument doc = WordprocessingDocument.Open("Test.docx", true)) { // 这里可以增删改 }第二个参数isEditable必须传 true；如果只传路径不传这个参数，默认是只读。只读模式不会立刻报错，但之后的Append、Add操作都会静默失败，保存后一切变动都丢了。这是新手最容易迷惑的地方：不报错，却等于白写。
第二种，新建一个空白文档。Open方法要求文件真实存在，否则抛FileNotFoundException。正确做法是用Create：
using (WordprocessingDocument doc = WordprocessingDocument.Create("NewDoc.docx", WordprocessingDocumentType.Document)) { MainDocumentPart mainPart = doc.AddMainDocumentPart(); mainPart.Document = new Document(new Body()); }这段代码有两个点不能省：AddMainDocumentPart()负责创建文档主部件，Document = new Document(new Body())负责在包内生成空的正文结构。少一句，后面访问doc.MainDocumentPart.Document.Body就会得到 null 引用。
第三种，从流打开。常用于把模板读进MemoryStream，再传给Open(stream, true)，避免临时文件落盘。这时要注意流的所有权：doc.Dispose()时也会关闭流，后续如果还要用这个流，得自己重新创建。批处理时如果同时操作多个文件，用流方式可以避免很多文件句柄问题。
using是这个场景的硬性要求。OpenXml 包在Dispose时才把未保存的内容写回文件，如果不Dispose，要么文件一直被占用，要么改动直接丢失。我见过不止一个人因为少写using，排查到半夜，最后发现是 Word 进程把 docx 锁住了。
2.2 Table 的层级：Table、TableGrid、TableRow、TableCell、Paragraph
Word 表格在 OpenXml 里的结构不是简单的二维数组，而是一个嵌套树。一个正常的表格，从上到下大致是这个形状：
Table ├── TableGrid │ └── TableGridColumn ├── TableProperties ├── TableRow │ └── TableCell │ └── Paragraph │ └── Run │ └── TextTableGrid定义表格一共有多少列，以及每列的宽度。TableGridColumn的Width属性单位是 twips，1 厘米约等于 567 twips，做导出的同学按这个比例换就行。TableRow是行，TableCell是单元格，单元格不能直接放字符串，必须先有Paragraph，再在Paragraph里放Run，最后在Run里放Text。这个嵌套顺序是 Word 渲染的基本要求，缺一层都会导致文档结构不完整。
理解了层级，再回头看原示例代码里的grid.Append(new TableGrid())，就能发现问题：应该追加的是TableGridColumn，而不是又一个TableGrid；同时grid也需要由table.Append(grid)挂到 Table 上。原示例里 grid 创建之后没有真正进入 Table，列定义等于无效。这种问题 SDK 不会报错，但 Word 打开时列宽会全部按照内容自动分配。
这里还要纠正一个隐藏得更深的错误：原示例在插入表格时用了new Paragraph(new Run(table))。Table是不能被塞进Run里的，它必须直接作为 Body 或容器的子元素。这种写法的本意可能是想给表格包一层段落，但 OpenXml 没有这种构造方式。正确做法是直接body.Append(table)，表格本身已经是一个独立的块级元素。
2.3 最小可运行示例：从空白文档到三列表格
把前面几个要素串起来，最小可运行代码是下面这样：
using System; using DocumentFormat.OpenXml; using DocumentFormat.OpenXml.Packaging; using DocumentFormat.OpenXml.Wordprocessing; public static void CreateSimpleTable(string filePath) { using (WordprocessingDocument doc = WordprocessingDocument.Create(filePath, WordprocessingDocumentType.Document)) { MainDocumentPart mainPart = doc.AddMainDocumentPart(); mainPart.Document = new Document(new Body()); Table table = new Table(); // 1. 定义两列，每列宽度 2000 twips TableGrid grid = new TableGrid(); grid.Append(new TableGridColumn() { Width = "2000" }); grid.Append(new TableGridColumn() { Width = "2000" }); table.Append(grid); // 2. 第一行两个单元格 TableRow row = new TableRow(); row.Append(CreateCell("A")); row.Append(CreateCell("B")); table.Append(row); mainPart.Document.Body.Append(table); } } private static TableCell CreateCell(string text) { TableCell cell = new TableCell(); Paragraph paragraph = new Paragraph(); Run run = new Run(); run.Append(new Text(text)); paragraph.Append(run); cell.Append(paragraph); return cell; }这段代码的逻辑很直接：先创建Table，把TableGrid挂进去定义列宽；然后一行行构建单元格；最后把表格挂到Body末尾。CreateCell方法值得说明一下：TableCell下面必须有一个段落，段落里必须有 Run，Run 里才是文本，这个嵌套在业务代码里很容易漏写，漏了之后 Word 里会显示成空单元格。
参数说明：TableGridColumn.Width传的是 twips 字符串，想按内容自适应可以传"auto"，但报表场景我更推荐固定值，因为 Word 在无表格列定义或列宽不一致时，会按照内容长度自行分配，导致最终效果和设计稿差很多。两列的Width = "2000"就是大约 3.5 厘米，按需调整。
这个例子跑通后，你已经有了一个结构合法的表格。接下来要做的，是把表头和数据行真正填进去，并加上边框。
3. 把表头和业务数据写进 Word：AddTable 方法的完整拆解
项目示例的 AddTable 方法，本质上是在解决三件事：数据怎么传进来、每一行怎么创建、表格边框怎么不丢。这一章把它拆开讲，顺带修正示例里几个测试时发现的问题。
3.1 方法签名与数据准备：为什么用 List<string[]>
AddTable的典型签名是：
public static void AddTable(string wordPath, List<string[]> lstData, string[] headerArray)三个参数分别是 Word 文件路径、二维数据（每一行是 string[]）、表头数组。用List<string[]>看着不够面向对象，但在批量导出场景非常实用：数据从数据库查出来后，通常也是 List 结构，直接 select 成 string[] 即可，省去为每个报表单独建实体类的步骤。OpenXml 只关心字符串内容，格式化交给上层处理。
这里要留意一个细节：列数。示例里用lstData.Select(x => x.Count()).Max()求最大列数，思路对，但有个隐患。如果某一行数组长度小于最大列数，后面遍历建行时该行会少几个单元格，Word 里会表现出单元格错位或表格列数不一致。我一般在构建表格前统一补成等长数组：
int maxColumnNum = lstData.Max(x => x.Length); for (int i = 0; i < lstData.Count; i++) { if (lstData[i].Length == maxColumnNum) continue; string[] paddedRow = new string[maxColumnNum]; Array.Copy(lstData[i], paddedRow, lstData[i].Length); for (int j = lstData[i].Length; j < maxColumnNum; j++) paddedRow[j] = string.Empty; lstData[i] = paddedRow; }这段代码的逻辑是：先算出最大列数，然后把每一行长度不足的部分用空字符串补齐。补位之后，整个二维数组变成一个规整的矩形，TableRow 数量稳定，TableGrid 的列定义才不会失效。如果你的数据本来就规整，这段可以不写，但报表数据来自多张表时，字段缺失是常态，留着更安全。
3.2 TableRow 统一构建：表头和内容用同一个方法
原示例把表头和数据行用同一个 foreach 逻辑处理，这个思路很好。我倾向于再抽一个BuildRow方法，表头和数据都通过它来创建行，后面要单独改样式时，只动表头那一次调用即可。
private static TableRow BuildRow(IEnumerable<string> cellTexts) { TableRow row = new TableRow(); foreach (string text in cellTexts) { TableCell cell = new TableCell(); Paragraph paragraph = new Paragraph(); Run run = new Run(); run.Append(new Text(text)); paragraph.Append(run); cell.Append(paragraph); row.Append(cell); } return row; }这个方法内部做的事情非常直白：每个字符串都创建一个单元格，单元格里放一个段落，段落里放一个 Run，Run 里才是文本。很多初学者会把 Text 直接塞给 TableCell，这是行不通的。TableCell 在 OpenXml 里只是容器，不经过 Paragraph 和 Run 两层包装，Word 根本不会把内容当作可显示文本。
参数说明：IEnumerable<string>让方法同时接收数组和 List，表头数组可以传，数据行 string[] 也可以传。如果你想在表头行加粗、加底色，可以把表头作为单独字段放进去，或者在生成表头后用另一个赋值函数处理第一行对象。后面 4.1 会给一个带样式的表头单元格写法。
示例还提到“有 TableHeader 对象，用不来”。解释一下：TableHeader是TableRow的派生类，专门用于跨页重复表头。如果表格不会跨页，用普通 TableRow 就行；如果表格长到跨页，希望每一页顶部都出现表头，第一行应该用TableHeader。这一点到 4.4 再展开。
3.3 TableProperties 边框配置：六个方向的边框一个都不能少
默认情况下，OpenXml 创建的表格不带边框，直接写入 Word 会显示成无框线表格。要加边框，必须给 Table 挂TableProperties，里面再放TableBorders。
示例里的边框写法本身是对的，但有几个参数值得展开：
TableProperties tblProp = new TableProperties( new TableBorders( new TopBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 2 }, new BottomBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 2 }, new LeftBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 2 }, new RightBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 2 }, new InsideHorizontalBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 2 }, new InsideVerticalBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 2 })); table.Append(tblProp);边框类型有六种：上、下、左、右、内部横线、内部竖线。Size的单位不是像素，而是 1/8 磅，Size = 2实际约等于 0.25 磅，屏幕上看着像没有。想要明显一点的边框，给 4 或 8，分别对应 0.5 磅和 1 磅。Val除了Single，还有Dashed、Dotted、Double，但正式报表用 Single 最稳妥。
另一个关键是枚举的写法。OpenXml SDK 里大多数属性值是强类型枚举，比如BorderValues.Single，赋值时要通过new EnumValue<BorderValues>(...)包一层，不能直接写= BorderValues.Single。很多从旧版 OpenXml 2.0 迁移过来的同学经常在这里遇到编译错误。
TableProperties里子元素的顺序也有讲究。Word 对tblPr内部元素有固定 schema 顺序，手动Append时容易打乱。顺序不对，SDK 不会报错，但 Word 打开可能忽略部分属性。稳妥做法是用构造函数一次传完，不要多次 Append。
3.4 更完整的 AddTable 流程：整合数据、表头、边框
把以上内容组合起来，一个能用于生产环境的 AddTable 大致如下：
public static void AddTable(string wordPath, List<string[]> lstData, string[] headerArray) { using (WordprocessingDocument doc = WordprocessingDocument.Open(wordPath, true)) { Body body = doc.MainDocumentPart.Document.Body; int maxColumnNum = Math.Max(headerArray.Length, lstData.Max(x => x.Length)); Table table = new Table(); // 列定义 TableGrid grid = new TableGrid(); for (int i = 0; i < maxColumnNum; i++) { grid.Append(new TableGridColumn() { Width = "2500" }); } table.Append(grid); // 边框属性 TableProperties tblProp = new TableProperties( new TableBorders( new TopBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 4 }, new BottomBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 4 }, new LeftBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 4 }, new RightBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 4 }, new InsideHorizontalBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 4 }, new InsideVerticalBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 4 })); table.Append(tblProp); // 表头行 table.Append(BuildRow(headerArray)); // 数据行 foreach (string[] rowData in lstData) { table.Append(BuildRow(rowData)); } body.Append(table); } }这段代码和原示例主干一致，但做了三处修正：第一，grid 里追加的是TableGridColumn，并且真正挂到 table 上；第二，边框 Size 提高到了 4，更适合查看和打印；第三，表头和数据的行构建统一走BuildRow，避免重复代码。
有同学问，为什么 TableGrid 要放在 TableProperties 前面。实际上 Table 内元素按照 OOXML 的 schema，TableGrid 应该出现在 TableRow 之前，TableProperties 一般放在 TableGrid 之后。具体顺序可以用 OpenXmlValidator 验证，这个验证器在最后一章会给代码。顺序正确的前提下，Word 才能稳定地识别边框和列宽。
4. 单元格样式与通用布局：背景色、对齐、合并、重复表头
基础表格能跑通后，真实的报表需求就来了：表头要加底色、数字列要右对齐、某些单元格要合并。这一章把单元格样式和高频布局操作拆开，代码都是可以直接抄进项目的。
4.1 TableCellProperties 与 Shading：给表头加上底色
单元格样式最核心的对象是TableCellProperties，简称 tcPr。它负责单元格宽度、背景色、垂直对齐、合并等。给表头加底色，要往 tcPr 里塞Shading：
private static TableCell BuildHeaderCell(string text) { TableCell cell = new TableCell(); TableCellProperties cellProps = new TableCellProperties(); // 背景色，Fill 是十六进制，不带 # Shading shading = new Shading() { Fill = "D9E2F3" }; cellProps.Append(shading); // 单元格宽度，单位 twips TableCellWidth cellWidth = new TableCellWidth() { Type = TableWidthUnitValues.Dxa, Width = "2500" }; cellProps.Append(cellWidth); cell.Append(cellProps); Paragraph paragraph = new Paragraph(); // 段落居中 ParagraphProperties paraProps = new ParagraphProperties(); paraProps.Append(new Justification() { Val = JustificationValues.Center }); paragraph.Append(paraProps); Run run = new Run(); run.Append(new Text(text)); paragraph.Append(run); cell.Append(paragraph); return cell; }Fill是十六进制颜色字符串，不带 # 号。D9E2F3是浅蓝灰，表头常用。TableCellWidth的Type有三种：Dxa固定宽度、Auto自动、Pct百分比。建议固定列宽都用Dxa，让 Word 不参与列宽决策。
Justification控制段落文字在单元格内的水平对齐，Center居中，Right右对齐。如果还要控制垂直居中，需要在 tcPr 上追加TableCellVerticalAlignment：
cellProps.Append(new TableCellVerticalAlignment() { Val = TableVerticalAlignmentValues.Center });有个坑必须提醒：TableCellProperties在TableCell里必须位于Paragraph之前。如果先 Append 了 Paragraph 再 Append tcPr，文档结构不符合 schema，有些 Word 版本会直接视为无效单元格。SDK 平时不拦你，但验证阶段会报警。
4.2 合并单元格：GridSpan 做水平合并，VerticalMerge 做垂直合并
合并单元格在制作复杂表头时躲不开。OpenXml 里水平合并和垂直合并不是一回事。
水平合并用GridSpan，表示这个单元格横跨几列。比如一个单元格跨两列：
TableCell spanCell = new TableCell(); TableCellProperties spanProps = new TableCellProperties(); spanProps.Append(new GridSpan() { Val = 2 }); spanCell.Append(spanProps); Paragraph p = new Paragraph(); p.Append(new Run(new Text("跨两列"))); spanCell.Append(p);使用GridSpan时，TableGrid 里依然定义两列，但该行里的单元格数量会少一个。这不会导致列数错误，因为 Word 知道这个单元格占了两列的位置。
垂直合并用VerticalMerge，和 Excel 的合并单元格概念不同。需要两个单元格配合：起始单元格设置Restart，后续单元格设置Continue。比如：
// 第一行 TableCell vMergeStart = new TableCell(); vMergeStart.Append(new TableCellProperties( new VerticalMerge() { Val = MergedCellValues.Restart })); vMergeStart.Append(new Paragraph(new Run(new Text("纵向合并")))); // 第二行 TableCell vMergeContinue = new TableCell(); vMergeContinue.Append(new TableCellProperties( new VerticalMerge() { Val = MergedCellValues.Continue })); vMergeContinue.Append(new Paragraph());Continue单元格不需要写文本，Word 会把它并入上方的起始单元格。但最好保留一个空 Paragraph，否则个别版本在打印预览时会出现高度不对的问题。我在一次打印测试里就见过表格第二页多出一条空白横线，原因就是 Continue 单元格里没有 Paragraph。
4.3 表格整体宽度和对齐：TableWidth 与 TableJustification
除了单元格，整个表格也能设置宽度和页面水平对齐。比如让表格居中并占满页面宽度，可以这样写：
TableProperties tableProps = new TableProperties( new TableWidth() { Type = TableWidthUnitValues.Pct, Width = "5000" }, new TableJustification() { Val = TableRowAlignmentValues.Center }); table.Append(tableProps);这里的"5000"在 Pct 类型下代表 100%，因为 Word 内部把百分比放大了。如果你要 50% 宽度，写"2500"；如果不想换算，直接用Dxa类型，比如Width = "8500"，大约是一页 A4 可用宽度。这个换算关系很容易错，很多项目的表格宽度异常都是在这里翻车的。
TableJustification控制的是表格在页面上的左右位置，和单元格内文字对齐是两回事。我做报表的习惯是：外层表格居中，单元格内文字按列性质决定居左还是居右；数字列右对齐，文本列左对齐，这个组合最常见。
4.4 让表头跨页重复：TableHeader 的正确打开方式
长表格跨页后，第二页顶部往往没有表头，阅读体验很差。OpenXml 提供了TableHeader，它继承自TableRow，只需要把第一行替换成它：
TableHeader headerRow = new TableHeader(); foreach (string headerText in headerArray) { headerRow.Append(BuildHeaderCell(headerText)); } table.InsertAt(headerRow, 0);使用限制有两点：表头必须是表格的第一行；表格真正跨页时才有效。如果表格只有几行，TableHeader和普通TableRow没有区别。项目中遇到一页装不下的明细表，加上这个设置，第二页顶部会自动出现重复表头，省去手工分页的烦恼。
5. 用 OpenXml 加表格避坑记录：五个翻车现场与修复
这一章记录的是实际开发中容易反复踩的五个问题。每条按“现象、原因、解决”的顺序写，方便你对照自己的代码。
5.1 表格列宽失效：grid 没挂到 Table 上，Width 全白设
现象：表格成功写入 Word，但列宽完全不受控制，有的列被内容撑得很宽，有的挤成一团；检查代码，TableGridColumn的 Width 都写了，就是无效。
原因：大多是结构错误。常见两种：一是把new TableGridColumn()写成了new TableGrid()，导致 grid 里没有列定义；二是创建了 grid 却忘了table.Append(grid)，导致 TableGrid 没有成为 Table 子元素。Word 找不到列定义时，只能按单元格内容自动分配列宽。
解决：严格按层级把 grid 放进 table：
TableGrid grid = new TableGrid(); for (int i = 0; i < columnCount; i++) { grid.Append(new TableGridColumn() { Width = "2500" }); } table.Append(grid);如果修正后列宽仍不对，检查 TableGridColumn 的数量和数据行里 TableCell 的数量是否一致。比如一行有 3 个单元格，grid 却定义 4 列，Word 表格会多出一列默认宽度。遇到这种情况，用 OpenXmlValidator 会提示列数与网格不匹配。
5.2 直接 Open 不存在的文件：FileNotFoundException 而不是友好提示
现象：程序在WordprocessingDocument.Open("不存在的.docx", true)这一行抛出FileNotFoundException，路径没问题，但文件确实不在。
原因：Open方法不支持“文件不存在就自动创建”。它要求目标文件已经存在且是合法 .docx。原示例默认Test.docx已经存在，许多初学者把路径换成自己的，没注意文件根本不存在，于是直接失败。
解决：在打开前做一次存在性判断，不存在就用Create建一个空白文档：
if (!File.Exists(wordPath)) { using (WordprocessingDocument doc = WordprocessingDocument.Create(wordPath, WordprocessingDocumentType.Document)) { MainDocumentPart mainPart = doc.AddMainDocumentPart(); mainPart.Document = new Document(new Body()); } }如果担心 Create 会覆盖，可以把判断逻辑放在程序入口，生成文件名的同时确认文件状态。批量导出时，我一般是先删掉旧的临时文件，再 Create，避免残留数据。
5.3 docx 文件被占用：IOException 或“文件正由另一进程使用”
现象：第一次运行正常，第二次运行时报IOException，提示文件正由另一进程使用。或者写入过程中，Word 打开了同一个文件，保存直接失败。
原因：docx 本质是 ZIP 包，WordprocessingDocument.Open会持有底层文件句柄直到对象释放。如果using没写，句柄不会释放；另一种情况是自己创建的 FileStream 也占用着文件，和 OpenXml 包的句柄冲突。Word 打开同一个文件时，同样不允许其他进程覆盖写入。
解决：第一，所有入口都用using包裹。第二，不要在外部额外打开 FileStream。第三，服务器批处理场景下，先复制一份到临时路径再操作：
string tmpPath = Path.GetTempFileName(); File.Copy(wordPath, tmpPath, true); using (WordprocessingDocument doc = WordprocessingDocument.Open(tmpPath, true)) { // 写入表格 doc.SaveAs(wordPath); } File.Delete(tmpPath);这样源文件始终不被占用，写入完成后用SaveAs覆盖回去。注意SaveAs只能在 Open 模式下使用，Create 模式下不支持，这个细节也值得记住。
5.4 中文乱码或文字不显示：很多情况下是少了一层 RunProperties
现象：表格写入成功，但中文在 Word 里显示成问号、方块，或者单元格里空白一片，点击进入才能看到文字。代码里明明用new Text("中文")写入的。
原因：OpenXml 写文本时，如果 Run 没有指定字体，Word 会用文档默认字体。没有 Office 的服务器环境里，默认字体可能不是中文字体，于是在渲染阶段变成乱码。另外，如果单元格里只有 Text 没有 Paragraph，或者 Run 没有挂进 Paragraph，Word 也识别不到内容。
解决：给 Run 显式设置中文字体，覆盖三个字体槽：
RunProperties runProps = new RunProperties(); runProps.Append(new Fonts() { Ascii = "Microsoft YaHei", HighAnsi = "Microsoft YaHei", EastAsia = "Microsoft YaHei" }); Run run = new Run(); run.Append(runProps); run.Append(new Text("中文内容"));Fonts的Ascii管西文字符，HighAnsi管扩展字符，EastAsia才管中文。只设 Ascii 的话，中文依旧可能乱码。我曾在某个报表项目里排查大半天，最后发现是服务器上缺少中文字体，把 RunProperties 显式指定后问题才解决。
5.5 TableProperties 子元素顺序不对：样式时灵时不灵
现象：同样的代码，把 TableProperties 放在不同位置后，有时 Word 显示边框，有时边框完全消失，而且不报任何错。看起来很像玄学。
原因：Word 解析 OOXML 的tblPr和tcPr时，对子元素顺序有强制要求。OpenXml SDK 的构造函数重载一般能保证顺序，但手工多次 Append 就很容易打乱。顺序不符时，Word 会静默忽略部分属性，不给出错误提示。
解决：手工构造 TableProperties 时，按下面的顺序追加常用子元素：TableStyle、TableJustification、TableWidth、TableBorders 等。最稳妥的方式是用构造函数一次性传参，顺序即 schema 顺序：
TableProperties tblProp = new TableProperties( new TableWidth() { Type = TableWidthUnitValues.Dxa, Width = "8500" }, new TableJustification() { Val = TableRowAlignmentValues.Center }, new TableBorders( new TopBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 4 }, new BottomBorder() { Val = new EnumValue<BorderValues>(BorderValues.Single), Size = 4 } ) );如果属性不生效，别靠猜，用 OpenXmlValidator 把错误列出来，它连哪个元素的顺序错了都能告诉你。这个习惯我是在被 Word 的“修复文档”弹窗教育了两次之后才养成的。
6. 收尾进阶：指定位置插入表格、自动验证和重复表头的完整组合
基础表格能加之后，实际交付往往会遇到三个高频需求：表格不要总出现在文末、长表格要跨页重复表头、生成的文件不能一打开就提示修复。把这三个技巧串起来，基本能覆盖大多数批量导出场景。
第一个技巧，在指定位置插入表格。Body.Append(table)只能把表格追加到文档末尾，不符合业务里“在第三段后面插一张表”的要求。常见做法是先定位到目标段落，再用InsertAfterSelf插到它后面：
Paragraph target = body.Descendants<Paragraph>() .FirstOrDefault(p => p.InnerText.Contains("插入点")); if (target != null) { target.InsertAfterSelf(table); }注意 table 如果已经被 Append 过，再次插入会报元素已存在异常。我通常先把表格构建好，再决定插入位置，只插一次。
第二个技巧，表头跨页重复。把第一行声明为 TableHeader 即可：
TableHeader headerRow = new TableHeader(); foreach (string headerText in headerArray) { headerRow.Append(BuildHeaderCell(headerText)); } table.InsertAt(headerRow, 0);这里假设 table 里还没有任何行，或者你已经先把原来的表头行清掉。TableHeader是 TableRow 的子类，所以插入逻辑和普通行一致。
第三个技巧，也是我每次写 OpenXml 必做的一步：保存前用 OpenXmlValidator 验证结构。使用前需要引入DocumentFormat.OpenXml.Validation命名空间。这个验证器能发现单元格层级、属性顺序、多余嵌套等问题，省去在 Word 里反复试错：
using DocumentFormat.OpenXml.Validation; using (WordprocessingDocument doc = WordprocessingDocument.Open(filePath, true)) { var validator = new OpenXmlValidator(); var errors = validator.Validate(doc).ToList(); foreach (var error in errors) { Console.WriteLine($"{error.Path} - {error.Description}"); } }以前我不太信任验证器，总觉得手工写的代码自己心里有数。直到有一次交付的文档被对方打开后提示“文件已损坏，是否修复”，才意识到检查工具比肉眼可靠。从那以后，每次生成完 docx，我都会在单元测试里跑一遍 OpenXmlValidator，再解压 document.xml 看一眼表格段落的位置。这套流程看着多两步，实际上省掉了大量返工。希望这些记录对你也有用。
本文还有配套的精品资源，点击获取
