做過(guò)Word模板導(dǎo)出功能開(kāi)發(fā)的人多半都被“插入圖片”這件事卡過(guò)?？蛻舻拿枋鲇肋h(yuǎn)很具體報(bào)告生成到第三頁(yè)這一段下面必須放質(zhì)檢照片或者一個(gè)大表格里某些單元格要貼圖。你翻遍POI的文檔找到addPicture這個(gè)方法調(diào)完之后圖片確實(shí)進(jìn)來(lái)了位置卻是文檔末尾。今天這篇就專(zhuān)門(mén)聊聊“用POI操作Word在指定位置插入圖片”的完整思路、代碼實(shí)現(xiàn)和踩坑記錄適合正在做報(bào)表導(dǎo)出、合同生成、批量證書(shū)打印或者任何用POI碰過(guò)Word模板填充的開(kāi)發(fā)者。1. 別上來(lái)就寫(xiě)代碼先搞清楚圖片在docx里到底存在哪第一次用POI往Word里插圖片的人基本都會(huì)走這么一條彎路先new XWPFDocument()然后doc.addPicture(...)圖片確實(shí)進(jìn)去了但永遠(yuǎn)在文檔末尾。這不是bug也不是POI故意坑你而是因?yàn)閐ocx的物理結(jié)構(gòu)和我們?nèi)粘?xiě)Word時(shí)的直覺(jué)完全不一樣。一個(gè).docx文件本質(zhì)上是一堆XML打包在一起。正文內(nèi)容放在word/document.xml里結(jié)構(gòu)大致是文檔Document下面是一個(gè)BodyBody下面是一排塊級(jí)元素最主要的兩種塊是段落w:p和表格w:tbl。每個(gè)段落內(nèi)部又有若干Runw:rRun才是真正承載文本的最小單位。一張圖片在XML里不是一個(gè)獨(dú)立的塊它是掛在某個(gè)Run下面的一串Drawing元素。這就是關(guān)鍵點(diǎn)POI里段落XWPFParagraph沒(méi)有addPicture方法能插圖片的只有XWPFRun也就是段落里某個(gè)Run。所以“指定位置插入圖片”這句話拆開(kāi)看其實(shí)是兩步定位到目標(biāo)位置對(duì)應(yīng)的段落或Run再調(diào)用那個(gè)Run上的addPicture。理解了這一層再看XWPFDocument.addPicture為什么沒(méi)用就清楚了——它確實(shí)也能把圖片加進(jìn)文檔但它只能新建一個(gè)段落并把圖片放進(jìn)去這個(gè)段落被追加在Body最后面。它不是“文檔級(jí)”該有的操作更像是一個(gè)方便追加的快捷方法。想要往文檔中間、模板某個(gè)位置插圖必須自己控制游標(biāo)和段落。還有一個(gè)容易忽略的細(xì)節(jié)Word中的Run是一段格式相同的文本。比如你寫(xiě)“第一段加粗第二段普通”這兩段里就有不同的標(biāo)簽。圖片掛在某個(gè)Run下意味著圖片會(huì)和這個(gè)Run擁有相同的段落格式、字體設(shè)置。這也是為什么插入圖片后它的縮進(jìn)、行距、對(duì)齊方式經(jīng)常要額外單獨(dú)設(shè)置——因?yàn)閳D片事實(shí)上繼承或者部分繼承了Run所在的段落樣式。搞清楚對(duì)象模型之后下一個(gè)問(wèn)題自然就來(lái)了怎么定位標(biāo)題里的“指定位置”到底怎么表達(dá)給POI2. 定位方案對(duì)比索引、文本錨點(diǎn)、書(shū)簽到底選哪個(gè)“指定位置”說(shuō)起來(lái)簡(jiǎn)單但實(shí)現(xiàn)時(shí)定位方式有幾種選錯(cuò)后面全是坑。我把常見(jiàn)方案整理了一下按實(shí)際體驗(yàn)排序。定位方式實(shí)現(xiàn)難度抗模板改動(dòng)能力模板可讀性實(shí)測(cè)推薦度段落索引定位低差模板多一個(gè)段落就全錯(cuò)位差靠猜不推薦文本錨點(diǎn)定位中好只要錨點(diǎn)文字不被刪就行好模板里一眼能看出標(biāo)記強(qiáng)推書(shū)簽定位中高好但POI對(duì)書(shū)簽的封裝比較繞一般Word里才看得見(jiàn)可以用但不優(yōu)先表格行/單元格定位中取決于具體場(chǎng)景一般特定場(chǎng)景用索引定位是我最早試的方法。寫(xiě)起來(lái)最省事doc.getParagraphs().get(index)拿到段落就往前面插。但壞處非常致命模板只要被編輯過(guò)一次哪怕是多空了一行索引全部位移。而且批量插入時(shí)前一次插入會(huì)改變后續(xù)段落的索引位置得從后往前倒著插調(diào)試起來(lái)非常消耗耐心。這個(gè)方法只適合那種完全用代碼動(dòng)態(tài)生成的、結(jié)構(gòu)永遠(yuǎn)不變化的文檔不適合模板填充。書(shū)簽定位理論上很優(yōu)雅。Word里CtrlShiftF2加個(gè)書(shū)簽POI里也有XWPFBookmark、getBookmarks()之類(lèi)的東西。實(shí)際試下來(lái)書(shū)簽要綁定到段落或者Run的XML節(jié)點(diǎn)上定位之后進(jìn)行操作還得自己轉(zhuǎn)游標(biāo)代碼繞模板使用者還未必會(huì)加書(shū)簽。不是不行是性?xún)r(jià)比低。我最后穩(wěn)定使用的是文本錨點(diǎn)定位。做法很簡(jiǎn)單在Word模板里寫(xiě)一行占位符比如{{IMG}}或者更具體的{{IMG_QUALITY}}、{{IMG_SIGNATURE}}代碼先遍歷所有段落包括表格里的段落找到包含這個(gè)標(biāo)記的段落然后在它前面或后面插入一個(gè)帶圖片的新段落。好處是模板長(zhǎng)什么樣不影響定位編輯過(guò)也最多是標(biāo)記文字被改視覺(jué)上占位符本身對(duì)排版影響也小。占位符設(shè)計(jì)有兩個(gè)小經(jīng)驗(yàn)。第一標(biāo)記盡量加雙花括號(hào)比如{{IMG}}這和渲染模板的語(yǔ)法一致不容易和正文文字沖突第二每個(gè)插入位置用不同的標(biāo)記名稱(chēng)而不是復(fù)用同一個(gè){{IMG}}這樣批量插入時(shí)不會(huì)出現(xiàn)“每次找到的都是第一個(gè)標(biāo)記”的問(wèn)題。選定文本錨點(diǎn)方案之后剩下的核心就是游標(biāo)操作了。這也是POI插入圖片最繞、最容易出問(wèn)題的地方。3. 游標(biāo)定位法完整實(shí)現(xiàn)從依賴(lài)到代碼一步步來(lái)先說(shuō)環(huán)境。我用的是Maven工程最常用的POI版本是5.2.3用4.x也差不多但5.x的API更干凈推薦以5.x為準(zhǔn)。dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependencypoi-ooxml這個(gè)包會(huì)把poi、xmlbeans、poi-ooxml-lite等依賴(lài)一并帶進(jìn)來(lái)做Word段落、Run、圖片操作已經(jīng)足夠不需要額外引入poi-scratchpad。3.1 先在模板里埋好占位符打開(kāi)Word模板在需要插入圖片的位置輸入{{IMG_LOGO}}比如公司技術(shù)認(rèn)證報(bào)告 {{IMG_LOGO}} 申請(qǐng)人信息如下……這里的{{IMG_LOGO}}會(huì)在運(yùn)行時(shí)被圖片替換掉。模板里這一行可以單獨(dú)占一個(gè)段落也可以和其他文字混在一起。為了排版省心我建議單獨(dú)占一行。3.2 查找錨點(diǎn)段落的核心代碼查找錨點(diǎn)有兩個(gè)層面要處理文檔正文段落和表格內(nèi)段落。很多人只寫(xiě)了doc.getParagraphs()結(jié)果表格里的占位符永遠(yuǎn)定位不到這是最常見(jiàn)的坑之一。import org.apache.poi.xwpf.usermodel.*; public class AnchorFinder { /** * 在文檔所有段落含表格單元格中的段落中查找包含指定占位符的段落。 */ public static XWPFParagraph findAnchor(XWPFDocument doc, String placeholder) { // 1. 正文區(qū)段落 for (XWPFParagraph p : doc.getParagraphs()) { if (p.getText() ! null p.getText().contains(placeholder)) { return p; } } // 2. 表格內(nèi)單元格的段落 for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { for (XWPFParagraph p : cell.getParagraphs()) { if (p.getText() ! null p.getText().contains(placeholder)) { return p; } } } } } return null; } }這里注意cell.getParagraphs()在POI 5.x返回的是ListXWPFParagraph和正文段落一樣操作沒(méi)區(qū)別。3.3 在錨點(diǎn)段落之前插入帶圖片的新段落定位到錨點(diǎn)段落之后最常用的需求是把圖片插到占位符所在位置。以“圖片插在錨點(diǎn)段落之前”為例完整代碼如下import org.apache.poi.util.Units; import org.apache.poi.xwpf.usermodel.*; import org.apache.xmlbeans.XmlCursor; import java.io.FileInputStream; import java.io.InputStream; public class WordImageInserter { /** * 在錨點(diǎn)段落之前插入一個(gè)包含圖片的新段落。 */ public static void insertImageBefore(XWPFParagraph anchor, String imagePath, int widthPx, int heightPx) throws Exception { // 關(guān)鍵拿到錨點(diǎn)段落的底層X(jué)ML游標(biāo) XmlCursor cursor anchor.getCTP().newCursor(); // 在游標(biāo)當(dāng)前位置插入新段落。游標(biāo)正好指向錨點(diǎn)段落的開(kāi)始 // 所以新段落會(huì)落在錨點(diǎn)段落之前。 XWPFParagraph imgParagraph anchor.getDocument().insertNewParagraph(cursor); // 讓圖片段落居中視覺(jué)效果最穩(wěn) imgParagraph.setAlignment(ParagraphAlignment.CENTER); // 新建Run圖片掛在Run上 XWPFRun run imgParagraph.createRun(); // 根據(jù)文件擴(kuò)展名判斷圖片類(lèi)型 int picType getPictureType(imagePath); // addPicture的寬高單位是EMU不是像素這里用Units轉(zhuǎn)換 try (InputStream is new FileInputStream(imagePath)) { run.addPicture(is, picType, imagePath, Units.toEMU(widthPx), Units.toEMU(heightPx)); } // 插入完成之后把占位符從錨點(diǎn)段落里清掉 clearPlaceholder(anchor, {{IMG_LOGO}}); } private static int getPictureType(String imagePath) { String lower imagePath.toLowerCase(); if (lower.endsWith(.png)) return XWPFDocument.PICTURE_TYPE_PNG; if (lower.endsWith(.jpg) || lower.endsWith(.jpeg)) return XWPFDocument.PICTURE_TYPE_JPEG; if (lower.endsWith(.emf)) return XWPFDocument.PICTURE_TYPE_EMF; if (lower.endsWith(.wmf)) return XWPFDocument.PICTURE_TYPE_WMF; if (lower.endsWith(.dib)) return XWPFDocument.PICTURE_TYPE_DIB; throw new IllegalArgumentException(不支持的圖片格式: imagePath); } private static void clearPlaceholder(XWPFParagraph paragraph, String placeholder) { StringBuilder sb new StringBuilder(); for (XWPFRun run : paragraph.getRuns()) { sb.append(run.getText(0) null ? : run.getText(0)); } if (sb.indexOf(placeholder) 0) { String newText sb.toString().replace(placeholder, ); ListXWPFRun runs paragraph.getRuns(); if (!runs.isEmpty()) { // 把清理后的文本放到第一個(gè)Run其他Run清空 runs.get(0).setText(newText, 0); for (int i 1; i runs.size(); i) { runs.get(i).setText(, 0); } } } } }這段代碼看起來(lái)不長(zhǎng)但幾個(gè)關(guān)鍵點(diǎn)不解釋清楚換一個(gè)場(chǎng)景就抓瞎。XmlCursor是Apache XMLBeans提供的游標(biāo)它可以直接在底層X(jué)ML節(jié)點(diǎn)上做前后移動(dòng)和插入操作。anchor.getCTP().newCursor()返回的游標(biāo)位置我實(shí)測(cè)下來(lái)是在錨點(diǎn)段落w:p的開(kāi)始標(biāo)簽處。doc.insertNewParagraph(cursor)這個(gè)方法是XWPFDocument提供的專(zhuān)門(mén)用來(lái)在指定XML位置創(chuàng)建段落它和普通的createParagraph()不同后者只會(huì)追加到Body尾部前者才是真正的“指哪打哪”。寬高參數(shù)是另一個(gè)容易翻車(chē)的地方。addPicture方法簽名里的最后兩個(gè)參數(shù)是EMUEnglish Metric Unit不是像素。Word內(nèi)部繪圖單位是EMU1英寸等于914400 EMU1像素大概是9525 EMU。如果直接拿像素?cái)?shù)字傳進(jìn)去圖片會(huì)小得幾乎看不見(jiàn)或者大得離譜。Units.toEMU()就是干這個(gè)換算的沒(méi)這個(gè)工具類(lèi)只能自己乘9525。clearPlaceholder做的事是把占位符文本從錨點(diǎn)段落里抹掉。為什么要單獨(dú)做這一步因?yàn)檎嘉环粼谀０謇锏谝淮芜\(yùn)行時(shí)被圖片替換了但如果不清掉第二次生成時(shí)同一個(gè)模板還會(huì)再匹配到它就會(huì)出現(xiàn)重復(fù)插入。3.4 想插到錨點(diǎn)段落之后怎么辦很多需求是“在某某段落后邊加一張圖”比如“以上為申請(qǐng)信息下方為簽字照片”。這種場(chǎng)景下圖片要插在錨點(diǎn)段落后面做法是先把游標(biāo)往后移動(dòng)到錨點(diǎn)段落的結(jié)束標(biāo)簽位置XmlCursor cursor anchor.getCTP().newCursor(); cursor.toEndToken(); XWPFParagraph imgParagraph anchor.getDocument().insertNewParagraph(cursor); // 后續(xù)邏輯同上創(chuàng)建Run、addPicture、清占位符toEndToken()把游標(biāo)移動(dòng)到當(dāng)前元素結(jié)束標(biāo)簽的位置此時(shí)調(diào)用insertNewParagraph新段落會(huì)落在錨點(diǎn)段落之后。這個(gè)和插入到前面剛好對(duì)稱(chēng)。不過(guò)要提醒一句不同版本XMLBeans對(duì)游標(biāo)位置“在結(jié)束標(biāo)簽上”和“在結(jié)束標(biāo)簽后”的語(yǔ)義行為略有差異萬(wàn)一插出來(lái)位置不對(duì)在toEndToken()之后補(bǔ)一行cursor.toNextToken()再插入通常就能糾正。如果你的場(chǎng)景比較復(fù)雜圖既要插在錨點(diǎn)前又要插在錨點(diǎn)后或者一時(shí)拿不準(zhǔn)方向最穩(wěn)妥的做法是模板里放一對(duì)占位符比如{{IMG_START}}和{{IMG_END}}圖片先插到{{IMG_END}}之前再把兩個(gè)占位符都清掉。這樣無(wú)論版本怎么變位置始終可控。4. 圖片大小、對(duì)齊和樣式繼承插進(jìn)去不難插得好看才難圖片能插進(jìn)去了不代表完事了。我見(jiàn)過(guò)很多初學(xué)者把圖插進(jìn)去之后一打開(kāi)Word圖片要么大得超出頁(yè)面要么歪在頁(yè)面邊上要么和周?chē)淖謹(jǐn)D在一起版式完全沒(méi)法看。這一節(jié)把排版相關(guān)的細(xì)節(jié)一次說(shuō)透。4.1 按比例縮放圖片而不是寫(xiě)死寬高最樸素的寫(xiě)法是直接傳固定像素值比如Units.toEMU(300)、Units.toEMU(200)。問(wèn)題在于原圖可能是4000x3000的大圖傳300x200會(huì)變形原圖是800x600傳300x200又會(huì)模糊。正確做法是先讀圖片原始尺寸按目標(biāo)寬度等比計(jì)算高度。import javax.imageio.ImageIO; import java.awt.image.BufferedImage; import java.io.File; public static int[] calcScaledSize(String imagePath, int maxWidthPx, int maxHeightPx) throws Exception { BufferedImage img ImageIO.read(new File(imagePath)); int width img.getWidth(); int height img.getHeight(); double scale Math.min( (double) maxWidthPx / width, (double) maxHeightPx / height ); if (scale 1) { return new int[]{width, height}; } return new int[]{(int)(width * scale), (int)(height * scale)}; }至于最大寬高設(shè)多少要結(jié)合頁(yè)面實(shí)際可用寬度來(lái)算。A4紙寬度是21厘米默認(rèn)頁(yè)邊距左右各3.17厘米也就是說(shuō)文字區(qū)的可用寬度大概是14.65厘米。如果你希望圖片鋪滿整個(gè)可用寬度14.65厘米換算成像素大概是14.65 / 2.54 * 96 ≈ 553像素。我一般取550作為最大寬度高度限制在350-400左右基本不會(huì)超出頁(yè)面。4.2 對(duì)齊方式單獨(dú)設(shè)置圖片段落既然是獨(dú)立的段落它的對(duì)齊方式就由段落屬性控制。居中是最常見(jiàn)的需求imgParagraph.setAlignment(ParagraphAlignment.CENTER);左右對(duì)齊也是同理。要注意的是如果錨點(diǎn)段落原來(lái)的對(duì)齊方式是左對(duì)齊而你新插入的圖片段落沒(méi)有顯式設(shè)置那么圖片會(huì)沿用段落默認(rèn)樣式可能是左對(duì)齊也可能是兩端對(duì)齊整體看起來(lái)就很隨機(jī)。所以每次插入都顯式setAlignment不要依賴(lài)默認(rèn)值。4.3 圖片段落繼承錨點(diǎn)段落的樣式模板里不同段落的字體、行距、縮進(jìn)可能不同。如果圖片段落是全新建的“裸段落”它的樣式可能和其他段落格格不入。最簡(jiǎn)單的解法是把錨點(diǎn)段落的段落屬性拷貝過(guò)來(lái)import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP; import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTPPr; CTP anchorCtp anchor.getCTP(); CTP imgCtp imgParagraph.getCTP(); if (anchorCtp.isSetPPr()) { imgCtp.setPPr((CTPPr) anchorCtp.getPPr().copy()); }這樣做的好處是行距、縮進(jìn)、段前段后間距全都和錨點(diǎn)段落保持一致。如果你連字體格式都希望圖片Run繼承可以再拷貝Run的RPr不過(guò)圖片本身沒(méi)有字體影響不大。4.4 圖片和周?chē)淖种g的間距圖片段落默認(rèn)的行距可能會(huì)讓圖片和上下文字貼得很近讀起來(lái)很擠?？梢栽趫D片段落的setSpacingBefore和setSpacingAfter上稍微加點(diǎn):imgParagraph.setSpacingBefore(200); imgParagraph.setSpacingAfter(200);這里的單位是緹twips1磅等于20緹200緹就是10磅視覺(jué)上比較舒服。具體大小看實(shí)際效果微調(diào)。5. 實(shí)測(cè)踩坑記錄這份避坑清單能省你大半天時(shí)間這部分整理了我在實(shí)際項(xiàng)目中遇到過(guò)的坑有些坑可能浪費(fèi)了你幾個(gè)小時(shí)也不一定想到。每一條都是從報(bào)錯(cuò)到排錯(cuò)到解決完整走過(guò)來(lái)的不是從官方文檔摘抄的。5.1 占位符被Word拆到多個(gè)Run里replace不掉這是第一個(gè)真正惡心到我的坑。模板里手寫(xiě)的{{IMG_LOGO}}存盤(pán)之后Word不一定把整串文字放在同一個(gè)Run里可能{{在一個(gè)RunIMG_LOGO在另一個(gè)Run}}又在第三個(gè)Run。你用paragraph.getText()能拿到完整文本一replace卻發(fā)現(xiàn)段落里根本沒(méi)變化因?yàn)槟阋鎿Q的內(nèi)容跨越了Run邊界。clearPlaceholder里我用了“拼完整文本、改第一個(gè)Run、清空其余Run”的策略就是為了應(yīng)對(duì)這種情況。如果替換完發(fā)現(xiàn)錨點(diǎn)段落里還殘留半個(gè)大括號(hào)的文本多半是遍歷時(shí)遺漏了哪個(gè)Run的getText(0)返回null處理時(shí)判空就行。5.2 只查正文段落表格里的占位符永遠(yuǎn)找不到上文代碼里已經(jīng)處理了這個(gè)問(wèn)題但我在實(shí)際開(kāi)發(fā)中見(jiàn)到不少同事只寫(xiě)了doc.getParagraphs()。文檔一旦涉及表格比如申請(qǐng)表、報(bào)價(jià)單占位符放在表格單元格里查正文段落就找不到程序直接往下走圖片就全堆到了文檔末尾。表面看是“插入位置不對(duì)”本質(zhì)是定位邏輯根本沒(méi)覆蓋到表格。排查這類(lèi)問(wèn)題先確認(rèn)錨點(diǎn)是不是在表格里再?zèng)Q定遍歷方式。5.3 重復(fù)插入同一個(gè)占位符被命中多次這不是死循環(huán)但效果類(lèi)似。假設(shè)模板里有好幾處{{IMG}}你調(diào)用findAnchor每次都從頭遍歷那么返回的永遠(yuǎn)是第一個(gè){{IMG}}段落。第一張圖插入后會(huì)清理占位符但第二次查找時(shí)第一個(gè)段落已經(jīng)沒(méi)有標(biāo)記了可代碼是從頭再查的結(jié)果還是會(huì)找到第二個(gè)位置之前的第一個(gè){{IMG}}——如果只插入一次還好循環(huán)插入就會(huì)錯(cuò)亂。我的解法是模板里的占位符一律帶編號(hào){{IMG_1}}、{{IMG_2}}、{{IMG_3}}。這樣每個(gè)位置有唯一標(biāo)識(shí)查找時(shí)按編號(hào)精確匹配。如果要插入同一張圖到多個(gè)位置就顯式多次調(diào)用每次傳不同的占位符邏輯清晰也不容易錯(cuò)。5.4 圖片類(lèi)型判斷錯(cuò)誤生成的docx打不開(kāi)addPicture里的第二個(gè)參數(shù)必須和實(shí)際圖片字節(jié)格式匹配。之前出現(xiàn)過(guò)一次文件擴(kuò)展名是.png但實(shí)際內(nèi)容被改成了JPEG編碼getPictureType判斷成了PNG結(jié)果打開(kāi)生成的Word時(shí)報(bào)“無(wú)法讀取圖片文件已損壞”。嚴(yán)格來(lái)說(shuō)這不是判斷邏輯的問(wèn)題而是圖片文件的真實(shí)格式問(wèn)題。穩(wěn)妥做法是用ImageIO.read()解析圖片通過(guò)ImageIO.getImageReaders()獲取真實(shí)格式再映射到POI的圖片類(lèi)型常量。如果項(xiàng)目里圖片來(lái)源可控都是程序生成的PNG用擴(kuò)展名判斷就夠了如果圖片是外部上傳的建議按真實(shí)格式判斷。5.5 生成的文件提示“要修復(fù)”的問(wèn)題排查思路如果你插入后生成的docx在Word里提示“發(fā)現(xiàn)無(wú)法讀取的內(nèi)容是否嘗試修復(fù)”別慌九成是XML結(jié)構(gòu)出了問(wèn)題。我的排查順序是先把生成的文件用解壓工具解壓打開(kāi)word/document.xml直接看新插入段落前后的XML標(biāo)簽是否閉合正常。段落嵌套層級(jí)不正確是最常見(jiàn)原因。檢查是不是游標(biāo)位置操作出了問(wèn)題比如在Body層級(jí)的段落外又插入了孤立節(jié)點(diǎn)或者插入到了一個(gè)表格單元格的非法位置。單獨(dú)跑一個(gè)最小復(fù)現(xiàn)用例只插入一張圖片、只操作一個(gè)占位符看能不能復(fù)現(xiàn)。能復(fù)現(xiàn)問(wèn)題就在插入邏輯不能復(fù)現(xiàn)說(shuō)明是模板本身有問(wèn)題。另外所有插入操作完成后記得調(diào)用一次doc.write()刷新內(nèi)部結(jié)構(gòu)再關(guān)閉輸出流。不要用doc.getDocument().toString()直接拼字符串查問(wèn)題那個(gè)是底層X(jué)ML的toString和實(shí)際寫(xiě)入文件的內(nèi)容不完全一樣。5.6 圖片流資源泄漏addPicture需要傳入InputStream如果你用裸寫(xiě)new FileInputStream()不關(guān)流批量生成文檔時(shí)容易出現(xiàn)文件句柄耗盡或文件被占用刪除不掉。上面代碼全用了try-with-resources這個(gè)習(xí)慣一定要帶上。尤其是在循環(huán)內(nèi)插入幾十張圖片的場(chǎng)景不關(guān)流的后果會(huì)非常明顯。6. 批量插入場(chǎng)景的性能優(yōu)化與模板復(fù)用最后一個(gè)常見(jiàn)場(chǎng)景一份文檔里要插入幾十張圖比如產(chǎn)品目錄、員工證件照集合、訂單截圖列表。按前面的單張插入方法每張圖都從頭遍歷整篇文檔找錨點(diǎn)復(fù)雜度是O(n*m)文檔段落很多時(shí)會(huì)明顯變慢。這個(gè)環(huán)節(jié)給幾個(gè)優(yōu)化思路。6.1 一次性收集錨點(diǎn)避免反復(fù)全表掃描不管插入多少?gòu)垐D先做一次遍歷把占位符和對(duì)應(yīng)的圖片路徑配對(duì)收集起來(lái)然后再統(tǒng)一處理。可以用一個(gè)小結(jié)構(gòu)class ImageAnchor { String placeholder; String imagePath; XWPFParagraph anchor; }遍歷時(shí)只掃一遍所有段落含表格把每個(gè)占位符對(duì)應(yīng)的段落引用存下來(lái)。這樣后續(xù)插入直接拿對(duì)象操作不需要反復(fù)從頭找。插入新段落時(shí)注意底層X(jué)ML是動(dòng)態(tài)變化的但你已經(jīng)拿到的XWPFParagraph對(duì)象引用依然有效因?yàn)樗腔贑TP包裝的不會(huì)因?yàn)椴迦胄露温涠А?.2 “可反復(fù)運(yùn)行”的冪等處理真實(shí)業(yè)務(wù)里往往要求同一個(gè)模板重復(fù)生成多份文檔比如批量套打證書(shū)。如果模板里的占位符被第一次運(yùn)行改掉第二次想再?gòu)?fù)用同一份模板文檔就會(huì)發(fā)現(xiàn)占位符沒(méi)了。我的做法是每次生成前都從原始模板重新加載一份副本占位符永遠(yuǎn)以原始模板為準(zhǔn)。生成流程變成三條固定步驟new XWPFDocument(templateInputStream)加載原始模板查占位符、插入圖片、清理占位符輸出寫(xiě)入新的docx文件模板文件只讀絕不寫(xiě)入。這樣無(wú)論跑多少次模板永遠(yuǎn)是干凈的。6.3 線程安全的取舍XWPFDocument不是線程安全的同一個(gè)模板對(duì)象多線程操作會(huì)互相干擾。如果并發(fā)量高要么每個(gè)線程各自加載一份模板副本要么用線程池串行化處理同一模板的生成任務(wù)。最省事的做法是把模板內(nèi)容readAllBytes()讀進(jìn)字節(jié)數(shù)組每次new XWPFDocument(new ByteArrayInputStream(bytes))生成新實(shí)例。模板不大時(shí)開(kāi)銷(xiāo)可以忽略換來(lái)的是完全隔離不用加鎖。6.4 不要邊遍歷邊改結(jié)構(gòu)的深層原因有些操作在循環(huán)內(nèi)直接用doc.getParagraphs()并同時(shí)調(diào)用insertNewParagraph這背后的隱患不只是索引偏移XMLBeans的游標(biāo)遍歷邏輯在節(jié)點(diǎn)增刪過(guò)程中有時(shí)會(huì)拋出ConcurrentModificationException有時(shí)會(huì)靜默跳過(guò)新插入節(jié)點(diǎn)導(dǎo)致插入順序錯(cuò)亂。把“收集”和“操作”分成兩階段不僅是性能考慮更是規(guī)避這類(lèi)詭異問(wèn)題的根本手段。我在批量插入場(chǎng)景里統(tǒng)一遵守一個(gè)規(guī)則收集階段只return段落引用操作階段只使用已收集到的引用做插入絕不在遍歷的同時(shí)修改文檔結(jié)構(gòu)。這套思路跑下來(lái)上百?gòu)垐D片的文檔生成也穩(wěn)定。如果你也要做類(lèi)似功能建議先把這個(gè)原則定下來(lái)再寫(xiě)業(yè)務(wù)代碼。