DOM-docx：HTML转原生可编辑Word文档

背景

在文档处理领域，将 HTML 内容转换为 Microsoft Word 格式（.docx）是一个常见需求。传统方法通常依赖截图、PDF 转换或基于布局的 hack，导致生成的文档无法编辑或样式失真。Hacker News 上发布的 DOM-docx 项目（MIT 许可）旨在解决这一问题：将语义化的 HTML 片段直接转换为原生、可编辑的 OOXML 文档，保留段落、文本格式、列表、表格、图片等元素，而非生成截图或使用布局技巧。

核心内容

DOM-docx 是一个 TypeScript/JavaScript 库，支持 Node.js 和浏览器环境。它通过一个三阶段流水线工作：样式解析（默认使用内联 style="" 或浏览器计算样式）、访问者模式（Cheerio 遍历生成 docx 库的段落、表格、编号、超链接）、打包与修补（生成 OOXML 并修补列表编号和阴影块对齐，确保 LibreOffice/Word 导出 PDF 的质量）。

安装与基本使用

• Node.js 环境：npm install dom-docx，要求 Node.js ≥ 20。默认内联路径无需浏览器或 Playwright。可选依赖 Playwright 用于计算样式路径或光栅化；npm install dom-docx 仅拉取 docx、cheerio 和 fflate，轻量。LibreOffice 仅用于视觉测试工具，转换不需要。
• 命令行工具：npx dom-docx input.html -o output.docx，支持 stdin/stdout 管道。也可全局安装后直接运行 dom-docx。
• 浏览器端：import { convertHtmlToDocx } from "dom-docx/browser"，返回 Blob 对象，无需 Playwright，完全在用户标签页内运行。

支持的功能

• 默认内联样式：支持标题、段落、列表（<ul>/<ol>，包括 list-style-type）、表格、链接、内联格式、块背景、引用块、<hr>、简单 flex 行（≤4 项）、内联数据图片、远程图片（通过 imageResolver）、页面大小/方向/边距、默认字体、元数据、页眉/页脚 HTML、页码、目录、语言/方向、低复杂度内联 SVG（条形+文本）、表格单元格中的 CSS 条形 div（背景+宽高 → 原生阴影带）。
• 高级计算样式（styleSource: "computed"）：解析 <style> 块和类/ID 选择器，通过 getComputedStyle。Node 端需要 Playwright + Chromium，浏览器端使用用户标签页的实时 DOM。
• 图表与复杂 SVG 光栅化（rasterizeInPlace）：将 <canvas> 和复杂 <svg>（如 Highcharts）在转换前光栅化为 PNG <img>，推荐 scale: 2 以获得更清晰图像。浏览器端需要 root，Node 端使用 Playwright/Chromium 上下文。

不支持的功能（v0.1.x）

• 内联路径上的外部样式表（需使用计算样式或内联所有样式）。
• Web 字体、CSS grid/float 布局、表单、<pre> 样式、<dl>、表格 rowspan。
• 页眉/页脚首页/偶数页变体、保证多页布局保真度。
• 复杂 SVG（路径、渐变、<use>）除非使用 rasterizeInPlace 对实时渲染页面进行光栅化。

质量保证

DOM-docx 由一个自主循环驱动，而非一次性视觉检查：30+ 回归案例（定义在 tools/generator.ts 中，通过 npm run score:suite 运行），包含人类验证的布局保真度（墨水投影结构比较，与盲人质量评分的 concordance 达 85.6%），以及对比度差、列表标记缺失、文本错误、阴影块不平衡等守卫。原始像素匹配作为回归触发器。引擎评分：50% 视觉贡献。

关键要点

• 原生编辑能力：生成的 .docx 文件可在 Word 中直接编辑，而非静态截图或布局 hack。
• 多环境支持：Node.js（CLI 和 API）和浏览器端均可运行，浏览器端无需额外依赖。
• 轻量默认安装：默认内联路径仅依赖 docx、cheerio、fflate，避免引入重型工具。
• 可选的增强路径：通过 Playwright 支持计算样式和光栅化，适用于复杂样式表和图表。
• 命令行工具：提供 npx dom-docx 快捷转换，支持管道和文件输出。
• 图像处理灵活：支持 data: URL 自动嵌入，http(s)/file 路径需通过 imageResolver 自定义获取策略，确保安全。
• 质量驱动开发：使用 30+ 回归测试和人类验证指标，自动评分，确保布局和结构保真度。
• 浏览器端 SPA 导出：支持通过 root 参数匹配实时 DOM 的计算样式，适用于单页应用片段导出。
• 图表光栅化：复杂 SVG 和 Canvas 可自动转为 PNG 图片嵌入 Word，推荐 2x 缩放以获得清晰效果。
• 开源 MIT 许可：代码托管于 Hacker News 展示，社区可自由使用和贡献。

意义与影响

DOM-docx 填补了 HTML 到原生 Word 文档转换领域的一个空白：它提供了一种语义化、可编辑的路径，而非依赖截图或 PDF 中转。对于需要将 Web 内容（如报告、文档、表格）导出为 Word 格式的应用场景，这是一个高效且质量可控的解决方案。其质量保证体系（回归测试 + 人类验证指标）意味着开发者可以信赖其输出的一致性。此外，支持浏览器端和 Node.js 双环境，以及可选的光栅化能力，使其适用于从静态页面到动态单页应用的广泛场景。该项目以 MIT 许可开源，鼓励社区贡献和商业使用，有望成为 HTML-to-docx 转换的标准工具之一。