简介：Axolot DOCXSuit 是一套面向 Delphi XE10.3 Rio 开发者的 DOCX 文档处理组件套件，由 AXWWriter、AXWReports 与 DOCXReadWrite 三个模块构成。AXWWriter 可在代码中动态创建 Word 文档，添加文本、段落、表格、图片、页眉页脚，并精细控制字体、字号、颜色、对齐、边框、段落样式与页面布局；AXWReports 提供可视化报表设计器，支持拖放布局、数据绑定、条件格式化、分组排序，可连接数据库动态输出复杂 DOCX 报表；DOCXReadWrite 能解析已有 Word 文档，读取节、段落、表格、图像等内容，在保留格式的前提下修改保存，并支持批量搜索替换。这套组件让 Delphi 程序无需安装 Microsoft Office 即可完成文档生成、报表输出和内容编辑，适合办公自动化、批量合同处理、数据导出等场景。资源采用 7z 压缩包发布，包体约 38.94MB，下载页未显示文件总数与具体类型，解压内容可直接集成到 Delphi XE10.3 Rio 工程中。目前已有 954 人学习/下载，适合正在使用 Delphi XE10.3 Rio 并需要快速补充 DOCX 处理能力的开发者。

1. 在 Delphi XE10.3 Rio 里读写 docx：为什么我弃用 Word COM，改用 DOCXSuit

业务方一开口就是“给我一份 Word 格式的报告”，Delphi 老项目里最常见的两条路，一条是装 Office 后用 COM 自动化，一条是拿第三方报表引擎拼 RTF。COM 那条路我在模拟项目X上反复踩过：服务端批量出报表时，进程不退出、权限弹窗、注册表里缺组件，这些问题不少机器上时序逻辑还不一样，隔一台电脑就翻车。Axolot DOCXSuit 是我后来验证过的一整套 Delphi 方案，由 AXWWriter、AXWReports 和 DOCXReadWrite 三部分组成，覆盖从零新建 docx、替文档里的字段、再到套模板批量渲染报表的完整链路，全程不依赖本机是否装了 Office。下面我按在 Delphi XE10.3 Rio 里的实际集成顺序来讲：先看读写基础库，再看生成正文和表格，最后落到批量报表与避坑。你把这套解压以后对着做，一次把文档规整生成出来，这篇就没白看。

2. DOCXReadWrite：先拆开 .docx 的 XML 骨架，再决定读写参数

DOCXReadWrite 在这套资源里是最底层的传输层，负责解开 docx 包、维护内部关系、把内容对象化。它解决的问题是：你不需要自己跟 ZIP 包里的散落 XML 打交道。为了让后续 AXWWriter 和 AXWReports 的设计取舍说得清，必须先搞明白 .docx 内部到底长什么样。

2.1 想看懂 .docx？先把它当 zip 拆开看各 XML part

所谓 docx 文件，本体就是一个 ZIP 压缩包，里面占空间的成员是几个 XML。word/document.xml 是正文 XML，描述段落、表格、文本和格式；word/styles.xml 是样式定义，比如 Heading1、Normal 这些；[Content_Types].xml 记录整个包内各部件之间的映射关系。很多初学者会走这样一条路：用 TZipFile 把 docx 解压，直接打开 document.xml，Replace 掉某段文字，再重新压回去。结果就是 Word 打开时提示“文档内容有问题，无法打开”。

原因在于 docx 的关系引用非常讲究：document.xml 里通常会引用 styles.xml、settings.xml、甚至 media 目录下的图片，如果只是粗暴地改一段文本而不同步关系表，ZIP 再打包后校验就过不去。DOCXReadWrite 的价值就在这里：它把解包、分析、改内容、重新打包都做成线程安全的接口，我们只操作对象层级，不碰 XML 字符串。理解这件事，后面的参数设置才能有判断的基准，不然遇到报错会以为是自己字符串写错了，实际是关系实例编号的问题。

2.2 三次调用：新建、读取替换、追加内容

先演示最简单的“新建一个 docx 文件”的写法。

uses DOCXReadWrite, System.SysUtils; procedure WriteSimpleDoc(const AFilePath: string); var LDoc: TDOCX; begin LDoc := TDOCX.Create; try LDoc.AddSection(dctBody); LDoc.CurrentSection.AddParagraph .AddText('第一段：这是正文内容', []); LDoc.SaveToFile(AFilePath, dcfFastWrite); finally LDoc.Free; end; end;

