简介这是基于.NET平台的C#文档处理库完整源码与演示工程面向需要在服务器或客户端程序中创建、读取、编辑Word文档并转换为PDF的开发者。资源包含Xceed.Document.NET.dll与Xceed.Words.NET.dll两个核心动态库分别负责文档对象模型与高级排版功能可在未安装微软Office的机器上处理段落、表格、图片及模板替换适合报表自动生成、合同批量填充、在线文档编辑等常见业务场景。压缩包内共有244个文件其中文档示例86个、开发语言源文件83个另有动态库、项目工程、解决方案、示例图片与配置文件整体压缩包大小约4.93兆字节目录结构清晰便于直接编译和二次维护。目前已有277人学习附带的示例工程覆盖从基础文本操作到复杂表格调整的多种用法并配有必要的说明文档可帮助开发者较快掌握相关接口。1. DocX 处理 Word 文档这套 DLL 拿回来就能跑的完整套路被报价单、合同、统计报告这类「Word 套模板」需求缠住的人基本都经历过同一个坑模板里塞着几十个占位符、一张要撑满页宽的表还得每天批量生成。自己对着 OpenXML 搓 XML 太折磨上重型自动化组件又杀鸡用牛刀。这套 DocX 资源包正好卡在中间位核心文件就是Xceed.Document.NET.dll和Xceed.Words.NET.dll外加一份可编译的 demo 源码。拿回来后给项目添加引用就能跑常见的段落、表格、图片都能编辑也可以在装了 Office 的机器上把 docx 导出成 PDF。适合被报表和模板生成缠住的后端、桌面端开发也适合方案选型前想快速验证的人——demo 本身就是最省事的说明书。和直接改 document.xml 相比这套封装把段落、表格、图片都收成了对象生成文档的逻辑写在一个方法里出问题好排查。下面按「跑起来 → 改文档 → 转 PDF → 避坑 → 批量」的顺序展开新手照着走熟手直接看参数边界和问题清单。2. 环境准备与引用先让 Xceed.Document.NET.dll 跑起来2.1 先认清资源包的文件构成拿到资源包后别急着解压拖进项目先花两分钟确认里面到底有什么。我一般先建一个清单对照检查文件类型作用DocX 源码工程csproj sln备查和二次编译用能看 API 内部实现Xceed.Document.NET.dll核心程序集新命名空间代码里using Xceed.Document.NET;Xceed.Words.NET.dll兼容程序集旧命名空间转发遇到老示例代码时用Demo 解决方案sln cs可运行示例覆盖创建、替换、保存等常用操作说明文档文本/PDF版本差异、运行环境和依赖说明这里要提醒一句两个 DLL 同时拷进 bin 目录通常没问题但如果你的项目同时引用了新老两套命名空间的代码编译时容易出现「类型存在于两个程序集」的冲突。常规做法是只引用Xceed.Document.NET.dll只有当你手头的示例代码写着using Novacode;时才需要Xceed.Words.NET.dll。2.2 三种方式把 DLL 引进来第一种最简单Visual Studio 里右键「引用」→「添加引用」→「浏览」→ 指向 DLL 文件确定即可。第二种是用 NuGet但离线环境或者需要与资源包版本严格匹配时我一般不推荐 NuGet因为在线拉到的版本可能和 demo 里用到的不一致行为会有细微差别。第三种是命令行编译适合写自动化脚本的场景csc /target:exe /out:demo.exe ^ /reference:.\libs\Xceed.Document.NET.dll ^ /reference:.\libs\Xceed.Words.NET.dll ^ Program.cs/target:exe指定生成控制台程序/reference逐个声明要引用的程序集/out指定输出文件名。用这种方式时如果编译报「未能找到类型 X」先检查 reference 路径是否写对再检查两个 DLL 的引用顺序——依赖底层的程序集放前面。正常开发中我依然推荐 Visual Studio 引用命令行更适合 CI 环境。2.3 跑通第一个 demo创建文档并落盘资源包里的 demo 一般会演示完整流程但最好还是自己敲一遍核心逻辑印象更深using Xceed.Document.NET; using System; class Program { static void Main() { // Create 传入磁盘完整路径目录必须先存在 using (DocX doc DocX.Create(hello.docx)) { // InsertParagraph 创建新段落返回 Paragraph 对象 Paragraph title doc.InsertParagraph(报价单生成工具); title.FontSize(22).Color(Color.Blue).Bold(); title.Alignment Alignment.center; // 追加模式在当前段落尾部继续写 Paragraph body doc.InsertParagraph(这是一份由 DocX 生成的演示文档。); body.Append( 支持追加续写也支持整段替换。); body.Font(宋体).FontSize(12); doc.Save(); } } }这段逻辑很直白DocX.Create的入参是磁盘路径目录不存在会直接抛异常InsertParagraph返回Paragraph对象后面的FontSize、Color、Bold都是链式调用可以连续设置Append和InsertParagraph的区别在于前者不新建段落只在当前段落末尾追加文本。using包裹保证 Save 之前即使出现异常也不会在磁盘留下半截文件。2.4 命名空间冲突提前给 Font 和 Color 起别名跑完 demo 往自己项目里迁移时最常见的编译报错是Color和Font二义性——WinForms 和 WPF 里各有一套DocX 也有自己的。常规做法是加别名using Xceed.Document.NET; // 用别名把两个 Font 区分开避免引用混乱 using DocXFont Xceed.Document.NET.Font; using System.Drawing;这个文件头一加后续代码里写Font时不再有歧义。如果你同时用到System.Drawing.Color和 DocX 的Color同理给其中一个起别名。我一般习惯给 DocX 的类型加别名因为文档相关代码占比高写起来更顺手。3. 编辑 Word 文档的核心操作遍历、替换、表格与样式3.1 Load 现有文档从模板开始干活实际项目里很少从空白文档从头写更多是加载一个做好的 docx 模板再往里面填数据。加载方式如下using (DocX doc DocX.Load(template.docx)) { doc.ReplaceText({{客户名}}, 某公司); doc.ReplaceText({{金额}}, 12,800.00); doc.SaveAs(output.docx); }DocX.Load打开已有文件后续操作和新建文档完全一致。ReplaceText第一个参数是查找串第二个是替换串。这里有个关键点它会替换文档所有可见文本中匹配的内容包括页眉页脚和表格内的文本但默认不涉及域代码内部的文本。如果你用过 Word 通配符会发现它和 Word 的「查找替换」行为不太一致——它不认^p这类特殊符号换行需要配正则。3.2 段落操作InsertParagraph、Append、ReplaceText 的边界三种「写」操作各有适用场景InsertParagraph创建全新段落Append在当前段落末尾续写ReplaceText做全局或局部替换。光用doc.ReplaceText一把梭会踩坑——它对表格内部文本的覆盖范围在不同版本里表现不一致有的版本替换不到单元格里的段落。保险写法是定位到表格段落再替换using (DocX doc DocX.Load(quote.docx)) { // 遍历第一张表的所有行、所有列 for (int r 0; r doc.Tables[0].Rows.Count; r) { for (int c 0; c doc.Tables[0].Rows[r].Cells.Count; c) { doc.Tables[0].Rows[r].Cells[c].Paragraphs[0] .ReplaceText({{占位}}, 真实值); } } doc.Save(); }这段代码把doc.Tables[0]里的每个单元格取出来取它的第一个段落做替换。这样做虽然繁琐但可以确保命中。ReplaceText还有第四个参数传入RegexOptions.IgnoreCase之类的枚举可以控制匹配方式例如让匹配忽略大小写。注意Tables集合只包含文档顶层的表嵌套在单元格里的表格不在这个集合里遇到那种结构需要递归遍历。3.3 表格、图片与样式把模板做成能产数据的流水线表格是 Word 文档里最麻烦的部分DocX 的表格 API 设计得还算顺手using (DocX doc DocX.Create(report.docx)) { // 3 行 4 列行列数创建后基本固定 Table t doc.AddTable(3, 4); t.Design TableDesign.LightGridAccent1; // 预设隔行配色省手工样式 // 给表头写内容 t.Rows[0].Cells[0].Paragraphs[0].Append(序号); t.Rows[0].Cells[0].Width 120; // 设置内边框虚线、1 磅、灰色 t.SetBorder(TableBorderType.InsideH, new Border(BorderStyle.Dashed, 1, Color.Gray)); doc.InsertTable(t); // 插入图片16 表示缩放后的宽高比例 Image img doc.AddImage(logo.png); doc.InsertParagraph(项目徽标).AppendLine().InsertImage(img, 16f, 16f); }几个参数要说清楚AddTable(3, 4)创建 3 行 4 列之后不能直接改列数要加列得通过插入行的方式迂回t.Design是内置样式枚举几十种预设能省掉大部分手工格式设置SetBorder的第一个参数指定边框位置InsideH表示内部横线还有其他枚举管外侧框和内部竖线Border构造的四个参数分别是线型、线宽磅值、颜色。InsertImage的第二个参数是缩放宽高传null保持原始尺寸。3.4 页面布局属性转 PDF 前的最后一道闸很多时候模板里数据都对转 PDF 出来页面方向却是纵向、页边距不对这就是页面布局属性没设置。DocX 里这部分挂在PageLayout对象下using (DocX doc DocX.Create(print.docx)) { // 整篇文档统一设置横向 doc.PageLayout.PageOrientation PageOrientation.Landscape; doc.PageLayout.MarginLeft 50f; doc.PageLayout.MarginRight 50f; // 强制分页后面的内容从新页开始 doc.InsertSectionPageBreak(); doc.InsertParagraph(第二页内容); doc.Save(); }PageOrientation.Landscape切换横向MarginLeft单位是磅值50 磅约等于 1.76 厘米比 Word 默认的 3.17 厘米窄不少。注意PageLayout挂在Section级别如果文档有多个分节只设置doc.PageLayout只影响第一节后面的章节需要遍历doc.Sections逐个设置。InsertSectionPageBreak会创建新节新节不会自动继承上一节的页边距这就是分页后边距突然变掉的常见原因。4. Word 转 PDF 常见问题与避坑现象、原因、解决办法4.1 转换机制COM 与 LibreOffice 两条路DocX 套件本身只负责生成 docx转 PDF 需要外部引擎而且转换质量受渲染引擎影响很大。最常见的两条路一是装了 Office 的机器上用 COM 互操作导出二是服务端装 LibreOffice 走命令行转换。先看 COM 方案using Word Microsoft.Office.Interop.Word; string src C:\tmp\in.docx; string dst C:\tmp\out.pdf; Word.Application app new Word.Application { Visible false }; Word.Document wdoc app.Documents.Open(src, ReadOnly: true); wdoc.ExportAsFixedFormat(dst, Word.WdExportFormat.wdExportFormatPDF); wdoc.Close(); app.Quit();ExportAsFixedFormat是 Word 2010 以后提供的导出方法第二个参数传wdExportFormatPDF就输出 PDF。如果版式复杂或需要精确控制优化选项可以再传后面的参数比如嵌入字体、导出范围等但只传前两个最稳妥。COM 方案的释放顺序有玄学先关文档对象再 Quit 应用对象反过来容易残留 Word 进程第一次写的人基本都会翻车。另一条路是 LibreOffice 命令行soffice --headless --convert-to pdf:writer_pdf_Export --outdir /tmp/out /tmp/in.docx--headless表示无界面运行pdf:writer_pdf_Export是导出过滤器的完整名称不能省略冒号后面的部分有些版本省略后会生成空白 PDF。--outdir指定输出目录最后一个是源文件路径。LibreOffice 对 docx 的渲染和 Word 有细微差异最简单的一行文本都会有零点几毫米的偏差对版式要求苛刻的场景优先用 COM。4.2 中文字体变方框现象转换后的 PDF 里中文全部显示成方块或者被替换成了宋体避开坑。原因目标机器或渲染引擎缺少对应字体文本里指定的字体名在系统里找不到模板里同时设置了西文字体和东亚字体替换文本后中文全部落到东亚字体上而渲染引擎找不到这个东亚字体。解决生成文档时固定字体名不要用「微软雅黑」的英文注册名尽量用「宋体」「黑体」这类常见名在模板里把中西文字体统一设置一次避免双重字体配置转换前把 docx 在目标机器上打开检查一遍确认所有字符都能正常渲染。4.3 页眉页脚错位现象转出来的 PDF 页眉与正文重叠或者页码不是从 1 开始而是从某个中间数字续起。原因模板里存在多个分节分节后的页眉没有显式断开「链接到前一节」转换引擎对最后一节的渲染规则不一致页码域没有重新设置起始编号。解决生成代码里对所有分节都显式写一遍页眉内容宁可内容相同也逐节设置不要依赖继承页码需要重新编号时在分节处设置页码重新从 1 开始转换前用 Word 打开看一眼分节符位置确定分节数量后再写循环。4.4 批注、修订和邮件合并域被静默丢弃现象转换出的 PDF 里批注消失、修订标记不见了甚至模板里的{{占位符}}还在文档里。原因转换工具默认不输出批注和修订ReplaceText没有真正写入文档内容替换动作作用在缓存层保存时机不对。解决保存前调doc.UpdateFields()刷新所有域替换完成后重新Load一遍生成文件遍历段落和表格检查是否还有{{残留COM 导出时确认没有传「仅文档内容」之类的限制参数。4.5 避坑清单五条反向操作记录1表格内ReplaceText没生效。现象表格里的占位符原样留在 PDF 里原因doc.ReplaceText对表格内文本的覆盖范围因版本而异解决循环遍历doc.Tables[0].Rows[r].Cells[c].Paragraphs[0]逐段替换。2Word 进程残留导致内存炸。现象批量转换跑了几百个文件后系统进程列表里全是 Word 实例原因COM 对象没释放干净异常分支没有执行Quit解决不管正常还是异常路径都走try-finally释放必要时杀进程兜底。3中文字体变方框。现象Windows 上正常Linux 服务器转 PDF 中文全变方块原因服务器没安装中文字体解决在服务器上安装雅黑或文泉驿等中文字体或者把字体文件放进模板同目录注册。4转换出的 PDF 缺图片。现象docx 里图片正常PDF 里图片位置空白原因图片被插入到段落的非标准锚定位置转换引擎无法解析解决统一用paragraph.AppendLine().InsertImage(img, width, height)方式插入避免直接插入到表格单元格。5模板 docx 打开提示「文件损坏是否修复」。现象数据生成后 Word 弹修复窗口原因模板里手工编辑留下非法 XMLDocX 只是把内容原样保留解决先用 Word 另存一遍模板把非法结构清掉再拿干净模板做生成。5. 进阶技巧批量生成、自校验与版本收口5.1 批量替换 200 个模板变量的路径真实业务里变量往往不是两三个而是几十上百个直接一个个调ReplaceText会慢而且容易漏。我一般先预处理再统一替换重点在于排序static void ReplaceVariables(DocX doc, Dictionarystring, string vars) { // 长 key 优先避免 {{金额大写}} 被 {{金额}} 先替换 foreach (var kv in vars.OrderByDescending(v v.Key.Length)) { doc.ReplaceText(kv.Key, kv.Value); } }OrderByDescending是关键否则{{金额}}会把{{金额大写}}的{{吞掉一半替换出来内容残缺。替换完成后建议再跑一遍校验找到所有残留占位符并记录到日志方便定位哪条数据没带上。5.2 转 PDF 前自校验把文本榨出来比对批量场景下最怕「数据没填进去就转 PDF」所以我在生成后、转换前必做一步把文档里的文本全部提出来和数据库源数据做比对。重复造轮子不如直接复用 DocX 的遍历逻辑static string DumpText(DocX doc) { var sb new StringBuilder(); foreach (var p in doc.Paragraphs) sb.AppendLine(p.Text); foreach (var table in doc.Tables) foreach (var row in table.Rows) foreach (var cell in row.Cells) foreach (var p in cell.Paragraphs) sb.AppendLine(p.Text); return sb.ToString(); }这个方法把正文段落和所有表格单元格里的段落拼成纯文本再拿这份文本去和模板变量字典比对只要发现{{或}}就说明有漏替换。跑完校验再调转换命令能省掉大量返工时间。5.3 收尾版本、授权与可回滚备份资源包自带源码和 demo下载解压后开箱即用。但我建议你拿到手先做三件事把 DLL 的版本号记进项目说明不同版本的 API 行为差异很大升级前务必对比确认授权覆盖范围这类组件通常按开发授权算内网工具也得留好授权文件原始资源包单独存一份备份不放进 git 仓库里跟着项目版本走避免组件更新后无法回退。从那以后我每次接文档生成类需求都会先跑一遍 demo再花两分钟把 DLL 版本和模板字体写进说明文档这个习惯救过我两次一次是环境升级后组件换了渲染行为一次是换机器后字体变方框。希望帮到你。本文还有配套的精品资源点击获取