简介这是一份面向Java开发者的工程示例资源演示如何基于docx4j与docx4j-ImportXHTML实现HTML内容向Word文档的自动转换特别适合需要批量生成合同、导出报表或维护跨格式文档的办公自动化场景。压缩包共170个文件约16.71MB包含10个Java源码及对应编译后的class文件、132个XML配置与Word文档定义、8个HTML模板、3个TTF字体文件等其中Java代码负责转换流程与样式处理XML和HTML模板用于预设文档结构字体文件则保障中文字体兼容。资源已有761人学习整体结构清晰既可直接运行调试也可作为二次改造的完整蓝本。通过阅读源码可掌握docx4j核心API调用、XHTML解析规则、占位符替换以及页眉页脚设置同时可参考PDF导出相关的扩展实现理解从HTML到Word再到PDF的完整转换链路并为生成带水印、目录的正式文档提供起点。1. 用 docx4j docx4j-ImportXHTML 把 HTML 转 Word这个方案到底解决什么问题如果你和我一样经常被“把网页上的合同、报告、工单导成 Word”这种需求找上门多半会先想到前端用html-docx-js、后端用 Apache POI或者干脆让用户自己 CtrlC。可一旦页面里有表格、图片、标题层级前端方案的 Word 结构往往很乱POI 手工拼段落又能把人写疯。这时候用 docx4j 配合 docx4j-ImportXHTML 把 HTML 转成真正的 .docx是 Java 后端最稳妥的一条路它把 HTML 的标题、段落、表格、图片映射成 Word 原生对象而不是塞一幅截图或一堆纯文本。适合已经跑在 Java 技术栈、需要批量导出 Word并且不想被 LibreOffice 转换依赖拖累的团队。2. 跑通最小转换依赖怎么配、第一个 Java 方法怎么写2.1 依赖选型docx4j-ImportXHTML 与 docx4j 版本为什么要对齐docx4j 是操作 .docx 的 Java 库而 docx4j-ImportXHTML 是它的一个转换模块负责把 XHTML 解析成 docx4j 能识别的对象树。网上经常有人问“js生成word文档有哪些js库”如果你前端已经跑在 Node 系那另说但后端是 Java 的时候docx4j 的稳定性、对 Word 原生特性的支持程度比大多数 JS 库更接近“真 Word”。这里有个最容易踩的坑docx4j-ImportXHTML 和 docx4j 的版本必须严格对齐。它不是一个独立演进的库而是跟着 docx4j 主版本走。如果你用 docx4j 8.2.x却拉了一个 6.x 的 ImportXHTML运行时大概率出现 NoSuchMethodError 或 LinkageError。常见的 Maven 坐标是这样dependency groupIdorg.docx4j/groupId artifactIddocx4j/artifactId version8.3.10/version /dependency dependency groupIdorg.docx4j/groupId artifactIddocx4j-ImportXHTML/artifactId version8.3.10/version /dependency参数说明8.3.10这个版本号不是固定必须但两个 artifact 的 version 要完全一致。如果你用 Spring Boot还要注意 docx4j 依赖的commons-logging、javax.xml.bind是否和你项目里的旧版本冲突。一个建议是新建一个最小的 Java 工程先跑通再往正式项目里引不要一上来就把所有依赖都堆进去。2.2 最小转换代码XHTMLImporterImpl 的调用方式和两个参数第一步别想复杂先拿一个最简单的 HTML 字符串试水。需要说明的是docx4j-ImportXHTML 这个模块名字里写着 HTML但它内部要求你给的是格式良好的 XHTML。实际工作中我一般会先用 Jsoup 把真实页面清洗成规范 XHTML再丢给转换器。下面是能跑通的最小代码import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import org.docx4j.convert.in.xhtml.XHTMLImporterImpl; import java.io.File; import java.util.List; public class HtmlToWordDemo { public static void main(String[] args) throws Exception { // 1. 创建一个空的 Word 包 WordprocessingMLPackage wordMLPackage WordprocessingMLPackage.createPackage(); // 2. 创建 XHTML 转换器 XHTMLImporterImpl importer new XHTMLImporterImpl(wordMLPackage); // 3. 准备 XHTML 内容 String xhtml html xmlnshttp://www.w3.org/1999/xhtml headmeta charsetutf-8//head body h1标题一/h1 p这是 b加粗/b 段落。/p table border1trtd单元格/td/tr/table /body/html; // 4. 转换convert(xhtml, baseURL) 返回一组 Word 对象 ListObject convertedObjects importer.convert(xhtml, null); // 5. 把转换结果挂到主文档正文 wordMLPackage.getMainDocumentPart().addObject(convertedObjects); // 6. 保存 wordMLPackage.save(new File(demo.docx)); } }逻辑说明第 1 步先创建空包它相当于一个空白 Word 文档第 2 步的XHTMLImporterImpl是核心转换器构造时要求传入目标包因为它需要知道往哪个文档里放内容第 4 步的convert返回的不是文件而是一个ListObject里面是 docx4j 的段落、表格等对象第 5 步把它整体加到正文里。参数说明convert的第二个参数是baseURL这里传null表示不解析相对路径。如果你的 HTML 里图片地址是images/logo.png就要把页面所在目录的 URI 传进来否则图片会丢。后面专门讲图片。2.3 转换完怎么验证读回 DOCX 检查段落与文本很多坑是在保存之后才暴露的比如文本变成乱码、表格只有一列。所以“转换完成”不等于“结果正确”。我习惯跑完立刻把 docx 读回来用 docx4j 的 API 抽文本做断言能自动化检查就自动化。下面是一个简单的文本抽取方法import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import org.docx4j.wml.P; import org.docx4j.wml.R; import org.docx4j.wml.Text; import java.io.File; import java.util.List; public class DocxTextExtractor { public static String extractText(File docxFile) throws Exception { WordprocessingMLPackage wordMLPackage WordprocessingMLPackage.load(docxFile); StringBuilder sb new StringBuilder(); ListObject content wordMLPackage .getMainDocumentPart().getContent(); for (Object obj : content) { if (obj instanceof P) { P paragraph (P) obj; for (Object child : paragraph.getContent()) { if (child instanceof R) { R run (R) child; for (Object rChild : run.getContent()) { if (rChild instanceof Text) { sb.append(((Text) rChild).getValue()); } } } } sb.append(\n); } } return sb.toString(); } public static void main(String[] args) throws Exception { String text extractText(new File(demo.docx)); if (text.contains(标题一) text.contains(单元格)) { System.out.println(内容完整); } else { System.out.println(内容缺失: text); } } }逻辑说明docx 的本质是一堆 XMLP是段落R是 run一段连续格式的文本片段Text才是最终存的字符串。这里按层级向下取只处理了顶层段落如果文本在表格里需要递归进入表格的每一行每一格。你可以把recursive写成递归方法这里先演示最小思路。参数说明wordMLPackage.load加载的同时会做 OOXML 校验如果你的文件是拿文本编辑器改后缀造出来的假 docx这一步会直接报错。所以这个验证方法本身也是在检查产物结构的合法性。3. HTML 样式与 Word 格式的映射CSS 能转多少、页面参数怎么给3.1 docx4j-ImportXHTML 支持的 CSS 子集内联 style 能转class 大概率丢如果你做过 Markdown 转 Word会发现很多转换器是“能转但样式别指望”。docx4j-ImportXHTML 稍微好一点它会读标签里的stylefont-size: 16px; color: red;这类内联样式生成对应的 Word run 属性。但它并不像浏览器那样去解析完整的 CSS 渲染。style块里的 class 选择器比如.red { color: red; }在很多版本下不会生效因为转换器只做了有限的 CSS 规则映射不会实现“类名查找”。我常用的做法是如果页面是公司内部的模板尽量在服务端拿到的 HTML 里就把关键样式写成内联 style如果是外部页面先用 Jsoup 解析再把需要保留的 class 逐个转成内联样式。这一步虽然烦但比事后打开 Word 发现一片黑字再回头调容易。下面是能转的核心 CSS/HTML 对照表也是我长期用的边界清单HTML/CSS 元素转换结果说明p、h1~h6Word 段落标题会带 outline level可在导航窗格看到b、strong、i、em加粗、斜体常见稳定font-size、font-family字号、字体支持 px、pt但 pt 更贴近 Wordcolor、background-color字体颜色、底纹有的版本背景色只支持段落级text-align段落对齐支持 left/center/right/justifytable、tr、tdWord 表格不完整支持合并单元格见 4.1ul、ol、li列表有缩进但项目符号样式可能变img图片需要处理 src 来源见 3.3a[href]超链接基本可转但样式需自己调div普通段落或容器常被忽略内容并入段落spanrun依赖内部样式解析flex/grid/float/absolute丢布局类 CSS 一律不支持注意这张表不是官方承诺是边界实际表现。也就是说你拿一个复杂 Vue 页面直接转出来的 Word 可能跟你浏览器里看到的完全两样。这个方案的适用场景是“内容型文档”不是“还原型排版”。3.2 预设 A4 页面、页边距和默认字体的代码很多时候客户要求导出 Word 必须 A4、页边距上下 2.54cm、正文宋体五号。docx4j-ImportXHTML 转换时不会帮你设页面你需要在转换前自己设置对象包。实际操作是拿到正文的sectPr改页面尺寸和边距import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import org.docx4j.wml.ObjectFactory; import org.docx4j.wml.PgSz; import org.docx4j.wml.PgMar; import org.docx4j.wml.SectPr; import java.math.BigInteger; public class PageSetup { public static void setupA4(WordprocessingMLPackage wordMLPackage) { ObjectFactory factory new ObjectFactory(); SectPr sectPr wordMLPackage.getMainDocumentPart() .getContents().getBody().getSectPr(); if (sectPr null) { sectPr factory.createSectPr(); } // A4 纵向宽 210mm高 297mmtwips 单位 PgSz pgSz factory.createPgSz(); pgSz.setW(BigInteger.valueOf(11906)); pgSz.setH(BigInteger.valueOf(16838)); sectPr.setPgSz(pgSz); // 页边距上下 2.54cm左右 3.18cm1cm ≈ 567 twips PgMar pgMar factory.createPgMar(); pgMar.setTop(BigInteger.valueOf(1440)); pgMar.setBottom(BigInteger.valueOf(1440)); pgMar.setLeft(BigInteger.valueOf(1800)); pgMar.setRight(BigInteger.valueOf(1800)); sectPr.setPgMar(pgMar); wordMLPackage.getMainDocumentPart() .getContents().getBody().setSectPr(sectPr); } public static void main(String[] args) throws Exception { WordprocessingMLPackage wordMLPackage WordprocessingMLPackage.createPackage(); setupA4(wordMLPackage); wordMLPackage.save(new File(page-setup.docx)); } }逻辑说明Word 内部用 twips 作为长度单位1 厘米约等于 567 twips1 英寸等于 1440 twips。所以上下 2.54cm 就是 1440 twips左右 3.18cm 约是 1800 twips。sectPr是正文的节属性负责所有页面设置。参数说明如果你的文档还要分节、每节不同页边距那要操作body.getSectPr()之外的其他节对象这里只做单节处理。页面设置要在转换前还是后做都行因为它影响的是整个 Word 文档的属性不影响内容对象。3.3 图片的三条落地路径本地文件、Base64 与网络图片HTML 里图片是最容易让转换翻车的元素。docx4j-ImportXHTML 在转换时遇到img会尝试把 src 读成二进制流插到 docx 的 media 目录。但 src 有三种形式处理方式完全不同。第一种是相对路径比如srcimages/logo.png。此时 convert 的第二个参数baseURL要传入包含图片的目录 URL通常new File(src/main/resources).toURI().toString()这样。第二种是 Base64 的 data URIsrcdata:image/png;base64,iVBOR...这种 docx4j 能直接解码但生成的 docx 明显变大几十张图能多出好几兆。第三种是网络绝对 URLhttps://...docx4j-ImportXHTML 默认不会去下载网络图片你需要先把图片下载到本地临时目录再改 src 为本地路径或转成 base64。常见的做法是写一个图片预处理函数import org.jsoup.Jsoup; import org.jsoup.nodes.Document; import org.jsoup.nodes.Element; import java.io.File; import java.io.FileOutputStream; import java.io.InputStream; import java.net.URL; public class ImagePreprocess { public static String downloadImagesToLocal(String html, String downloadDir) throws Exception { Document doc Jsoup.parse(html); for (Element img : doc.select(img)) { String src img.attr(src); if (src.startsWith(http://) || src.startsWith(https://)) { String fileName img_ System.nanoTime() .png; File target new File(downloadDir, fileName); try (InputStream in new URL(src).openStream(); FileOutputStream out new FileOutputStream(target)) { in.transferTo(out); } img.attr(src, target.getAbsolutePath()); } } return doc.html(); } }逻辑说明把网络图片下载到本地后还要把 HTML 里的 src 改成本地绝对路径然后再喂给 docx4j-ImportXHTML。参数说明downloadDir建议用系统的临时目录用完就删图片格式可以读Content-Type判断这里偷懒统一存 png 后缀只是演示。如果你是服务端导出接口还要考虑超时与失败降级——我一般会设置 5 秒连接超时下载失败就留一个占位图别让整个文档生成失败。4. 表格与列表的转换细节别再手动调列宽了4.1 table 转 Word 表colspan、rowspan 与列宽的已知问题表格是 Word 文档里最需要结构正确的部分而 docx4j-ImportXHTML 对复杂表格的转换一直是个薄弱点。简单表没问题tabletrtd...能生成 Word 表格。但合并单元格要提前评估有些版本支持colspan却能把它转成多个空单元格而不是真正的横向合并rowspan的支持更差很可能出现“行数对不上”的错位。我做过一次业务报表转换HTML 表头用了 rowspan 跨行转换后 Word 里的表格行列全乱了。后来我把原始 HTML 在服务端先做一层表格归一化能不用合并就不用合并必须合并时把合并信息在转换后用 docx4j 的 API 手动改。不要指望 ImportXHTML 帮你处理所有合并场景。列宽也是高频需求。很多人习惯在 HTML 里设width100但 docx4j-ImportXHTML 不一定会把这个宽度转成 Word 表格的列宽属性。结果是用户打开 Word 想拖动列宽却发现“word 表格列宽无法拖动”——这其实是表格被设成了固定布局或者各单元格宽度互相矛盾。给一个更稳妥的设置列宽的方法import org.docx4j.wml.Tbl; import org.docx4j.wml.Tc; import org.docx4j.wml.TcPr; import org.docx4j.wml.TblWidth; import org.docx4j.wml.ObjectFactory; import java.math.BigInteger; public class TableWidthFix { public static void setColumnWidth(Tc cell, int twipsWidth) { ObjectFactory factory new ObjectFactory(); TcPr tcPr cell.getTcPr(); if (tcPr null) { tcPr factory.createTcPr(); cell.setTcPr(tcPr); } TblWidth width factory.createTblWidth(); width.setW(BigInteger.valueOf(twipsWidth)); width.setType(dxa); // dxa 就是 twips tcPr.setTcW(width); } public static void main(String[] args) throws Exception { WordprocessingMLPackage pkg WordprocessingMLPackage.createPackage(); Tbl tbl (Tbl) pkg.getMainDocumentPart() .getContent().stream() .filter(o - o instanceof Tbl) .findFirst() .orElse(null); // 对每一行第一个单元格设置 3000 twips约 5.3cm if (tbl ! null) { tbl.getAllRows().forEach(row - row.getAllCells().forEach(cell - setColumnWidth(cell, 3000))); pkg.save(new File(fixed-table.docx)); } } }逻辑说明Word 表格列宽本质上存在每个单元格的tcW属性里typedxa表示单位是 twips。手动设置过之后用户在 Word 里拖动列宽就会正常。参数说明tbl.getAllRows()是 docx4j 封装好的方法方便遍历如果想让整列一致需要按列索引设置。这个做法是拿 poi 设置 word 表格单元格宽度 的同款思路与其依赖转换器不如直接改 OOXML 对象。4.2 列表和标题层级从 HTML 语义到 Word 大纲级别docx4j-ImportXHTML 对h1~h6会映射成 Word 的标题样式这算是个好消息因为 Word 导航窗格、目录生成都依赖大纲级别。但你需要注意它的标题转换可能只设置了大纲级别而没有绑定你公司模板里的“标题 1”“标题 2”样式名。换句话说生成的 Word 左边导航能看到层级但字号字体未必好看。ul和ol的转换类似它会生成带缩进的段落但项目符号可能不是你预期的圆点或数字。常见问题是多层嵌套列表的缩进不一致。我一般会在转换后遍历检查P对象如果发现列表缩进异常就手动改ind属性。这里给一个简易的缩进修正代码import org.docx4j.wml.P; import org.docx4j.wml.PPr; import org.docx4j.wml.Ind; import org.docx4j.wml.ObjectFactory; public class ListIndentFix { public static void setParagraphIndent(P paragraph, int twipsLeft) { ObjectFactory factory new ObjectFactory(); PPr ppr paragraph.getPPr(); if (ppr null) { ppr factory.createPPr(); paragraph.setPPr(ppr); } Ind ind ppr.getInd(); if (ind null) { ind factory.createInd(); ppr.setInd(ind); } ind.setLeft(BigInteger.valueOf(twipsLeft)); ind.setHanging(BigInteger.valueOf(0)); } }逻辑说明列表缩进在 Word 里由段落属性ind控制left是左边距hanging是悬挂缩进。如果你发现项目符号和文字挤在一起多半是hanging没设对。参数说明一层列表建议设left720约 1.27cm二层left1440左右。这个办法同样适用于普通段落的缩进控制。4.3 特殊字符与换行 、中文全角空格和空段落HTML 里的nbsp;多半会变成 Word 里的不间断空格表面上看起来是个空格但如果你做文本比较、或者用户删除它时会出现“删不掉”的诡异现象。另外中文全角空格在 HTML 里如果直接写 转换后可能保留原样也可能变成普通空格。我建议在转换前统一做一次字符归一化把nbsp;替换成普通空格把连续两个nbsp;替换成制表符或缩进。还有一个坑HTML 中p/p空段落转换后 Word 里是一个空的段落标记看起来空了一行。这虽然是正常现象但批量转换后你会发现文档里空行特别多。如果你希望严格控制版式可以在转换前用 Jsoup 删除多余的空白文本节点和空段落。代码大致是这样import org.jsoup.Jsoup; import org.jsoup.nodes.Document; import org.jsoup.nodes.Element; import org.jsoup.nodes.TextNode; public class HtmlCleaner { public static String cleanEmptyParagraphs(String html) { Document doc Jsoup.parse(html); // 删除只包含空白的文本节点 for (Element p : doc.select(p)) { p.childNodes().removeIf(node - node instanceof TextNode ((TextNode) node).text().trim().isEmpty()); if (p.text().isEmpty() p.children().isEmpty()) { p.remove(); } } return doc.html(); } }逻辑说明这段代码先删掉段落里的纯空白文本再删除空标签。注意只处理p不要误删pre里的空白那是代码块。参数说明Jsoup.parse会自动补全不闭合标签这也是为什么我推荐 Jsoup 做预处理但 Jsoup 输出的 XHTML 与 docx4j-ImportXHTML 的兼容性需要测试遇到特殊实体时可能要手动转义。5. 避坑docx4j-ImportXHTML 高频问题与排查方法5.1 内容缺失类乱码、图片不显示、样式全丢第一个高频问题是中文乱码或实体变成#x...;。现象转换出来的 Word 里看到的是#20013;#25991;这样的字符串。原因你传入的 HTML 字符串不是 UTF-8 编码或者从 HTTP 接口拿到的字节流没有按 UTF-8 解码。解决在转换入口统一做好编码声明比如用 Java 的new String(bytes, StandardCharsets.UTF_8)读页面同时确保 HTML 的meta charsetutf-8存在。第二个问题是图片不显示生成 Word 后图片位置是个空框。现象转出来的 docx 文件里只有空白占位没有图片。原因src是相对路径且没传baseURL或者图片已被下载但没有把 src 改成正确位置。解决按 3.3 节的方式先下载到本地再把 src 指向绝对路径。还有一个隐蔽点docx4j-ImportXHTML 对图片文件的扩展名敏感明明是个 jpg 但文件名是.png也可能导致图片解码失败。第三个问题是样式全丢。现象转换出来的 Word 全是默认字体、默认字号红色标题变黑。原因你用了写在style里的 class而当前版本的 ImportXHTML 只解析内联 style或者样式选择器写得太复杂。解决转换前用 Jsoup 遍历元素把需要保留的 CSS 属性写进style属性。不要试图在转换器里去支持 SCSS、后代选择器、伪类这些浏览器概念。5.2 运行异常类空指针、文件损坏、依赖冲突第四个高频异常是调用convert抛NullPointerException。现象当 HTML 是空字符串或null时转换器内部解析直接 NPE。原因docx4j-ImportXHTML 的 XHTML 清洗流程遇到空输入不会优雅降级。解决在进入转换前判空传一个html xmlnshttp://www.w3.org/1999/xhtmlbodyp//body/html作为兜底。第五个问题是生成的文件打不开Word 提示“文档内容损坏”。现象save成功但用户打开 docx 时弹错误。原因多半是你往getMainDocumentPart().addObject()里塞了不兼容的对象比如在同一个文档里重复添加了多个转换结果内部引用关系冲突或者用了旧版本的 docx4j 配合新版本的 ImportXHTML。解决先检查版本一致再检查你的转换结果是否包含不可序列化的自定义对象。如果问题依旧打开 docx 文件本质上是一个 zip查看[Content_Types].xml和document.xml的w:body部分看看是不是有w:altChunk或未闭合标签。排查命令很简单unzip damaged.docx然后用 XML 编辑器看word/document.xml。第六个是依赖冲突。现象项目里已经有 Apache POI启动时或转换时报org/apache/xmlbeans/XmlException之类。原因docx4j 和 POI 都会带各自的 XMLBeans 版本冲突后类加载器找到了旧类。解决用mvn dependency:tree -Dincludesorg.apache.xmlbeans查看版本强制统一到 docx4j 要求的版本。如果没法统一考虑把 HTML 转 Word 的服务独立成一个小模块避免污染主项目。6. 进阶把 HTML 转 Word 封装成批量服务并自动校验结果前面所有代码都是单次转换实际生产里往往要“一页一批”地转几十份。我会把转换流程拆成三步准备 XHTMLJsoup 清洗 图片下载 样式内联、调用XHTMLImporterImpl.convert生成对象、用 2.3 节的文本抽取做断言。第三步很多人忽略但它是自动化回归的关键。写一个批处理函数import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import org.docx4j.convert.in.xhtml.XHTMLImporterImpl; import java.io.File; import java.util.List; public class HtmlToWordService { public void batchConvert(ListSourceHtml sources) throws Exception { for (SourceHtml source : sources) { String cleanedHtml HtmlCleaner.cleanEmptyParagraphs( source.getHtml()); WordprocessingMLPackage wordMLPackage WordprocessingMLPackage.createPackage(); PageSetup.setupA4(wordMLPackage); XHTMLImporterImpl importer new XHTMLImporterImpl(wordMLPackage); ListObject objects importer.convert(cleanedHtml, null); wordMLPackage.getMainDocumentPart().addObject(objects); File outFile new File(source.getOutputPath()); wordMLPackage.save(outFile); String text DocxTextExtractor.extractText(outFile); if (!text.contains(source.getRequiredKeyword())) { throw new RuntimeException(转换缺失关键内容: source.getOutputPath()); } } } }逻辑说明批量转换时每个源都新建一个WordprocessingMLPackage避免前一个文档的节属性、页面设置污染下一个。如果一份 HTML 要生成多个不同模板的 Word可以把页面设置和样式内联做成前置拦截器这样转换器只负责内容映射。参数说明SourceHtml是你自己的数据类至少包含html、outputPath、requiredKeyword最后一个用于自动校验。我吃过最大的亏是上线后才发现某类页面里的rowspan全被转换成了空单元格而人工验收时只看了封面页。后来我在自动化校验里增加了一个“表格维度校验”——如果源 HTML 里表格有 5 行转换后的 Word 里必须能读出 5 行读不出来就报警。这比打开 Word 肉眼查可靠得多。另外如果客户要求 PDF 也一块出别用这个流程直接转 PDFdocx4j 的 PDF 导出需要额外加载字体和 HTML 转 Word 是两套问题。先把 Word 链路做稳定再考虑下游。希望这套“先清洗、再转换、后校验”的方法能帮你少走弯路。我用这个方案处理过上千份导出任务到现在仍然会在每个新版本 docx4j 上线前先跑一遍最小示例——依赖库升级翻车的概率远比业务代码改出 bug 的概率高。希望帮到你。本文还有配套的精品资源点击获取