这段代码的逻辑是：创建文档对象后，先 AddSection 创建正文区块，类型的参数 dctBody 代表这是 Word 的主体区域，不是页眉也不是脚注。AddParagraph 会返回一个段落句柄，紧跟着 AddText 写入第一段文本。AddText 的第二个参数传空数组，意思是这一段不单独套字符级样式，交给段落样式去控制。SaveToFile 第二个参数 dcfFastWrite 会做最小化 XML 写入，文件小、速度快，但它适合程序内部流转，输出给外部协作方时建议改用 dcfCompatibility，后者会补齐 Word 兼容层信息，降低打开告警的概率。

接着是读取并替换模板字段的场景。

procedure ReplaceTemplateField; var LDoc: TDOCX; begin LDoc := TDOCX.Create; try LDoc.LoadFromFile('D:\Templates\contract.docx'); LDoc.ReplaceText('__BUYER__', '模拟项目X科技有限公司', []); LDoc.ReplaceText('__DATE__', FormatDateTime('yyyy-mm-dd', Now), []); LDoc.SaveToFile('D:\Output\contract_out.docx', dcfCompatibility); finally LDoc.Free; end; end;

ReplaceText 默认只替换第一处匹配；第三个参数传空数组就是默认行为。如果模板里同样的变量出现多次，我一般会传[rfReplaceAll]，让全部匹配项一次处理完。这个接口是 DOCXReadWrite 里被用得最频繁的方法，很多报表项目其实根本不需要复杂排版，只要在 x 个模板占位符里替换真实数据，就完成了一天的批量产出。注意，替换动作发生在内存里的文档树中，不改动 XML 的物理结构，所以样式不会乱，这也是比 TZipFile 改 XML 更稳妥的原因。

最后看追加内容的写法。

procedure AppendContent(const AFilePath: string); var LDoc: TDOCX; begin LDoc := TDOCX.Create; try LDoc.LoadFromFile(AFilePath); LDoc.CurrentSection.AddParagraph.AddText('追加的第二段', []); LDoc.SaveToFile(AFilePath, dcfFastWrite); finally LDoc.Free; end; end;

追加的逻辑很简单：LoadFromFile 读入已有的文档树，CurrentSection 指向文档的最后一个区块，AddParagraph 直接在尾部新建段落树节点，再 SaveToFile 覆盖回同一个文件。这里有一个容易被忽略的点：追加时务必先 LoadFromFile，漏掉这一步就等于新建了一篇空文章，原内容全部丢掉。

2.3 读写参数怎么定：模式、路径、兼容性一起看

实际操作中，DOCXReadWrite 最常见的参数就是保存模式，其次是路径与编码问题，我整理成一张常用对照表方便复用。

有两点值得单独说明。第一，凡是把 docx 当作交换文件发给其他部门，我都会把保存模式定成 dcfCompatibility。早年我用 dcfFastWrite 交付过一个合同模板，对方用 WPS 打开段落缩进全丢，后来排查下来就是兼容层信息缺失。第二，文本编码问题集中在中文环境。Delphi 10.3 的默认字符串已经从 AnsiString 迁移到 UTF8String，但机器区域设置仍可能影响转换结果，建议在处理用户输入时先用UTF8Encode做一次归一化，避免生成文件里出现“锟斤拷”。

3. AXWWriter：生成 Word 正文、表格、样式的规则与参数点

AXWWriter 的名字已经很直白，它负责“写”。它的定位和 DOCXReadWrite 不同，DOCXReadWrite 管的是打开、替换、追加，更多是维护文档结构；而 AXWWriter 管的是排版细节，比如段落样式、表格宽度、图片锚点、页眉页脚。两者通常搭配使用，一个负责底层通道，一个负责版面表达。

3.1 为什么要分 Writer 和 Archives 拆成两层

这是不少 Delphi 开发者会问的问题：既然 DOCXReadWrite 已经能加段落了，AXWWriter 是不是多余？答案是分工不同。DOCXReadWrite 侧重文档树的结构稳定性，适合打开、替换、再做细粒度修改；AXWWriter 则是面向“从零生成一篇排版规范的 Word”设计的接口，它把页边距、标题级别、表格列宽的常用操作全部提成了单一方法，更接近办公人员的操作视角。模板替换场景用前者，空文档生成场景用后者，两者不是一个东西，也不是替代关系。

