簡介這是一份面向 Delphi 開發(fā)者的 Axolot DOCXSuit 組件套件適配 XE10.3 Rio用于在應(yīng)用程序中直接創(chuàng)建、編輯與讀取 DOCX 文檔擺脫對微軟 Office 的依賴。套件由三部分組成AXWWriter 負(fù)責(zé)動態(tài)生成 Word 文檔可添加文本、段落、表格、圖片、頁眉頁腳并支持字體、字號、顏色、對齊、邊框、填充、段落樣式與頁面布局等復(fù)雜格式設(shè)置AXWReports 提供可視化報表設(shè)計器支持?jǐn)?shù)據(jù)綁定、條件格式化、分組和排序適合生成數(shù)據(jù)密集型 DOCX 報表DOCXReadWrite 可解析和修改已有文檔在保留原格式與樣式的前提下完成批量搜索替換和統(tǒng)一格式調(diào)整。壓縮包為 7z 格式約 38.94MB下載頁未列出文件總數(shù)與類型明細(xì)解壓后可直接查看內(nèi)部結(jié)構(gòu)。已有 953 人學(xué)習(xí)下載。對需要在業(yè)務(wù)系統(tǒng)中集成 Word 文檔處理的 Delphi 工程師這套組件可以省去大量底層格式開發(fā)成本讓文檔生成、報表輸出和批量維護(hù)更加高效。 裝 Delphi 第三方組件庫翻車概率最高的從來不是代碼問題而是版本匹配問題。DOCXSuit 這套處理 Word 文檔的三件套AXWWriter、AXWReports、DOCXReadWrite在 Delphi 開發(fā)者里不算冷門它的編譯產(chǎn)物跟 IDE 版本綁得很死——同一個 7z 安裝包喂給 XE10.3 以外版本的 Delphi輕則報 Cannot find unit重則 IDE 啟動直接加載不了包。我?guī)屯戮冗^一次他把給 XE10.3 Rio 編的 .bpl 拖進(jìn)新版 IDE起不來最后只能把環(huán)境和包統(tǒng)一回退。這篇安裝記錄從解壓 7z、配 Library Path、編 .dpk 一路寫到工程里生成 DOCX 并回讀驗(yàn)證適合正被組件裝不上、報錯看不懂卡住的人。2. 環(huán)境準(zhǔn)備XE10.3 版本核對、7z 解壓與源碼目錄規(guī)劃2.1 版本選用DOCXSuit 和 XE10.3 的對應(yīng)關(guān)系先講版本。DOCXSuit 安裝包命名里帶 XE10.3 Rio說明它的 .dcu編譯好的單元和 .bpl包文件是用 XE10.3 的 RTL 生成的。Delphi 的包文件機(jī)制決定了不同大版本之間互不通用編譯出來的 DCU 頭里帶的版本標(biāo)識、包文件引用的運(yùn)行時單元路徑都不一樣硬塞進(jìn)去要么編譯期報“Unit not found”要么 IDE 加載包時直接內(nèi)存錯亂。常見做法是先核對 RAD Studio 的小版本。XE10.3 Rio 里面有 10.3.0、10.3.1、10.3.2、10.3.3 幾個小版本組件庫大多要求至少 10.3.3。我一般先把 IDE 升級補(bǔ)丁打全再裝組件不然有些 RTL 修復(fù)沒生效組件編譯出來之后運(yùn)行時會出各種玄學(xué)問題——不是不能跑是一會兒有一會兒沒有那種最費(fèi)時間。如果你手頭只有 XE10.4 或 XE11理論上可以拿 DOCXSuit 的源碼重新編譯但這套包的 .dpk 文件里 requires 寫死了版本相關(guān)的運(yùn)行時包名手動改 .dpk 很容易把依賴關(guān)系改壞。我的建議是要么按安裝包匹配的版本裝要么別碰源碼重編。為了一份組件去折騰包依賴不劃算。項(xiàng)目XE10.3 RioXE10.4 SydneyXE11 Alexandria編譯環(huán)境標(biāo)識28.x29.x30.xDOCXSuit 安裝包匹配本包需另找對應(yīng)包需另找對應(yīng)包運(yùn)行時包目錄版本號20.021.022.0表格注意最后一行運(yùn)行時包目錄版本號是裝完組件后找 .bpl 的關(guān)鍵第 4 章排查問題時會反復(fù)用到。2.2 下載校驗(yàn)7z 包別解壓到一半才后悔DOCXSuit 是以 7z 壓縮包分發(fā)的不是 zipWindows 自帶的解壓工具不認(rèn)得用 7-Zip 19.00 以上版本。我見過有人用老版本解壓解到一半報 CRC error原因是壓縮包用了較新的 LZMA2 字典大小老版本的解壓器不支持。下載完成后先核對文件完整性和哈希值。發(fā)布方一般會在資源頁標(biāo)注 SHA-256沒標(biāo)的話至少對一下文件大小。我在 Windows PowerShell 里算哈希Get-FileHash .\DOCXSuit_XE10.3.7z -Algorithm SHA256打印出來的哈希值和資源頁對得上才繼續(xù)往下。對不上就重新下載別賭運(yùn)氣——損壞的 7z 強(qiáng)解出來后面編譯報錯能把你帶溝里。校驗(yàn)通過后用 7-Zip 解壓C:\Program Files\7-Zip\7z.exe x DOCXSuit_XE10.3.7z -oC:\Libs\AxolotDOCXSuit參數(shù)說明x解壓并保留壓縮包內(nèi)的目錄結(jié)構(gòu)-o指定輸出目錄注意-o和目標(biāo)路徑之間沒有空格目標(biāo)路徑如果帶空格整個括號里的內(nèi)容都要用引號包住。解壓出來的目錄結(jié)構(gòu)大概是這樣的C:\Libs\AxolotDOCXSuit ├── Packages\ # 各模塊的 .dpk 包工程 │ ├── AXWWriter\ │ ├── AXWReports\ │ └── DOCXReadWrite\ ├── Sources\ # .pas 源碼 ├── Lib\ # 預(yù)編譯的 .dcu / .bpl ├── Samples\ # 官方示例工程 └── Docs\ # Readme 和安裝說明解壓完先看 Docs 里的安裝說明確認(rèn)官方推薦的安裝順序。DOCXSuit 的三個模塊有依賴關(guān)系A(chǔ)XWReports 依賴 AXWWriter 的單元DOCXReadWrite 相對獨(dú)立。這個順序第 3 章會嚴(yán)格沿用。2.3 目錄規(guī)劃源碼放本地路徑別帶中文和空格第三方組件庫的源碼和編譯路徑我會放在磁盤根目錄下的純英文目錄比如C:\Libs\AxolotDOCXSuit而不是C:\Program Files或桌面。原因有兩條Delphi 的 Library Path 對帶空格的路徑支持一直不完善部分組件在編譯時會把路徑截斷報出的錯誤讓人完全摸不著頭腦放在盤符根目錄下重裝 IDE 時路徑好找整個目錄壓包備份也方便。我也見過有人在網(wǎng)絡(luò)盤上解壓源碼編譯時各種奇怪報錯把項(xiàng)目挪回本地磁盤就好了。組件庫源碼永遠(yuǎn)放本地這是原則。還有一個細(xì)節(jié)Lib目錄里如果帶了預(yù)編譯的 .bpl 和 .dcu先別急著刪。如果你打算自己重新編譯全部源碼比如想加調(diào)試符號預(yù)編譯產(chǎn)物可以不用直接從 Packages 里的 .dpk 現(xiàn)場編如果你只是想裝上就用Lib里的東西可能能省一輪編譯時間。我建議首次安裝用源碼編譯原因后面 3.2 會講。提示解壓之后的目錄結(jié)構(gòu)、.dpk文件名、版本標(biāo)識都以你實(shí)際拿到的包為準(zhǔn)。不同渠道分發(fā)的包內(nèi)部組織可能略有差異但安裝流程是同一套。3. 組件安裝三條 Library Path 和三份 .dpk 的編譯順序3.1 配置 Library Path讓 IDE 先認(rèn)識源碼打開 Delphi XE10.3 Rio走 Tools → Options → Delphi Options → Library。這里要改兩個地方Library Path 和 Browsing Path。Library Path 是編譯時找 .dcu 和 .pas 的搜索路徑Browsing Path 只影響代碼編輯器的符號跳轉(zhuǎn)不配也能編譯但配了之后 CtrlClick 能跳到源碼排查問題方便很多。在 Library Path 末尾追加兩行C:\Libs\AxolotDOCXSuit\Sources C:\Libs\AxolotDOCXSuit\Lib這里有個很容易踩的坑Delphi 的 Library Path 是按平臺分開記錄的。如果你要打 Win32 和 Win64 兩個平臺必須在 Library 頁面左上角的 Target 下拉框里把平臺分別切到 Windows 32-bit 和 Windows 64-bit各加一次。我只配了 32 位就切去編 64 位工程編譯時直接報整個 DOCXSuit 的單元全部找不到一臉懵。加完點(diǎn) OK回到主界面先新建一個空 VCL 工程編譯一次確認(rèn) IDE 環(huán)境本身沒問題再做下一步。這一步能排除掉 IDE 自身的故障避免后面把賬算在組件頭上。3.2 編譯安裝 AXWWriter先裝核心AXWWriter 是生成 Word 文檔寫端的核心AXWReports 底層也依賴它所以第一個裝它。文件在Packages\AXWWriter目錄下通常是一個以模塊名加版本號命名的 .dpk 工程。雙擊打開 .dpkPackage 編輯器會顯示包的單元列表和依賴節(jié)點(diǎn)。這時先別急著點(diǎn) Install先點(diǎn)右上角的 Build 按鈕。Delphi 里 Compile 和 Build 的區(qū)別在于Compile只重編譯當(dāng)前包不遞歸處理依賴包改一個單元后快速驗(yàn)證用Build強(qiáng)制重新編譯所有被引用的單元第一次裝組件必須用這個。第一次安裝用 Build把 AXWWriter 的全部單元完整編一遍。編譯通過后看 Package 編輯器左側(cè)的 Requires 節(jié)點(diǎn)確認(rèn)它依賴的運(yùn)行時包是 Delphi 自帶的 rtl、vcl 這一層沒有出現(xiàn)指向其它組件庫的殘留依賴。確認(rèn)沒問題再點(diǎn) Install把 AXWWriter 注冊進(jìn) IDE 的組件面板。Install 成功會彈提示框同時組件面板里會多出 AXW 相關(guān)的頁面或圖標(biāo)。如果沒彈說明 Build 沒過回去看輸出窗口里的紅色報錯——絕大多數(shù)是 3.1 的路徑?jīng)]配全。這里有一個我吃過虧的細(xì)節(jié)Install 成功之后要把 .dpk 保存并關(guān)閉然后去Lib目錄確認(rèn)生成的 .bpl 文件存在。Delphi 有個“包輸出目錄”的設(shè)置如果你之前改過這個配置.bpl 會被丟到別的目錄去。找不到 .bpl后面運(yùn)行時就會出“類未注冊”第 4 章會展開講。3.3 依次編譯 AXWReports 與 DOCXReadWrite依賴順序不能反AXWReports 依賴 AXWWriter 的單元必須等 AXWWriter 編譯注冊完再動它。打開Packages\AXWReports下的 .dpk先檢查 Requires 節(jié)點(diǎn)里出現(xiàn)的是 AXWWriter 的 .bpl 名稱而不是一個單純的源文件路徑——如果是后者說明 IDE 沒認(rèn)出 AXWWriter 的包回去查 3.1。第二份包同樣是先 Build 再 Install觀察輸出窗口時要重點(diǎn)看有沒有Cannot find unit AXWWriter...這種行。報這個說明 3.1 的路徑仍然有遺漏或者包的搜索順序不對回到 Library Path 把Sources目錄往列表前面移。DOCXReadWrite 是讀寫 DOCX 的底層庫對 AXWWriter 沒有硬依賴既可以單獨(dú)裝也可以放最后。我習(xí)慣把它放最后裝理由很樸素它是另外兩個模塊的讀寫基礎(chǔ)放最后裝相當(dāng)于給整條鏈?zhǔn)諅€尾出現(xiàn)問題也只影響 DOCX 讀寫不會波及其它模塊的注冊狀態(tài)。安裝順序模塊作用依賴1AXWWriter生成 DOCX 文檔無2AXWReports報表生成依賴 AXWWriter3DOCXReadWriteDOCX 讀寫底層獨(dú)立三份 .dpk 都 Install 完成后打開 Components → Install Packages在已安裝的包列表里應(yīng)該能看到三個新條目?？吹街蠼M件才算真正裝上接下來進(jìn)入驗(yàn)證環(huán)節(jié)。4. 避坑排查DOCXSuit 安裝最常見的五個翻車點(diǎn)4.1 現(xiàn)象編譯報錯 Cannot find unit整個輸出窗口一片紅編 AXWWriter 的 .dpk 時輸出窗口一直滾[dcc32 Fatal Error] E2201 Unit not found: AXWWriterXXX。原因多半是 Library Path 沒走到源碼目錄或者路徑里帶了中文和空格被編譯器的路徑解析截斷也常見于 3.1 里提到的平臺沒切對——只配了 Win32切到 Win64 編就報錯。我第一次裝的時候就是死在平臺這里路徑明明加了編譯還是找不到最后發(fā)現(xiàn)是 Target 下拉框停在 32 位沒動。解決方式是回 Tools → Options → Library確認(rèn)Sources目錄在列表里然后把 Target 切到當(dāng)前要編的平臺兩個平臺都加一遍。改完路徑先 Compile 一次再 Build不要直接 Build——Compile 報錯信息更直接適合定位是路徑問題還是代碼問題。4.2 現(xiàn)象.dpk 裝完組件面板里找不到 AXW 圖標(biāo)Install 提示成功但組件面板翻了好幾頁都看不到 AXW 開頭的組件。先說一個容易忽略的點(diǎn)DOCXSuit 里有一部分模塊是純類庫不注冊可視組件比如 DOCXReadWrite安裝后組件面板上本來就沒有它的圖標(biāo)。AXWWriter 的組件注冊后也可能落在某個非默認(rèn)的組件頁比如名為 Axolot 的頁面被折疊在面板抽屜里。解決方式是右鍵組件面板打開 Components 配置窗口在搜索框里輸入 AXW 或 Axolot 過濾。找到就說明注冊成功了只是頁面位置太隱蔽。真找不到的話回 Package 編輯器點(diǎn) Uninstall再重新 Install 一次然后重啟 IDE——重啟能解決 Delphi 里大部分組件面板不刷新的問題。4.3 現(xiàn)象工程能編譯運(yùn)行時彈 Class not registered 或找不到 .bpl工程編譯順利一運(yùn)行就報Class not registered或者The specified module could not be found。原因是在運(yùn)行時代碼要去加載 DOCXSuit 的運(yùn)行時包 .bpl而這個包不在系統(tǒng)的 DLL 搜索路徑里。Delphi 默認(rèn)把包的輸出目錄放在用戶文檔目錄下的 BPL 文件夾里比如 XE10.3 對應(yīng)版本目錄 20.0。如果你在安裝組件時改過包輸出目錄或者 .dpk 編譯后 .bpl 落在了別處運(yùn)行時自然找不到。解決方式是把 AXWWriter.bpl、AXWReports.bpl、DOCXReadWrite.bpl 全部復(fù)制到 Delphi XE10.3 默認(rèn)的 BPL 目錄里或者把 .bpl 所在目錄手動加到系統(tǒng)環(huán)境變量 Path 中。復(fù)制完重啟 IDE 再跑工程這個報錯就不會再出現(xiàn)。我最開始嫌復(fù)制麻煩直接改 Path后來重裝系統(tǒng)發(fā)現(xiàn) Path 里的舊路徑失效反而多花半天排查現(xiàn)在一律復(fù)制到默認(rèn)目錄。4.4 現(xiàn)象7z 解壓中途報 CRC 失敗強(qiáng)解出來的文件不能用解壓到一半7-Zip 報Unexpected end of archive或CRC failed點(diǎn)“保留損壞文件”之后勉強(qiáng)解出一堆文件編譯時各種莫名錯誤。原因是下載過程丟包或轉(zhuǎn)存工具把壓縮包截斷了不是解壓工具的鍋也不是包的編碼問題。常見來源是瀏覽器斷點(diǎn)續(xù)傳沒有完成、網(wǎng)盤同步工具只同步了一部分。強(qiáng)行解壓出來的文件哪怕能打開內(nèi)容也可能是不完整的編出來的組件行為無法預(yù)期。解決方式是把壓縮包重新下載一遍下載完先算 SHA-256 和發(fā)布頁核對再解壓。解壓工具換成 7-Zip 19.00 以上版本別用 Windows 右鍵菜單自帶的“全部解壓縮”那個對 7z 格式支持比較老容易在 LZMA2 解壓上翻車。順序是先看文件大小再對哈希值最后解壓一步都不能省。4.5 現(xiàn)象裝完 DOCXSuit 后工程里出現(xiàn)單元名沖突工程里報Ambiguous unit name或者明明 uses 了某個 AXW 單元IDE 卻提示單元不存在。原因是有多個第三方庫共用了同一個單元名。Delphi 的 Library Path 是按下標(biāo)順序搜索的哪個庫的目錄排在前面就優(yōu)先用哪個庫的同名文件。DOCXSuit 的單元命名相對獨(dú)立但如果你同時裝了別的報表庫或文檔處理庫撞上的概率并不低。解決方式是在 Library Path 里把 DOCXSuit 的Sources目錄整體往前移讓它的單元優(yōu)先被搜到或者在工程里用絕對路徑 uses直接指到C:\Libs\AxolotDOCXSuit\Sources\AXWWriter這種完整路徑。絕對不能把兩個組件庫的源碼目錄混放在同一個目錄下那樣編譯器會徹底分不清誰是誰。5. 工程接入用 AXWWriter 生成 DOCX 再回讀校驗(yàn)5.1 新建 VCL 工程并引入 AXW 單元組件裝好之后驗(yàn)證方式不是直接寫功能代碼而是先新建一個 VCL Forms Application 工程。VCL 工程的運(yùn)行時包加載機(jī)制和真實(shí)項(xiàng)目一致用它驗(yàn)證比控制臺工程可靠得多。在窗體上加兩個按鈕和一個 Memo然后在單元文件的 uses 里引入 AXWWriter 的核心單元。DOCXSuit 解壓后Sources目錄里的單元名以實(shí)際包為準(zhǔn)我這里的示例按常見命名風(fēng)格寫假設(shè)核心單元叫AXWWriter和AXWDocumentuses AXWWriter, AXWDocument;加完引用先編譯一次如果 IDE 報單元找不到說明 3.1 的路徑仍有遺漏優(yōu)先回查 Library Path而不是改單元名。這一步把環(huán)境問題擋在前面后面所有代碼問題才能歸到代碼頭上。5.2 用 AXWWriter 生成一份帶標(biāo)題和表格的 DOCX在按鈕的 OnClick 事件里寫生成邏輯。核心思路是創(chuàng)建文檔對象、往里面加段落和表格、保存到磁盤。示例如下procedure TForm1.Button1Click(Sender: TObject); var Doc: TAXWDocument; Paragraph: TAXWParagraph; Table: TAXWTable; begin Doc : TAXWDocument.Create; try Doc.Title : DOCXSuit 安裝驗(yàn)證; Paragraph : Doc.AddParagraph(DOCXSuit 安裝驗(yàn)證文檔, 16); Paragraph.Bold : True; Doc.AddParagraph(這段正文由 AXWWriter 生成。, 10).Alignment : taLeft; Table : Doc.AddTable(2, 2); Table.Cell[0, 0].Text : 模塊; Table.Cell[0, 1].Text : 狀態(tài); Table.Cell[1, 0].Text : AXWWriter; Table.Cell[1, 1].Text : OK; Doc.SaveToFile(C:\Temp\AxolotTest.docx); ShowMessage(生成成功); finally Doc.Free; end; end;代碼邏輯拆開看TAXWDocument是文檔對象AddParagraph負(fù)責(zé)插入段落并返回段落對象方便繼續(xù)設(shè)置粗體、字號、對齊AddTable的兩個參數(shù)是行數(shù)和列數(shù)返回的表格對象用Cell[i, j].Text填內(nèi)容。對象生命周期用 try/finally 包住是 Delphi 的慣例中間如果保存異常能保證Doc.Free一定執(zhí)行不會留下句柄泄漏。需要留意這里 API 名稱是按常見命名風(fēng)格寫的示意DOCXSuit 的具體類名和參數(shù)定義以Samples目錄里的示例工程為準(zhǔn)。裝完第一件事就是打開官方示例跑一遍比自己猜 API 快得多。5.3 用 DOCXReadWrite 回讀校驗(yàn)生成完不叫閉環(huán)能讀回來才算數(shù)。再加一個讀取按鈕用 DOCXReadWrite 把剛才的文件讀出來并校驗(yàn)內(nèi)容里是否包含預(yù)期的關(guān)鍵字uses DOCXReadWrite;procedure TForm1.Button2Click(Sender: TObject); var Reader: TDOCXReader; Content: string; begin Reader : TDOCXReader.Create; try Content : Reader.LoadFileToString(C:\Temp\AxolotTest.docx); Memo1.Lines.Add(Content); if Pos(AXWWriter, Content) 0 then ShowMessage(驗(yàn)證通過內(nèi)容包含預(yù)期關(guān)鍵字) else ShowMessage(驗(yàn)證失敗內(nèi)容不完整); finally Reader.Free; end; end;LoadFileToString把整個文檔的純文本提取出來用于確認(rèn)寫入內(nèi)容真的落盤。如果返回空串先檢查文件路徑的寫權(quán)限再檢查 AXWWriter 保存時有沒有拋異常。Pos是 Delphi 自帶的字符串查找函數(shù)第一個參數(shù)是關(guān)鍵字第二個是目標(biāo)字符串返回值大于 0 就說明找到了。到這一步寫和讀都跑通了DOCXSuit 在工程里的接入就是健康的。如果Pos找不到預(yù)期文字別急著改代碼先打開生成的 docx 文件確認(rèn)內(nèi)容確實(shí)存在再回頭查 AXWWriter 的保存參數(shù)——八成是文檔對象里某些屬性賦值沒生效。6. 裝完怎么驗(yàn)證跑通三分鐘組件自檢清單6.1 自檢順序面板、編譯、運(yùn)行每次裝完組件庫我強(qiáng)制自己走一遍三連檢查缺一項(xiàng)都不算裝完Components → Install Packages 里能看到三個包條目狀態(tài)是 Active新建空 VCL 工程引用 AXWWriter 單元后能直接編譯出 exe無紅色報錯跑 5.2 和 5.3 的讀寫示例生成 docx 后能正?；刈x并匹配關(guān)鍵字。6.2 版本核對在 IDE 的 Help → About 里確認(rèn)當(dāng)前版本是 XE10.3 Rio在 Install Packages 列表里查看 DOCXSuit 三個包的安裝信息看 Build 日期和安裝包發(fā)布日是否對得上。日期差得太遠(yuǎn)說明包版本和 IDE 補(bǔ)丁級別可能不匹配需要回頭打 IDE 補(bǔ)丁。驗(yàn)證項(xiàng)期望結(jié)果失敗處理Install Packages 列表三個包均為 Active重新 Build 并 Install空工程編譯無紅色報錯檢查 Library Path 和平臺AXWWriter 生成文件生成成功檢查保存路徑權(quán)限D(zhuǎn)OCXReadWrite 回讀關(guān)鍵字匹配檢查文檔內(nèi)容、比對示例工程這套檢查做完不超過三分鐘但它能擋住后面至少半天的排查時間。從那以后我每次換機(jī)器、重裝 IDE都先把 DOCXSuit 完整裝一遍并跑通讀寫 Demo而不是直接從舊機(jī)器拷一個裝好的 BPL 過來——省得運(yùn)行時版本對不上出幺蛾子。裝組件這事兒最怕的不是報錯是裝完不知道該信它還是懷疑它。希望這份流程能幫你在 Delphi XE10.3 Rio 下少繞幾個彎。本文還有配套的精品資源點(diǎn)擊獲取