如何将 HTML 转成 Word 文档且格式不丢失？html-to-docx 使用教程

如何将 HTML 转成 Word 文档且格式不丢失？html-to-docx 使用教程

【免费下载链接】html-to-docxHTML to DOCX converter项目地址: https://gitcode.com/gh_mirrors/ht/html-to-docx

html-to-docx 是一个 JavaScript 库，核心功能就是HTML 转 DOCX：把一段 HTML 字符串转成标准 Word 文档（.docx），支持 Word 2007+、WPS、Google Docs、LibreOffice 等主流办公软件打开。你不需要装 Office，也不需要复制粘贴，写几行代码就能拿到文件。

🧩 它解决的到底是什么问题？

直接把 HTML 复制进 Word，样式多半会碎掉：颜色没了、表格错位、图片只剩个空框。html-to-docx 的思路不同——它在内存里把 HTML 解析成虚拟 DOM，再逐节点映射成 Word 的 Office Open XML 结构，最后打包成一个真正的 .docx 压缩包。

• 样式：内联 CSS（颜色、背景、字体、字号、段落缩进）会被转成 Word 对应的属性
• 表格：colspan、rowspan、边框、单元格背景色都能保留
• 图片：支持 base64（data URI）和网络 URL 两种来源，自动下载并嵌入文档
• 列表：支持多级嵌套，有序列表还能自定义编号样式

核心逻辑在 src/html-to-docx.js（HTML 解析与参数归一化），文档结构由 src/docx-document.js 负责拼装，想看完整效果可以直接跑 example/ 里的脚本。

🚀 三步跑通：安装、调用、拿文件

第一步，装依赖：

npm install html-to-docx

第二步，调用唯一的转换函数。它接收 4 个参数：正文 HTML、页眉 HTML、文档选项、页脚 HTML，返回Promise<Buffer|Blob>：

const fs = require('fs'); const HTMLtoDOCX = require('html-to-docx'); const html = '<h1>标题</h1><p>正文内容，支持<strong>加粗</strong></p>'; HTMLtoDOCX(html, null, { font: '微软雅黑', fontSize: 11 }) .then((buffer) => fs.writeFileSync('out.docx', buffer));

第三步，打开out.docx检查效果。Node 环境拿到的buffer可以直接writeFile；在 React 这类浏览器环境里则拿Blob触发下载。

注意：项目主要在 Node.js 环境验证过，浏览器端仅在 React 中测试，建议先在后端跑通再考虑前端集成。

📄 HTML 转 DOCX 时，哪些格式能保留？

文字样式：<span style="color: #cc1177">这类内联颜色、字号、背景色都会映射到 Word；段落级样式如margin-left: 40px会变成段落缩进。font-family在 Word 桌面版表现最好，LibreOffice 和 Word Online 会自行替换字体，这是软件本身的差异，不是转换错误。

表格与分页：带合并单元格的复杂表格结构能完整还原。需要换页时，在 HTML 里插入一个专用 div 即可，注意该 div 内部的内容会被忽略：

<ol style="list-style-type: lower-alpha">const buffer = await HTMLtoDOCX(reportHTML, null, { orientation: 'landscape', // 横向纸张 margins: { top: '2cm', bottom: '2cm' }, header: true, footer: true, // 开启页眉页脚 pageNumber: true, // 页脚显示页码 table: { row: { cantSplit: true } }, // 表格行不跨页断开 title: '月度报告', creator: '报告系统', }); res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'); res.send(buffer);

几个值得知道的细节：

• 尺寸类参数（pageSize、margins）支持px、cm、inch字符串，内部自动换算成 Word 用的 TWIP
• fontSize单位是 pt，不传时默认Times New Roman、11pt
• 想控制拼写检查语言，设lang（如'zh-CN'）；HTML 里含&这类实体时开decodeUnicode: true
• 批量转换没有专门的 API，本质就是循环调用 + 并发控制，一次调用是独立无状态的

📝 常见坑，先踩过的帮你绕开

1. 分页不是自动的：只有div.page-break会触发换页，普通page-break-after写在别处不生效
2. 页码依赖页脚：pageNumber: true必须配合footer: true才有用
3. 字体跨软件不一致：同一份文档在 Word、LibreOffice 里字体可能不同，交付前建议在目标软件里过一眼
4. 输入要"干净"的 HTML：它是转换器不是渲染引擎，复杂的 CSS 布局（flex、grid）不会还原，简单文档效果最好

🏁 最后

如果你要做的只是"HTML 转 Word 保留格式"这一件事，html-to-docx 是目前依赖少、够轻量的选择：npm install之后一次函数调用，拿到 Buffer 就完事。先拿 example/example-node.js 跑一遍，确认你手上的 HTML 结构都能转对，再往业务流程里接。

【免费下载链接】html-to-docxHTML to DOCX converter项目地址: https://gitcode.com/gh_mirrors/ht/html-to-docx