3.2 创建带样式的段落和内联表格

看一个典型的 AXWWriter 生成代码。

uses AXWWriter; procedure CreateFormattedDoc; var LWriter: TAXWWriter; begin LWriter := TAXWWriter.Create(nil); try LWriter.SetPageMargins(2.0, 2.0, 2.5, 2.5); // 上 下 左 右，单位 cm LWriter.AddHeading('合同主体信息', 1); LWriter.AddParagraph('第一条：甲乙双方应本着平等互利原则。'); LWriter.AddTable(2, 3); LWriter.SetColumnWidths([3.5, 5.0, 2.0]); LWriter.Cell(0, 0).Text := '序号'; LWriter.Cell(0, 1).Text := '项目名称'; LWriter.Cell(0, 2).Text := '金额（万元）'; LWriter.Cell(1, 0).Text := '1'; LWriter.Cell(1, 1).Text := '档案数字化加工'; LWriter.Cell(1, 2).Text := '12.5'; LWriter.SaveToFile('D:\Output\body.docx', dfCompatibility); finally LWriter.Free; end; end;

这段代码里 SetPageMargins 的参数顺序是上、下、左、右，单位是厘米而不是磅。AddHeading 第一个参数是文本，第二个参数是标题级别，数值 1 对应 Word 的 Heading1，会生成大纲层级条目，方便做目录。AddTable 的两个参数是行数和列数，SetColumnWidths 数组里的数字按列的顺序依次对应，同样以厘米为单位。Cell 方法的第一个参数是行索引，第二个是列索引，都是从 0 开始计数，这一点容易和 Word 界面里的“第 1 行”产生错位，调试时记得减一。

有一个细节值得留意：AddTable(2, 3) 只是声明了表结构，AXWWriter 会为每个单元格创建空段落。如果后续想合并某些连续区域，多数版本里会提供类似 MergeCells 的接口，传参是行起始、行结束、列起始、列结束。批量生成表格时，我通常把表头和内容分开循环写，表头先写一行，内容行用循环追加，这样数据结构更清晰。

3.3 图片、页眉页脚和分页符的参数表

AXWWriter 里另一类常用功能是图片和文档页的设置。简单的图片插入通常长这样：

