简介这份资源围绕 docx4j 与 docx4j-ImportXHTML 实现 HTML 转 Word 展开面向具备一定 Java 基础、需要处理办公文档自动化的开发者尤其适合在报表生成、合同填充、内容复用等场景中遇到格式转换难题的技术人员。压缩包共 170 个文件约 16.71MB以 132 个 xml 配置与映射文件、10 个 java 源码、10 个 class 编译文件为主另含 8 个 html 模板、3 个 ttf 字体及 yaml、md 等辅助文件覆盖模板准备、内容填充、格式转换到页眉页脚、页码水印、目录增强的完整链路并延伸出 HTML 经 Word 再导出 PDF 的思路。已有 761 人学习下载可帮助读者理解占位符替换、XHTML 解析为 Word XML 结构、字体段落列表表格转换规则等关键环节快速搭建可运行的转换工程并排查常见格式兼容问题。1. 用 docx4j 把 HTML 转成 Word为什么“所见即所得”总在表格和样式上翻车做过文档导出的同学大概率都踩过这个坑前端富文本编辑器里排版漂漂亮亮的 HTML一导出成 Word 就面目全非——表格边框没了、字体全变成宋体、行距乱成一团。很多人第一反应是换个库试过 POI、试过各种在线转换服务最后发现要么样式丢失严重要么对复杂 HTML 支持太差。docx4j 配合 docx4j-ImportXHTML 这套组合是目前 Java 生态里处理 HTML 转 Word 相对靠谱的方案之一它基于 OOXML 标准直接操作 docx 的 XML 结构对 CSS 的支持比纯 POI 手写要完整得多。这套方案适合谁适合需要在服务端批量生成 Word 报告、合同、通知类文档的后端开发者尤其是 HTML 来源是富文本编辑器比如常见的富文本组件或者模板引擎渲染结果的场景。它解决的核心问题是把一段结构化的 HTML 片段连同内联样式和基础 CSS尽可能保真地塞进一个符合 Word 规范的 docx 文件里。但要注意它不是什么都能转理解它的能力边界比会调 API 更重要下面从环境搭建一路讲到踩坑排查。2. 环境搭建与最小可运行示例从零跑通第一次转换2.1 依赖选型为什么是 docx4j 而不是 POI 的 XWPF先说选型理由。Apache POI 的 XWPF 组件确实能创建 Word 文档但它对 HTML 的解析基本等于没有你得自己写 HTML 解析器再把每个标签手动映射成 XWPF 的段落、表格对象工作量巨大且容易漏样式。docx4j 本身是一个成熟的 OOXML 操作库而 docx4j-ImportXHTML 是它的一个扩展模块专门负责把 XHTML 转成 docx4j 的文档对象模型。它的转换链路是HTML 字符串 → 用 XML 解析器解析成 XHTML DOM → 遍历 DOM 节点 → 映射成 docx4j 的 JAXB 对象 → 序列化成 docx。这个链路决定了两个关键点第一你的 HTML 必须是格式良好的 XHTML标签必须闭合否则解析阶段就挂了第二CSS 支持是有限度的它主要认内联 style 和一部分基础选择器复杂的外部样式表基本不认。所以选它的前提是你能控制 HTML 的生成质量或者愿意在转换前做一轮 HTML 清洗。依赖方面Maven 项目里通常需要引入 docx4j-core、docx4j-ImportXHTML以及它们依赖的 JAXB 实现。注意 docx4j 对 JDK 版本有要求JDK 8 和 JDK 11 在 JAXB 依赖上处理方式不同JDK 11 以后 JAXB 被移出标准库需要额外引入。下面是一个典型的 Maven 依赖配置。dependencies !-- docx4j 核心操作 OOXML 文档对象 -- dependency groupIdorg.docx4j/groupId artifactIddocx4j-core/artifactId version11.4.9/version /dependency !-- ImportXHTML 模块负责 HTML 到 docx4j 对象的转换 -- dependency groupIdorg.docx4j/groupId artifactIddocx4j-ImportXHTML/artifactId version11.4.9/version /dependency !-- JDK 11 需要手动补 JAXBJDK 8 可省略 -- dependency groupIdjakarta.xml.bind/groupId artifactIdjakarta.xml.bind-api/artifactId version2.3.3/version /dependency dependency groupIdorg.glassfish.jaxb/groupId artifactIdjaxb-runtime/artifactId version2.3.3/version /dependency /dependencies版本号这里给的是一个较稳定的参考值实际项目里建议锁定团队验证过的版本不要盲目追新。docx4j 各模块版本要一致core 和 ImportXHTML 版本不一致是常见的 NoSuchMethodError 来源。2.2 最小转换代码把一段 HTML 塞进 docx环境就绪后先跑通一个最小示例。核心 API 是XHTMLImporterImpl它接收一个WordprocessingMLPackage对象和一个 HTML 字符串调用convert()方法返回段落列表再把这些段落追加到文档主体里。import org.docx4j.Docx4J; import org.docx4j.convert.in.xhtml.XHTMLImporterImpl; import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import org.docx4j.openpackaging.parts.WordprocessingML.MainDocumentPart; import java.io.File; public class HtmlToWordDemo { public static void main(String[] args) throws Exception { // 1. 创建一个空的 docx 包相当于新建一个 Word 文档 WordprocessingMLPackage wordMLPackage WordprocessingMLPackage.createPackage(); MainDocumentPart mainPart wordMLPackage.getMainDocumentPart(); // 2. 准备待转换的 HTML注意必须是格式良好的 XHTML String html htmlbody h1 stylecolor:#2c3e50;季度运营报告/h1 p stylefont-size:14px;line-height:1.6;本季度整体表现strong稳中有升/strong 其中华东区域贡献了主要增量。/p table border1 styleborder-collapse:collapse;width:100%; trth stylebackground:#f0f0f0;区域/thth销售额/th/tr trtd华东/tdtd1280/td/tr trtd华南/tdtd960/td/tr /table /body/html; // 3. 创建导入器绑定目标文档包 XHTMLImporterImpl importer new XHTMLImporterImpl(wordMLPackage); // 设置图片等资源的存放目录没有图片可忽略 importer.setHyperlinkStyle(Hyperlink); // 4. 执行转换得到 docx4j 的段落对象列表 mainPart.getContent().addAll(importer.convert(html, null)); // 5. 保存为 docx 文件 wordMLPackage.save(new File(output.docx)); System.out.println(转换完成); } }这段代码的逻辑很直白建包、备料、转换、落盘。convert()的第二个参数是 base URL用于解析 HTML 里的相对路径资源比如图片的 src如果 HTML 里没有相对路径引用传 null 即可。转换结果是一个ListObject里面是 docx4j 的 JAXB 对象直接 addAll 到主文档部分就行。跑通之后你会看到标题颜色、加粗、表格边框基本都保留下来了。但别高兴太早这只是理想情况真实业务里的 HTML 往往带着一堆外部 CSS 类名、嵌套 div、浮动布局这时候转换结果就开始玄学了。2.3 关键参数字号、字体、页面设置怎么调默认转换出来的文档字体和字号往往不符合国内文档习惯。docx4j 转换时会尽量映射 CSS 的 font-family 和 font-size但 CSS 里没写的话它会用 Word 默认值。国内报告类文档通常要求正文宋体小四、标题黑体这些需要在转换前对 HTML 做样式注入或者转换后对 docx 对象做二次处理。一个实用做法是在 HTML 的 body 上挂一个全局 style把基础字体定下来String html htmlbody stylefont-family:SimSun;font-size:12pt; h1 stylefont-family:SimHei;font-size:16pt;标题/h1 p正文内容/p /body/html;注意 font-size 用 pt 而不是 pxWord 对 pt 的识别更准确px 会被按 96 DPI 换算容易出现 10.5pt 这种奇怪的字号。页面设置页边距、纸张大小不在 HTML 里控制需要在WordprocessingMLPackage上通过 sectPr 设置或者干脆用一个预置的空白模板 docx 作为底稿把页面设置提前配好转换时只往里塞内容。// 加载预置模板页面设置已在模板里配好 WordprocessingMLPackage wordMLPackage WordprocessingMLPackage.load(new File(template.docx));用模板底稿是个好习惯能避免每次转换都去调页面参数也方便统一公司文档规范。3. 样式映射与表格处理让转换结果接近预期3.1 CSS 支持边界哪些样式认哪些直接丢docx4j-ImportXHTML 对 CSS 的支持是“够用但不完整”。根据实际测试它比较可靠支持的有color、background-color、font-family、font-size、font-weight、font-style、text-decoration、text-align、border简写和分写都认一部分、padding、margin、width、height、vertical-align。这些基本能覆盖富文本编辑器的常见输出。但下面这些它基本不认或者支持很差float、position、display:flex、display:grid、复杂的伪类选择器:hover、:nth-child、CSS 变量、媒体查询。这意味着如果你的 HTML 是用现代前端框架渲染的、依赖 flex 布局的页面直接转基本会散架。常见做法是转换前做一轮 HTML 降级把 flex 布局改成 table 布局或者简单的块级堆叠把外部 CSS 内联化。内联化这一步很关键。很多富文本编辑器输出的 HTML 是带 class 的样式在style标签或者外部文件里。docx4j 对style标签里的选择器支持有限最稳妥的是用工具把 CSS 内联到每个元素的 style 属性上。Java 侧可以用 jsoup 配合一些 CSS 内联库或者在前端导出前就做好内联。// 用 jsoup 做一轮清洗补全闭合标签、移除脚本、内联基础样式 import org.jsoup.Jsoup; import org.jsoup.nodes.Document; import org.jsoup.nodes.Entities; String rawHtml div classcontentp文本br换行/div; Document doc Jsoup.parse(rawHtml); doc.outputSettings().syntax(Document.OutputSettings.Syntax.xml); // 输出为 XHTML doc.outputSettings().escapeMode(Entities.EscapeMode.xhtml); String cleanHtml doc.body().html();jsoup 这步的价值在于把不规范的 HTML未闭合的 br、div整理成格式良好的 XHTML同时可以顺手移除 script、iframe 这些 docx4j 处理不了的标签。Syntax.xml这个设置必须加否则 jsoup 默认输出 HTML 语法docx4j 解析时可能报错。3.2 表格转换边框、合并单元格与列宽控制表格是 HTML 转 Word 最容易翻车的地方。HTML 表格的边框靠 CSS 的 border 和 border-collapse 控制而 Word 表格的边框是定义在单元格属性里的。docx4j 会尝试把 CSS border 映射过去但 border-collapse:collapse 这种合并边框模式它处理得不完美经常出现双线或者部分边框丢失。血泪经验是与其依赖 CSS 边框不如在 HTML 表格上直接用 border 属性并且给每个 td 都写上边框样式别指望从 table 继承。table border1 cellspacing0 cellpadding4 styleborder-collapse:collapse;width:100%;table-layout:fixed; tr td styleborder:1px solid #333;width:30%;区域/td td styleborder:1px solid #333;width:70%;销售额/td /tr /tabletable-layout:fixed配合每个 td 的 width 百分比能让 Word 里的列宽更接近预期。如果不写Word 会按内容自动撑开长文本会把列挤变形。合并单元格方面docx4j 支持 colspan 和 rowspan但 rowspan 在跨页时容易出现边框错位建议能不用就不用或者控制表格不要跨页。列宽还有一个坑Word 的列宽单位是 twips1/20 磅docx4j 会做换算但换算结果受页面可用宽度影响。如果表格总宽超过页面宽度Word 会强行压缩导致列宽和 HTML 里设的对不上。稳妥做法是表格宽度设成 100%让各列按比例分配而不是写死像素值。3.3 图片与超链接资源路径和样式名HTML 里的图片转 Worddocx4j 需要能读到图片的二进制数据。如果 img 的 src 是网络 URL它会在转换时去下载如果是相对路径需要配合 convert 方法的 base URL 参数。生产环境里更推荐先把图片下载到本地临时目录把 src 改成绝对文件路径或者 file URI避免转换时网络超时。// 图片用绝对路径避免相对路径解析失败 String html p示意图/pimg srcfile:///data/tmp/chart.png stylewidth:400px;/; XHTMLImporterImpl importer new XHTMLImporterImpl(wordMLPackage); // 第二个参数传 null因为 src 已是绝对路径 mainPart.getContent().addAll(importer.convert(html, null));图片的 width 样式会被映射成 Word 图片的显示尺寸但要注意 DPI 换算HTML 里的 px 和 Word 里的实际尺寸有偏差必要时转换后用 docx4j 的 API 遍历图片对象手动调整 extent。超链接方面docx4j 会把a标签转成 Word 的超链接但样式依赖一个叫 Hyperlink 的字符样式。如果目标文档里没有这个样式链接会显示成普通文本。解决办法是在模板底稿里预置好 Hyperlink 样式或者转换后手动给链接文本加下划线和蓝色。4. 避坑与排查那些让转换结果失控的细节4.1 中文乱码编码不一致的连锁反应现象转换出来的 Word 里中文变成问号或者方块。原因通常是 HTML 字符串的编码和解析时声明的编码不一致。docx4j 内部用 XML 解析器处理 HTML如果 HTML 头部没有声明编码或者声明的是 GBK 而实际字符串是 UTF-8就会乱码。解决确保 HTML 字符串本身是 UTF-8并且在 HTML 头部显式声明meta charsetUTF-8/Java 侧读取源文件时也统一用 UTF-8。4.2 样式丢失外部 CSS 没被识别现象HTML 里明明写了样式转出来却是白底黑字无格式。原因多半是样式写在style标签的选择器里而 docx4j 对选择器匹配支持有限尤其是类选择器和后代选择器。解决转换前用工具把 CSS 内联到元素 style 属性上或者直接在生成 HTML 时就写内联样式。这是最省心的做法别跟选择器较劲。4.3 内存溢出大文档批量转换的隐患现象转换几百页的 HTML 或者批量循环转换时抛 OutOfMemoryError。原因是 docx4j 会把整个文档对象模型加载到内存HTML 越大、图片越多内存占用越高。解决单文档转换后及时释放引用批量场景下控制并发数必要时分章节转换再合并。JVM 参数适当调大堆内存但根治还是靠控制单次转换的文档规模。4.4 表格跨页断行错乱现象表格内容多跨页后边框消失或者行高异常。原因是 Word 表格跨页时的渲染规则和 HTML 不同docx4j 生成的表格属性没设置好跨页行为。解决给表格行设置cantSplit属性防止单行跨页断开或者接受跨页但确保边框定义在每个单元格上而不是表格级别。复杂长表格建议拆成多个小表格。4.5 版本冲突导致 NoSuchMethodError现象运行时报 NoSuchMethodError 或 ClassNotFoundException指向 docx4j 内部类。原因是 docx4j-core 和 docx4j-ImportXHTML 版本不一致或者项目里混入了其他版本的 JAXB。解决用 mvn dependency:tree 排查依赖树强制统一 docx4j 各模块版本排除冲突的 JAXB 传递依赖。5. 进阶技巧模板底稿 后处理把转换结果打磨到能交付跑通基础转换只是第一步真正要交付给业务方还得在“底稿”和“后处理”上做文章。我一般会准备一个 template.docx 作为底稿里面预置好页面尺寸、页边距、页眉页脚、以及 Hyperlink、标题 1、标题 2 这些命名样式。转换时加载这个模板把 HTML 转出来的内容追加进去这样出来的文档天然符合公司规范不用每次调页面参数。后处理主要解决两类问题一是转换后样式微调二是补充 HTML 表达不了的元素。比如页码、目录、水印这些 HTML 里没有对应概念得在 docx 对象上操作。docx4j 提供了遍历文档对象的能力可以定位到特定段落改字体或者往页脚里插入页码字段。// 后处理示例遍历所有段落把字体统一兜底为宋体 import org.docx4j.wml.*; import org.docx4j.jaxb.Context; ObjectFactory factory Context.getWmlObjectFactory(); ListObject paragraphs mainPart.getContent().stream() .filter(o - o instanceof P) .collect(java.util.stream.Collectors.toList()); for (Object obj : paragraphs) { P p (P) obj; // 获取或创建段落属性 PPr pPr p.getPPr() ! null ? p.getPPr() : factory.createPPr(); RPr rPr factory.createRPr(); RFonts fonts factory.createRFonts(); fonts.setAscii(SimSun); fonts.setEastAsia(SimSun); // 中文字体必须设 eastAsia rPr.setRFonts(fonts); pPr.setRPr(rPr); p.setPPr(pPr); }这段代码的关键点是setEastAsia中文字体在 OOXML 里是单独用 eastAsia 属性控制的只设 ascii 字体对中文不生效这是很多人调字体调不出来的根本原因。遍历段落做统一兜底能解决 HTML 里没写字体时的默认字体问题。另一个进阶点是分节处理。如果一份文档里既有横向页面又有纵向页面或者需要不同的页眉就得用分节符。docx4j 支持创建 sectPr但操作起来比较繁琐建议在模板底稿里把分节结构搭好转换时按节填充内容。验证转换结果是否合格我习惯用三步第一步用 Word 打开看整体排版重点看表格和图片第二步用 docx4j 反向读取检查段落数、表格数是否符合预期第三步把 docx 另存为 PDF看分页和字体嵌入是否正常。PDF 那一步能暴露很多 Word 里看不出来的字体缺失问题。最后说个习惯每次调整转换逻辑后留一组固定的测试 HTML 样本覆盖标题、段落、加粗斜体、表格、图片、超链接、中英文混排这几种情况改完就跑一遍对比输出。HTML 转 Word 这活儿玄学时刻不少靠固定样本回归比靠肉眼靠谱得多。希望帮到你。本文还有配套的精品资源点击获取