简介：html-docx-js 是一个轻量级开源 JavaScript 库，专为前端开发者设计，用于在浏览器环境中将 HTML 内容无缝转换为标准 DOCX 文档，无需后端服务或 Office 依赖，适用于报表导出、在线文档生成、教学材料一键下载等场景。资源包共28个文件，涵盖核心功能的 CoffeeScript 源码（5个）、编译后 JS 文件（4个）、模板文件（3个 tpl）、配置与元数据（json/npmignore/gitignore 等共7个）、文档说明（md/html/License 共6个）及少量静态资源（css/jpg），整体仅160KB，结构清晰、开箱即用。已有4678人学习下载，体现了其在轻量文档导出方案中的实用价值。用户可直接运行 testbed.html 进行效果验证，通过阅读 README.md 和 CHANGELOG.md 快速掌握 API 使用方式；源码分层明确（src 下含 utils/internal/api 三类 Coffee 文件），配合 vendor 目录与 gulp 构建流程，便于二次开发与深度定制。
1. html-docx-js：不碰后端、不传服务器，纯前端把 HTML 表格/列表/样式秒转 DOCX 的实战方案
你有没有遇到过这种场景：用户在网页里填完一份带格式的报告（含表格、加粗标题、有序列表、行内图片），点“导出 Word”按钮，结果弹出的是个丑得没法交差的.txt或.html文件？或者更糟——前端把 HTML 发给后端，后端用 Python 的python-docx或 Java 的Apache POI拼 DOCX，结果一并发就超时、图片乱码、样式全丢？html-docx-js 就是专治这个病的「浏览器原生解药」：它不依赖任何服务端渲染，不走 API 请求，所有转换逻辑都在用户本地浏览器里跑完，生成的.docx文件可直接下载，且能保留<table>结构、<ol>/<ul>编号、<strong>加粗、<img>嵌入（base64）、甚至<h1>到<h6>的层级语义。它不是玩具库——某高校在线实验报告系统上线后，学生导出成功率从 62% 拉到 99.3%，核心就靠它把富文本编辑器输出的 HTML 直接喂进 DOCX 黑匣子。适合前端工程师、教育类 SaaS 开发者、需要离线导出能力的政企内部系统维护者。别被名字里的 “js” 迷惑——它不是简单字符串替换，而是用 JS 模拟 Office Open XML（OOXML）规范，手搓 ZIP 容器、打包[Content_Types].xml、word/document.xml、word/media/等全套结构。
2. 核心原理与选型依据：为什么不用后端方案？为什么不是 jszip + 手写 XML？
2.1 DOCX 本质是 ZIP 包，但手写 XML 是玄学工程
DOCX 文件表面是.docx，实则是 ZIP 压缩包，解压后能看到word/document.xml（正文内容）、word/styles.xml（样式定义）、word/media/（嵌入图片）等标准 OOXML 结构。理论上，你可以用jszip库新建 ZIP，再手动拼document.xml字符串。但现实很骨感：
<w:t>标签必须严格嵌套在<w:r><w:t>内，漏一个<w:r>就导致 Word 打开报错；- 表格需同时写
w:tbl、w:tr、w:tc、w:p四层结构，合并单元格还要算w:gridSpan和w:hMerge； - 图片必须 base64 解码后存为二进制 blob，再写进
media/image1.png，同时在document.xml里插入<a:blip r:embed="rId5"/>并在word/_rels/document.xml.rels中声明关系。
某开发者曾花 3 天手写表格转换，结果导出的 DOCX 在 Word 2016 上打开提示「文件已损坏」，用opc-diag工具查才发现document.xml里<w:tcW w:w="0" w:type="dxa"/>的w:w="0"被 Word 认为非法——这种细节根本不在任何公开文档里写明，全靠翻微软私有规范和血泪经验。
2.2 html-docx-js 的破局点：HTML 语义到 OOXML 的精准映射
html-docx-js 不是暴力字符串替换，而是建立了一套「HTML 元素 → OOXML 节点」的映射规则表。例如：
<h1>→<w:p><w:pPr><w:pStyle w:val="Heading1"/></w:pPr><w:r><w:t>...</w:t></w:r></w:p>；<table>→<w:tbl><w:tblPr>...</w:tblPr><w:tr>...</w:tr></w:tbl>，且自动处理<thead>作为首行加粗、<colgroup>宽度继承；<img src="data:image/png;base64,...">→ 自动提取 base64 数据，生成唯一文件名image1.png，写入media/目录，并在document.xml插入对应<w:drawing>节点。
关键在于它不依赖外部样式表：所有style="font-weight:bold"、style="text-align:center"都实时解析成 OOXML 属性（如<w:rPr><w:b/></w:rPr>、<w:pPr><w:jc w:val="center"/></w:pPr>），避免了 CSSOM 解析的兼容性雷区。这正是它比docxtemplater（需预定义模板）或mammoth.js（专注.docx→ HTML，反向不强）更适合「动态 HTML 导出」的根本原因。
2.3 为什么不用服务端方案？三个硬伤无法绕过
某跨平台系统曾用 Node.js 的officegen库做后端转换，结果暴露三大死穴：
- 并发瓶颈：单次转换平均耗时 800ms，当 50 人同时导出，Node 进程 CPU 暴涨至 95%，API 响应延迟超 10s；
- 图片路径失效：前端 HTML 中
<img src="/api/images/123">，后端无法访问该 URL（跨域/鉴权失败），只能返回空图； - 样式丢失率高：
officegen对flex布局、CSS Grid 的解析为 0，所有响应式容器在 DOCX 中坍缩为单列。
而 html-docx-js 把全部压力卸载到用户终端：你的服务器只管静态资源分发，转换性能取决于用户电脑 CPU，且所有<img>的src必须是 base64 或同源绝对路径（由前端确保），彻底规避网络请求问题。这不是妥协，是架构级降维打击。
3. 快速上手：三步集成，10 行代码搞定基础导出
3.1 安装与引入：CDN 与模块化双路径
CDN 方式（适合快速验证）：
<script src="https://cdn.jsdelivr.net/npm/html-docx-js@1.0.0/dist/html-docx.min.js"></script>提示：
html-docx-js@1.0.0是当前稳定版，dist/目录下html-docx.min.js仅 42KB，无外部依赖，加载即用。
ES Module 方式（推荐生产环境）：
npm install html-docx-jsimport { asBlob } from 'html-docx-js'; // 注意：不要 import * as htmlDocx，会因命名冲突报错3.2 核心 API：asBlob()与saveAs()的协作链
html-docx-js 只暴露两个核心函数：asBlob(htmlString, options)生成Blob对象，saveAs(blob, filename)触发下载。切记：它不直接生成文件，也不操作 DOM——你必须先拿到 HTML 字符串。典型流程：
// 1. 获取目标 HTML（注意：必须是完整 HTML 片段，含 <body> 内容） const htmlContent = document.getElementById('report-container').innerHTML; // 2. 调用 asBlob 转换（options 为可选配置） const blob = asBlob(htmlContent, { orientation: 'portrait', // 页面方向：'portrait' | 'landscape' margins: { top: 720, right: 720, bottom: 720, left: 720 }, // 单位：twips（1英寸=1440 twips） fontSize: 20, // 基础字号，单位：twips（12pt ≈ 288 twips） }); // 3. 下载文件 saveAs(blob, '实验报告.docx');逻辑说明：
asBlob()内部执行三步：① 解析 HTML 字符串为 DOM 节点树；② 遍历节点，按映射规则生成 OOXML 字符串；③ 用JSZip打包所有 XML 文件及媒体资源，调用JSZip.generateAsync({ type: 'blob' })输出 Blob。saveAs()本质是创建<a href="blob:...">并触发click()，兼容 Chrome/Firefox/Edge。
3.3 配置项详解：哪些参数真有用，哪些可忽略
| 参数名 | 类型 | 默认值 | 作用说明 | 是否建议修改 |
|---|---|---|---|---|
orientation | string | 'portrait' | 页面方向，影响纸张宽高比 | ✅ 导出横向报表必设'landscape' |
margins | object | {top:720,...} | 页边距（twips），720 = 0.5英寸 | ✅ 需打印时调大至1440（1英寸） |
fontSize | number | 20 | 基础字号（twips），20≈0.014英寸≈1pt | ⚠️ 通常不改，字号由 HTML 内联 style 控制 |
footer | string | '' | 页脚 HTML 字符串（支持<p>第 {{page}} 页</p>） | ✅ 需页码时必设，{{page}}自动替换 |
header | string | '' | 页眉 HTML 字符串 | ✅ 同上 |
includeHiddenElements | boolean | false | 是否包含display:none元素 | ❌ 一般不开启，避免导出隐藏控件 |
参数说明：
twips是 Word 原生单位（1 inch = 1440 twips），所以margins: {top: 1440}= 上边距 1 英寸。footer中的{{page}}是 html-docx-js 内置变量，无需额外插件；若需总页数{{pages}}，需配合footer: '<p>第 {{page}} 页，共 {{pages}} 页</p>'，但注意{{pages}}仅在 Word 2013+ 支持。
4. 避坑指南：五个真实翻车现场与后悔药
4.1 现象：导出的 DOCX 在 Word 中打开提示「文件已损坏」，点击「修复」后内容全乱
原因：HTML 字符串中存在未闭合标签或非法嵌套，如<p><div>内容</div></p>（<div>不允许在<p>内）。html-docx-js 的 HTML 解析器基于浏览器 DOM API，会自动修正为<p></p><div>内容</div><p></p>，但修正后的 DOM 结构可能破坏 OOXML 映射逻辑，导致document.xml格式错误。
解决：导出前用DOMParser预校验并标准化 HTML：
function sanitizeHtml(html) { const parser = new DOMParser(); const doc = parser.parseFromString(html, 'text/html'); // 移除 script/style 标签（防止 XSS，且 DOCX 不执行 JS） doc.querySelectorAll('script, style').forEach(el => el.remove()); return doc.body.innerHTML; } const cleanHtml = sanitizeHtml(document.getElementById('report').innerHTML); const blob = asBlob(cleanHtml, options);4.2 现象：表格导出后列宽严重失真，所有列挤成一列
原因：html-docx-js 默认将表格宽度设为auto，且不解析 CSSwidth属性（如table { width: 100%; }）。它只认<table width="500">或<td width="200">这类 HTML 属性。
解决：在生成 HTML 时，用 JS 注入width属性：
// 遍历所有 table，设置固定宽度（单位：像素） document.querySelectorAll('table').forEach(table => { const rect = table.getBoundingClientRect(); table.setAttribute('width', Math.round(rect.width).toString()); // 为每个 td 设置宽度（按比例） table.querySelectorAll('td, th').forEach((cell, i) => { const cellRect = cell.getBoundingClientRect(); const width = Math.round(cellRect.width / rect.width * 100); cell.setAttribute('width', `${width}%`); }); });4.3 现象：中文显示为方框，英文正常
原因：html-docx-js 默认使用Times New Roman字体，该字体在部分 Windows 系统中不包含中文字形，Word 回退为默认中文字体（如 SimSun），但回退逻辑不稳定。
解决：强制指定中文字体，在 HTML 中添加<style>块：
<div id="report-container"> <style>body { font-family: "Microsoft YaHei", "SimSun", sans-serif; }</style> <!-- 其他内容 --> </div>注意：
font-family必须写在要导出的 HTML 片段内，且优先级高于全局 CSS，因为 html-docx-js 只解析内联style和style标签，忽略外部样式表。
4.4 现象：图片导出后模糊、拉伸变形
原因：html-docx-js 对<img>的尺寸处理逻辑是：取img.naturalWidth/Height（原始尺寸），而非img.width/height（CSS 设置的显示尺寸）。若 HTML 中用img { max-width: 100%; height: auto; }，则naturalWidth可能远大于显示区域。
解决：导出前统一重设img的width/height属性为显示尺寸：
document.querySelectorAll('#report-container img').forEach(img => { const rect = img.getBoundingClientRect(); img.setAttribute('width', Math.round(rect.width)); img.setAttribute('height', Math.round(rect.height)); });4.5 现象：导出文件体积爆炸（>10MB），打开极慢
原因：HTML 中<img>的src是未压缩的 base64（如data:image/png;base64,iVBORw0KGgo...），而 html-docx-js 会原样写入media/目录，不做任何压缩。一张 5MB 的 PNG base64 会导致 DOCX 体积直逼 5MB。
解决：前端压缩图片再转 base64：
async function compressAndConvertToBase64(file, maxWidth = 800) { return new Promise((resolve) => { const reader = new FileReader(); reader.onload = (e) => { const img = new Image(); img.onload = () => { const canvas = document.createElement('canvas'); const ctx = canvas.getContext('2d'); const scale = Math.min(maxWidth / img.width, 1); canvas.width = img.width * scale; canvas.height = img.height * scale; ctx.drawImage(img, 0, 0, canvas.width, canvas.height); resolve(canvas.toDataURL('image/jpeg', 0.8)); // JPEG 压缩至 80% 质量 }; img.src = e.target.result; }; reader.readAsDataURL(file); }); } // 使用时：await compressAndConvertToBase64(fileInput.files[0])5. 进阶技巧：自定义样式、批量导出与离线可靠性加固
5.1 绕过默认样式：注入自定义 Word 样式（Heading1/Normal 等）
html-docx-js 的styles.xml是硬编码的，但你可以通过options.styles注入自定义样式定义。例如，让所有<h1>使用「黑体 16pt 加粗」：
const customStyles = ` <w:style w:type="paragraph" w:styleId="Heading1"> <w:name w:val="heading 1"/> <w:basedOn w:val="Normal"/> <w:next w:val="Normal"/> <w:link w:val="Heading1Char"/> <w:uiPriority w:val="9"/> <w:pPr> <w:spacing w:before="240" w:after="120"/> </w:pPr> <w:rPr> <w:rFonts w:ascii="SimHei" w:hAnsi="SimHei" w:eastAsia="SimHei"/> <w:sz w:val="320"/> <!-- 16pt = 320 twips --> <w:b/> </w:rPr> </w:style> `; const blob = asBlob(htmlContent, { styles: customStyles, // 其他选项... });关键点：
w:styleId="Heading1"必须与 HTML 中<h1>的映射一致；w:rFonts指定中文字体；w:sz设字号（twips）；w:b表示加粗。此 XML 片段会合并到生成的styles.xml中，覆盖默认样式。
5.2 批量导出：一次生成多个 DOCX 并打包为 ZIP
html-docx-js 本身不提供 ZIP 打包，但可结合JSZip实现：
import JSZip from 'jszip'; async function batchExport(reports) { const zip = new JSZip(); for (let i = 0; i < reports.length; i++) { const { title, html } = reports[i]; const blob = asBlob(html, { orientation: 'portrait' }); // 将 Blob 转为 Uint8Array 再存入 ZIP const arrayBuffer = await blob.arrayBuffer(); zip.file(`${title}.docx`, arrayBuffer); } const content = await zip.generateAsync({ type: 'blob' }); saveAs(content, '批量报告.zip'); } // 调用示例 batchExport([ { title: '张三-实验报告', html: getHtml('zhangsan') }, { title: '李四-实验报告', html: getHtml('lisi') } ]);注意：
blob.arrayBuffer()是异步操作，必须await；JSZip.generateAsync()返回 Blob，可直接saveAs。此方案避免了服务端 ZIP 生成，全程前端完成。
5.3 离线可靠性加固：缓存核心资源与降级策略
在弱网或离线场景，CDN 加载html-docx-js可能失败。解决方案：
- Service Worker 缓存：在
sw.js中预缓存html-docx.min.js； - 降级为 HTML 下载：检测加载失败时，回退到
location.href = 'data:text/html;charset=utf-8,' + encodeURIComponent(htmlContent)； - 预加载检查：
async function loadHtmlDocx() { try { // 尝试加载 CDN await import('https://cdn.jsdelivr.net/npm/html-docx-js@1.0.0/dist/html-docx.min.js'); return true; } catch (e) { console.warn('html-docx-js 加载失败，启用降级模式'); return false; } } // 使用时 if (await loadHtmlDocx()) { const blob = asBlob(html, options); saveAs(blob, 'report.docx'); } else { // 降级逻辑 const a = document.createElement('a'); a.href = 'data:text/html;charset=utf-8,' + encodeURIComponent(html); a.download = 'report.html'; a.click(); }从那以后我每次集成 html-docx-js，都强制走三遍流程：第一遍用 CDN 快速验证功能，第二遍用npm install接入构建流程并测试 Tree Shaking，第三遍在 Chrome DevTools 的 Application → Service Workers 面板里勾选「Offline」，反复点击导出按钮确认降级逻辑生效。这看似繁琐，但省去了线上用户反馈「导出按钮点了没反应」的半夜救火。希望帮到你。
本文还有配套的精品资源，点击获取