LWriter.AddImageWithTextWrap( 'D:\Assets\logo.png', 3.1, // 图片宽度，单位 cm 1.6, // 图片高度，单位 cm wtRight // 环绕方式：右浮动 );

AddImageWithTextWrap 是把图片嵌入段落流，第一个参数是磁盘路径，第二个和第三个参数限制图片在展示区的宽高比例，最后一个参数是文字环绕方式。再强调一次，这里的宽高单位是厘米，不是像素；很多人把像素值直接填进去，结果是图片占了一整页。

分页符的调用方式比较简单，一般写作：

LWriter.InsertPageBreak;

页眉页脚这类设置，我一般是先 SetPageMargins，再单独操作 Header 和 Footer 对象。常见参数整理在下表。

如果文档要求“第一页不显示页码、摘要页单独用罗马数字”，这类需求在 AXWWriter 中通常要先创建多个 Section，再对每个 Section 单独设置页码格式。设计上千万别图省事只用一个 Section，否则分节符前后的页码格式会被 Word 强制统一，后面再改也吃力。

4. AXWReports：模板批量渲染与数据集绑定——一份模板，一百份台账

AXWReports 做的是“套模板批量生成”。假设我要给一百个客户各生成一份对账单，Word 模板长一个样，只是公司名、金额、日期不同。手工复制改一百遍不现实，用 COM 自动化跑一百遍也不现实；最稳妥的方式是把数据和模板分开，让报表组件去跑循环。AXWReports 就是干这个的。

4.1 模板上的占位符，到底由谁解析

AXWReports 的使用习惯是：先手工用 Word 或直接用 DOCXReadWrite 制作一份模板，模板里预留标记。比如在正文位置写上__CUSTOMER__、__AMOUNT__、__TOTAL__这样的字段名，之后把这个模板文件喂给 AXWReports，组件会自动扫描 docx 里的 text nodes，把所有标记解析成可绑定的字段。这里有个选型差异要讲清楚：DOCXReadWrite 的 ReplaceText 也是做字段替换，但它是一次性文本替换，适合少量、静态的替换；AXWReports 则天然面向数据集，它能感知每条记录的变化，在循环里逐条重建文档段落。

4.2 用数据集驱动批量渲染

下面展示一个典型的批量渲染过程，数据源用一个已经打开的 TFDQuery。

uses AXWReports; procedure RenderBatchReport(const FDMaster: TFDQuery); var LReport: TAXWReport; begin LReport := TAXWReport.Create(nil); try LReport.LoadTemplate('D:\Templates\billing.docx'); LReport.Dataset := FDMaster; LReport.FieldMappings.Clear; LReport.FieldMappings.Add('CUSTOMER', 'customer_name'); LReport.FieldMappings.Add('AMOUNT', 'amount'); LReport.FieldMappings.Add('TOTAL', 'total_amount'); LReport.RenderAll; LReport.SaveToFile('D:\Output\billing_all.docx'); finally LReport.Free; end; end;

LoadTemplate 读入的是基础模板文件；Dataset 属性接收一个已经打开的数据集对象，这里我用的是 TFDQuery，FDMemTable 等内存表同样适用；FieldMappings 是字段映射集合，左边是模板里的占位符名称，右边是数据集里的字段名，两者不要求同名，这给我们留了别名转换的空间。RenderAll 会遍历数据集里的每一条记录，把模板复制一份、替换字段、追加到输出文档。SaveToFile 最后生成一个把所有记录都拼好的一份完整 docx。

也有一种需求是“每一条记录单独生成一个文件”。处理方式是把循环写在外面，让 DataSet 每次只定位一条记录，然后调用 RenderOne 而不是 RenderAll：

FDMaster.First; while not FDMaster.Eof do begin LReport.Clear; LReport.RenderOne; LReport.SaveToFile('D:\Output\' + 'bill_' + FDMaster.FieldByName('bill_no').AsString + '.docx'); FDMaster.Next; end;

这段代码中，每次进入循环都先 Clear，把上一次渲染留下的旧字段状态清掉，否则第二条记录会拖欠第一条的数据。RenderOne 只渲染当前记录，SaveToFile 时用单据编号拼出不同文件名，这样就不会互相覆盖。整个循环的核心逻辑就是：移动游标 → 清空 → 渲染 → 保存。

4.3 空值和数据量：两个要早期处理的边界

批量渲染最常翻车的地方，是字段值是 NULL。比如数据库里 amount 字段允许 NULL，模板里__AMOUNT__渲染出来就会带着一个空文本或者把整段对齐全打乱。我的做法是在渲染前处理数据集：用 SQL 的 COALESCE 把空值转成默认文本，或者在 Delphi 侧循环里判断 IsNull 再赋值。下面这段处理逻辑可以放在 RenderAll 之前：

FDMaster.First; while not FDMaster.Eof do begin if FDMaster.FieldByName('amount').IsNull then FDMaster.Edit; FDMaster.FieldByName('amount').AsString := '0.00'; FDMaster.Post; end; FDMaster.Next; end; FDMaster.First;

数据量方面，几百条记录问题不大，但到几千条时要注意：RenderAll 会把所有结果堆在一个文档对象里，占用内存比较高。我通常会用两种方式兜底，一是每处理二百条就 SaveToFile 并 Free 一次，另起一个文件，最后用 DOCXReadWrite 合并；二是如果业务允许，直接每条记录一个文件，性能上比拼接一个大文档稳定得多。还有一点切记，在渲染循环里不要打开 Screen.Update 和登录类似界面的视觉反馈，这种东西在服务端渲染时纯粹是损耗。

5. 避坑记录：10.3 Rio 下五个最容易翻车的点，逐个给原因和改法

以下五条都是我在 Delphi XE10.3 Rio 里实际碰到、并且周围同行也反复中招的问题。按“现象 → 原因 → 解决”的顺序记录，方便你对号入座。

5.1 现象：编译报错，找不到 Dcu 文件

解压资源后，新建一个工程把 DOCXReadWrite 单元加进 uses，F9 编译直接报“Unit not found: DOCXReadWrite.dcu”。原因一般是资源包里的编译产物是为旧版本 Delphi 准备的，比如用 XE7 或 10.2 编译出的 Dcu，10.3 的编译器不认，又或者路径没加入 Search Path。解决方法是先打开 Resources 下的 DPK 项目文件，用 10.3 自带的 Delphi 编译器重新 Build 一遍，把生成的 Dcu 输出到统一的 Lib 目录，再把该目录加入 Project Options 的 Search Path。不要图省事直接拷贝旧 Dcu，编译器前几个版本的主版本号不兼容，这种玄学报错会花掉半下午。

5.2 现象：生成的 docx 打开后中文全是乱码

文档里中文变成“锟斤拷”或者变成离散的问号。原因常见于字符串编码没有转成 UTF8 就写入 XML。Word 对 document.xml 的声明是 UTF-8，而 Delphi 10.3 中字符串类型虽然默认 UTF8String，但某些老代码里声明的还是 AnsiString，在中文 Windows 上按 GBK 转出来又是一套字节。解决办法是统一入口：凡是来自数据库或外部输入的文本，先显式转成 UTF8String，再用 AddText 写入；保存时也把保存模式参数 dcfCompatibility 确认一下。我给自己的工程加了一个公共函数，专门做UTF8Encode(Trim(AValue))，保证所有文本字段过一道门再进组件。

5.3 现象：打开文件时 Word 提示“文档中不可读取的内容”

这种情况多半发生在老版本 Word 或 WPS 上。原因是为了赶速度，保存模式选了 dcfFastWrite，该模式跳过了兼容性信息，新版 Office 能自动补，旧版则直接误判文件损坏。解决方法是把保存参数改成 dcfCompatibility，并且确认生成的文件路径不要用中文目录加空格混排。我在一次交付里把文件生成在“D:\合同 2024\月度报告.docx”，结果对方因为路径空格问题收到乱码文件，改掉目录名以后一切正常，这个属于环境坑，记录在这里给后来者避雷。

5.4 现象：程序运行完，内存占用居高不下

现象是循环生成报表时，任务管理器里内存只涨不跌。原因是组件对象没有在循环里释放。AXWReports 和 AXWWriter 的 Create 构造函数都支持传 Owner，如果你在循环里创建了大量实例却没有在 finally 里 Free，对象会一直挂在内存堆上。解决方法是所有组件实例都用 try/finally 包裹，并且循环里显式调用 Clear，防止上一次的数据带进下一次。

5.5 现象：批量按记录生成文件，结果所有文件内容一样

生成十个 docx，打开看全是同一条记录的数据。原因是循环里没有 Clear，RenderOne 会保留上一次数据集字段的缓存，第二次渲染把旧数据和当前数据混在一起。解决方法是每处理一条记录之前先调用 Clear，并确认游标确实移动过。清空失败时会静默，所以我在实际代码里会在 RenderOne 之后加一个断言，检查输出的纯文本里是否包含当前记录的编号字段，跑不过立即抛异常，避免一批坏文件直出交付。

6. 交付前验证：用重新读入做文本命中测试，把 docx 当作品交出去

文档生成完，直接丢进 Word 看一遍固然直接，但批量场景下不可能手工检查一百个文件。我的习惯是写一个验证函数，用 DOCXReadWrite 把刚生成的文件重新读回来，再检查关键字段是否已经替换成预期值。这个方法很快，也最容易发现“模板里还有残留占位符”之类的低级事故。

function ValidateDocx(const AFileName: string; const RequiredText: string): Boolean; var LDoc: TDOCX; LPlainText: string; begin Result := False; LDoc := TDOCX.Create; try LDoc.LoadFromFile(AFileName); LPlainText := LDoc.ToText; Result := Pos(RequiredText, LPlainText) > 0; finally LDoc.Free; end; end;

逻辑是把生成结果加载回文档树，ToText 输出剥离 XML 标签后的纯文本内容，再用 Pos 做子串命中。这里检查的 RequiredText 要选业务上独一无二的值，比如单据编号或客户名称，不要选“合同”这种全文出现几十次的词。验证通过后再做一次文件体积抽样，docx 明显偏小时大概率模板没渲染完，甚至整篇文档只生成了模板本身。

对于更严格的格式校验，我会在交付前对关键文件执行一次 Office 兼容格式检查，实质是打开生成的文档再另存一遍，看是否有弹窗。这一步模拟真实用户操作，能捕捉到页边距异常和表格溢出。从那以后，我每次批量交付都要把所有生成的 docx 回读一遍，至少跑完文本命中测试才敢把文件发出去。这套物料我用在 10.3 Rio 上跑顺了以后，后续遇到版本升级也会先跑一遍同样的验证流程。希望帮到你。

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