简介：Axolot DOCXSuit 是面向 Delphi XE10.3 Rio 开发者的 DOCX 文档处理组件套件，适合需要在桌面应用中集成 Word 文档生成、报表设计与文件读写能力的中高级开发者，可摆脱对 Microsoft Office 的依赖。套件由三部分组成：AXWWriter 负责动态创建与编辑 DOCX，支持文本、表格、图片、页眉页脚及字体、边框、页面布局等格式设置；AXWReports 提供可视化报表设计器，支持数据绑定、条件格式化、分组排序与打印输出；DOCXReadWrite 用于解析、修改并回写既有文档，可批量搜索替换或统一调整格式。压缩包为 7z 格式，体积约 38.94MB，上游未提供文件明细，具体文件构成以实际解压为准。该资源已有 955 人浏览学习，读者可从中获得一套可直接融入 Delphi 工程的文档处理组件，减少底层 OOXML 格式研究成本，快速实现文档生成、数据报表与批量文档维护等业务功能。
1. Delphi XE10.3 Rio 装 DOCX 组件：先别急着解压，版本对不上全白搭
上周帮一个做报表系统的朋友收拾环境，他 Delphi XE10.3 Rio 里装了个来路不明的 DOCX 控件包，编译能过，一运行就报类找不到，折腾一下午。这类事在 Delphi 圈太常见了——第三方组件包对 IDE 版本、编译目标、运行时包的要求卡得很死，尤其像 Axolot DOCXSuit 这种同时带 AXWWriter、AXWReports 和 DOCXReadWrite 三块功能的套件，装错一步后面全是玄学。这篇记录的是我在 Rio 上把这套 7z 包从解压到跑通 Word 读写与报表导出的完整过程，适合正在给老项目补文档导出能力、又不想换 IDE 的开发者。装之前先把版本、路径、编译目标三件事对齐，比装完再救省事得多。
2. 装前环境盘点：Rio 的包路径与编译目标先对齐
Delphi 的组件安装翻车，八成不是包本身有问题，而是环境没盘清楚。Axolot DOCXSuit 这套东西本质是若干.pas源文件加设计期包，它依赖 VCL、RTL 里几个基础单元，还要跟 IDE 的库路径、BPL 输出目录对上。Rio 这个版本比较特殊，它同时支持 Win32 和 Win64 编译，但设计期包只能装在 Win32 下，这点如果没意识到，后面注册组件时会一直提示找不到包。
2.1 确认 IDE 版本与更新包
先确认你手上的是 10.3 Rio 的哪个更新级别。Rio 有 10.3.0、10.3.1、10.3.2、10.3.3 几个版本，组件包如果按 10.3.3 编译，拿到 10.3.0 上大概率报Unit not found或者接口不匹配。查看方式很简单，打开 IDE，Help → About 里能看到完整版本号。我一般会把这个号记在便签上，后面选包、改路径都要用。
# 在安装目录下确认版本文件，比 About 更准 # 默认路径类似 C:\Program Files (x86)\Embarcadero\Studio\20.0 type "C:\Program Files (x86)\Embarcadero\Studio\20.0\bin\bds.exe" >nul 2>&1 # 20.0 对应 10.3 Rio 系列，20.0 内部小版本看 source 目录下的 version.inc上面这段只是确认安装根目录存在，20.0是 Rio 的 Studio 版本号，不同更新包这个号不变，但version.inc里的CompilerVersion会略有差异。真正要盯的是 IDE 里 Library 路径指向的$(BDS)是否解析到你实际安装的那个目录，很多人机器上装过两个版本，环境变量指错了自己都不知道。
2.2 库路径与 BPL 输出目录
组件包能不能被 IDE 找到，取决于 Library Path 里有没有源文件目录，以及设计期包的 BPL 有没有输出到 IDE 能加载的位置。我一般不去动全局的 Library Path，而是在项目级或者 IDE 的搜索路径里追加，避免污染其他项目。
打开 Tools → Options → Language → Delphi → Library，重点看两处：一是Library path里有没有你解压出来的Source目录；二是Package output directory和DCP output directory，默认在C:\Users\Public\Documents\Embarcadero\Studio\20.0\Bpl和Dcp。设计期包编译后必须落到 Bpl 目录，否则 Install 时会提示找不到.bpl。
| 配置项 | 建议值 | 说明 |
|---|---|---|
| Library path | 解压目录\Source | 让编译器找到 pas 源文件 |
| Package output directory | 公共文档\Studio\20.0\Bpl | 设计期包输出位置 |
| DCP output directory | 公共文档\Studio\20.0\Dcp | 编译中间文件 |
| 编译目标 | Win32（设计期） | 设计期包只能 32 位 |
这张表看着简单，但第二行和第三行的路径如果被改到用户目录下，多用户机器上换账户就加载不了包，这是血泪经验。公共文档目录是 Rio 默认认的位置，别自作聪明改到项目里。
2.3 解压 7z 包的正确姿势
7z 包解压本身没难度，坑在于路径里带空格和中文。Delphi 的编译器对含空格路径的容忍度时好时坏，尤其设计期包注册时读注册表路径，空格容易截断。我一般解压到D:\Components\AxolotDOCX\这种纯英文短路径下，别放在桌面或者「下载」目录里。
# 用 7-Zip 命令行解压，指定输出目录，避免中文路径 "C:\Program Files\7-Zip\7z.exe" x "Axolot DOCXSuit for Delphi XE10.3 Rio.7z" -o"D:\Components\AxolotDOCX\" -yx是保留目录结构解压，-o后面紧跟输出目录不能有空格，-y表示全部覆盖不询问。解压完先别急着打开工程，进目录看一眼结构，通常会有Source、Packages、Demos几个子目录，Packages下按 IDE 版本分文件夹，认准XE10.3或Rio字样的那个。
3. 安装设计期包：从编译到注册的完整链路
环境盘清楚之后，安装本身其实就三步：编译运行期包、编译设计期包、注册组件。但每一步都有细节，顺序错了或者编译目标选错，后面就得重来。Axolot DOCXSuit 把功能拆成 AXWWriter（文档写入）、AXWReports（报表导出）和 DOCXReadWrite（底层读写）三块，包文件也对应分开，装的时候要按依赖顺序来。
3.1 先编译运行期包
运行期包（Runtime Package）是设计期包和最终程序都依赖的基础，必须先编。在Packages目录下找到运行期包工程，通常是.dpk文件，名字里带Runtime或者RTP。用 IDE 打开后，在 Project Manager 里把编译目标切到 Win32，然后 Build。
// 运行期包工程里常见的 requires 子句，确认依赖的 RTL 包版本对得上 requires rtl, vcl, vclx; // 如果这里报找不到 vclx，说明 IDE 的库路径没配全，回 2.2 检查requires里列的是这个包依赖的其他包，rtl、vcl是 Rio 自带的，vclx如果报缺失，多半是安装时没勾选对应组件或者库路径被改过。编译成功后，.bpl会输出到 2.2 里配的 Bpl 目录，.dcp落到 Dcp 目录。这一步不要跳过直接去编设计期包，否则设计期包会报找不到运行期包的接口。
3.2 编译并注册设计期包
设计期包（Design Package）负责把组件注册到 IDE 的工具面板上，它requires运行期包。打开对应的.dpk，同样切 Win32，Build 之后右键工程选 Install。如果 Build 成功但 Install 报错，通常是 Bpl 目录里没有刚编出来的运行期包，或者 IDE 加载了旧版本的包。
// 设计期包的 register 单元里大致长这样，注册组件到面板 procedure Register; begin RegisterComponents('Axolot DOCX', [TAXWWriter, TAXWReport, TAXWDOCXReader]); end;RegisterComponents第一个参数是面板页签名字，装完在工具面板上会多出一个Axolot DOCX页。如果 Install 之后面板没出现，先看 IDE 的 Install Packages 列表里这个包是否勾选，再检查是不是装到了另一个 IDE 实例上——机器上装多个 Delphi 版本时，包是分版本注册的，别装错地方。
3.3 三个功能模块的依赖顺序
这套件里 DOCXReadWrite 是底层，AXWWriter 和 AXWReports 建在它上面。如果只装 Writer 不装 ReadWrite，编译时能过但运行时读文档会缺单元。我一般三个包全装，顺序是 ReadWrite → Writer → Reports，每个装完都 Build 一次确认没连锁报错。
提示：装完一个包就重启一次 IDE 不是必须的，但装完三个之后重启一次能避免面板缓存不刷新。Rio 的包缓存有时候很固执，不重启看不到新组件。
装完在工具面板拖一个TAXWWriter到窗体上，如果能放上去且 Object Inspector 里属性正常显示，说明注册链路通了。这一步别急着写代码，先把「能拖能编」确认了，再往下配参数。
4. 配置与首个 DOCX 读写验证：参数别照抄默认值
组件装上只是能拖，真正跑通还得配几个关键参数，尤其是文档路径、字体回退和报表导出的页面设置。Axolot 这套件的默认值偏保守，直接拿来用在小文件上没问题，一旦文档带图片或者表格跨页，默认配置就容易出空白页或者字体乱码。
4.1 文档路径与临时目录
DOCXReadWrite 在读写时会在临时目录生成中间文件，默认走系统%TEMP%。如果临时目录所在盘空间紧张，或者路径里有中文，读写大文档时可能失败。我一般显式指定一个临时目录，放在项目输出目录旁边。
var Doc: TAXWDOCXReader; begin Doc := TAXWDOCXReader.Create(nil); try // 显式指定临时目录，避免系统 TEMP 路径含中文或空间不足 Doc.TempPath := 'D:\Work\Temp\Docx\'; Doc.FileName := 'D:\Work\Input\report.docx'; Doc.Open; // 读取段落数做基本校验 ShowMessage(IntToStr(Doc.ParagraphCount)); finally Doc.Free; end; end;TempPath末尾要带反斜杠，不带的话拼接出来的路径会少一个分隔符，这是很多人第一次用会踩的坑。FileName指向的文档最好先用 Word 另存为一次，排除文档本身损坏的可能。ParagraphCount只是验证读取链路，能读出非零值说明底层解析没问题。
4.2 字体回退与中文支持
DOCX 里指定的字体如果本机没装，Axolot 默认会回退到系统默认字体，中文环境下这个回退经常变成宋体或者直接方框。解决办法是在 Writer 上显式设置回退字体链。
var W: TAXWWriter; begin W := TAXWWriter.Create(nil); try W.FontName := 'Microsoft YaHei'; // 回退链：主字体缺失时依次尝试 W.FallbackFonts.Add('SimSun'); W.FallbackFonts.Add('Arial'); W.BeginDocument; W.AddParagraph('测试中文段落'); W.SaveToFile('D:\Work\Output\test.docx'); finally W.Free; end; end;FontName设成雅黑是因为大部分 Windows 机器都有，FallbackFonts是字符串列表，按顺序尝试。这里要注意，回退只影响显示和导出时的字体替换，不会改原文档里记录的字体名，所以拿 Word 打开时看到的还是原字体，只是渲染时替换了。
4.3 报表导出的页面参数
AXWReports 导出时页面大小、边距、方向这几个参数如果沿用默认，A4 纵向在宽表格场景下会被截断。我一般按内容宽度动态设，或者至少把边距调小。
| 参数 | 默认值 | 建议值 | 场景 |
|---|---|---|---|
| PageWidth | 210mm | 297mm | 宽表格横向 |
| MarginLeft/Right | 25mm | 15mm | 内容多时压缩 |
| Orientation | Portrait | Landscape | 列数超过 6 列 |
| FitToWidth | False | True | 自动缩放适配 |
FitToWidth打开后，超宽内容会按比例缩到一页宽，代价是字号变小，适合报表类导出。如果对字号有硬要求，就改 Orientation 而不是开缩放。
5. 避坑与排查：装完不跑、跑了报错的几种典型
这套件在 Rio 上的问题集中在包加载和运行时依赖两块，下面几条是我和朋友实际遇到过的，按「现象 → 原因 → 解决」记下来，遇到类似情况先对照排查。
5.1 现象：Install 后工具面板没有 Axolot 页
原因多半是设计期包装到了另一个 IDE 实例，或者 Bpl 目录里运行期包版本不对。Rio 的包注册信息写在注册表HKCU\Software\Embarcadero\BDS\20.0\Known Packages下，装错版本时这里指向的路径是旧的。
解决：打开 Component → Install Packages，看列表里有没有这个包且勾选；没有就 Add 一次，路径指向刚编出来的.bpl。如果 Add 时报「不是有效的包」，回 3.1 确认运行期包和设计期包的编译目标都是 Win32。
5.2 现象：编译报 Unit 'AXWDOCXReadWrite' not found
原因是 Library Path 里没有 Source 目录，或者解压路径带空格导致路径解析截断。Delphi 的搜索路径对空格的处理在 Rio 上不算稳。
解决：把 Source 目录加到项目搜索路径，路径用短英文目录；如果已经加了还报，检查是不是加到了 Win64 的路径下而当前编译目标是 Win32，两个目标的路径是分开配的。
5.3 现象：运行时读文档抛「Invalid DOCX format」
原因是文档本身是旧版.doc改了扩展名，或者文档加密。Axolot 这套件只认标准 OOXML 的 docx，不处理 doc 和加密文档。
解决：用 Word 打开另存为 docx，确认没有密码保护；如果是批量场景，先在入口处做扩展名和文件头校验，别让非 docx 文件进到读取逻辑里。
5.4 现象：导出报表中文变问号
原因是导出时用的字体不支持中文，或者编码设置没跟上。AXWReports 默认按系统 ANSI 处理文本，跨机器时容易出问题。
解决：显式设FontName为中文可用字体，并在导出前确认Encoding相关属性是 UTF-8 或与目标一致。这条在 4.2 里已经配过，导出模块要单独再设一次，两个模块的字体配置不共享。
5.5 现象：装完能编，换机器部署报缺 BPL
原因是设计期包和运行期包混在一起部署了。最终程序只需要运行期包对应的 DLL 或静态链接，设计期包不该进部署包。
解决：部署时只带运行期依赖，或者在项目里改成静态链接（不勾选 Build with runtime packages），把运行期代码编进 exe。静态链接体积大一点，但省去部署时找 BPL 的麻烦，小工具类项目我一般直接静态链接。
6. 装完怎么验证跑通：三个动作确认环境真的可用
装完组件、配完参数，最后一步是验证。我不太信「能编译就算装好」这种判断，编译过但运行时缺依赖的情况太多了。下面三个动作按从轻到重排，全过一遍基本能确认这套环境在 Rio 上是真能用的。
6.1 动作一：空窗体拖控件并编译
新建一个 VCL Forms Application，从Axolot DOCX页拖一个TAXWWriter和一个TAXWDOCXReader到窗体上，不改任何属性直接 Build。这一步验证的是设计期注册和运行期包链接是否都正常。如果 Build 报缺单元，回 5.2；如果拖不上，回 5.1。
6.2 动作二：跑一个最小读写闭环
在窗体上加一个按钮，写一段「生成 docx → 读回段落数 → 比对」的代码，跑通说明读写链路完整。
procedure TForm1.Button1Click(Sender: TObject); var W: TAXWWriter; R: TAXWDOCXReader; Expected, Actual: Integer; begin Expected := 3; W := TAXWWriter.Create(nil); try W.BeginDocument; W.AddParagraph('第一段'); W.AddParagraph('第二段'); W.AddParagraph('第三段'); W.SaveToFile('D:\Work\Output\verify.docx'); finally W.Free; end; R := TAXWDOCXReader.Create(nil); try R.FileName := 'D:\Work\Output\verify.docx'; R.Open; Actual := R.ParagraphCount; finally R.Free; end; if Actual = Expected then ShowMessage('读写闭环通过') else ShowMessageFmt('段落数不符：期望 %d，实际 %d', [Expected, Actual]); end;这段代码先写后读，用段落数做比对，是最小可信的闭环。Expected写死 3 是因为我们刚写了三段，如果读回来不是 3，要么写的时候丢了段落，要么读的时候解析有问题，两种情况都值得停下来查。跑通之后再用真实业务文档替换verify.docx试一次，真实文档带表格和图片，能暴露最小用例覆盖不到的问题。
6.3 动作三：换一台干净机器部署验证
这一步最容易被跳过，但恰恰最能暴露问题。把编译好的 exe 拷到一台没装 Delphi、没装这套组件的机器上跑，如果报缺 DLL 或 BPL，说明部署方式选错了。静态链接的项目这一步基本能过，动态链接的就要把运行期 BPL 一起带上，并确认目标机器上的路径能被找到。
| 验证动作 | 通过标准 | 失败先查 |
|---|---|---|
| 拖控件编译 | Build 无错，面板有组件 | 包注册、库路径 |
| 读写闭环 | 段落数一致 | 临时目录、文档格式 |
| 干净机器部署 | exe 直接运行不报缺库 | 静态/动态链接选择 |
三个动作全过，这套 DOCXSuit 在 Rio 上就算真正装好了。从那以后我每次装第三方组件包，都强制走一遍「拖控件 → 最小闭环 → 干净机器」这三步，不再信「编译过了就行」这种判断——吃过一次换机器演示前夜发现缺 BPL 的亏，后悔药没处买。希望帮到你。
本文还有配套的精品资源，点击获取
