Show HN: DOM-docx – HTML to native, editable Word docs (MIT)
156 points
• 5 days ago
• Article
Link
dom-docx 是一个用于将语义化 HTML 片段转换为原生且可编辑的 Microsoft Word 文档（OOXML）的库。与依赖截图或布局技巧的工具不同，它着重将段落、列表、表格和图像等 HTML 元素直接映射到对应的 Word 结构上，支持元数据、页码、页眉页脚和目录等文档功能。
该库通过多种源模式提供样式处理的灵活性。默认的内联模式直接解析 HTML 中的样式，因而成为一个无需浏览器、运行快速的纯 JavaScript 解决方案。对于需要处理外部 CSS 或类选择器的更复杂场景，提供了计算模式：在 Node.js 中该模式借助 Playwright 和 Chromium 渲染片段并解析样式，而在浏览器包中则利用实时 DOM 完成相同工作。
为了解决图表和复杂 SVG 等难以原生映射到 Word 的视觉元素，dom-docx 提供了栅格化功能，允许在生成文档前将特定元素转换为 PNG，从而保证视觉呈现。库中还提供通过自定义解析器管理外部图像的选项，并支持对页面的页边距、方向和语言等配置进行细粒度控制。
项目开发重视严格的质量控制，采用自动化的视觉回归循环。引擎通过一套经人工验证的指标测试布局还原度、可编辑性和编译速度，确保转换结果稳定可靠，使用户能够信赖生成文档的结构与外观。
该项目通过简洁的 API 和命令行界面提供访问，适配多种工作流。无论是在浏览器作为客户端库使用，还是在 Node.js 环境作为服务器端工具运行，dom-docx 的目标都是在 Web 内容与 Microsoft Word 专业文档之间搭建一座可靠的桥梁。
dom-docx is a library designed to convert semantic HTML fragments into native, editable Microsoft Word documents, or OOXML. Unlike tools that rely on screenshots or layout hacks, this project focuses on mapping HTML elements such as paragraphs, lists, tables, and images directly into their corresponding Word structures. It supports a variety of document features including metadata, page numbering, headers and footers, and tables of contents.
The library offers flexibility in how styles are handled through different source modes. By default, it uses an inline mode that parses HTML styles directly, making it a fast, pure JavaScript solution that does not require a browser environment. For more complex requirements, such as handling external CSS or class selectors, it supports a computed mode. In Node.js, this mode utilizes Playwright and Chromium to render the fragment and resolve styles, while in the browser bundle, it leverages the live DOM to perform the same task.
To handle dynamic or complex visual elements like charts and intricate SVGs, dom-docx provides a rasterization feature. This allows users to convert specific elements into PNG images before the final document generation, ensuring visual fidelity for content that would otherwise be difficult to map natively to Word. The library also includes options to manage external images via a custom resolver and supports page-specific configurations like margins, orientation, and language settings.
A key aspect of the library's development is its rigorous quality control, which uses an autonomous visual regression loop. The engine is tested against a suite of human-validated metrics that evaluate layout fidelity, editability, and compilation speed. This process ensures that the conversion remains consistent and reliable, allowing users to trust the structure and appearance of their generated documents.
The project is designed to be accessible through both a straightforward API and a command-line interface, making it suitable for a variety of workflows. Whether used as a client-side library in the browser or as a server-side tool in a Node.js environment, dom-docx aims to provide a robust bridge between web-based content and the professional document environment of Microsoft Word.
40 comments • Comments Link
• 由于加密机制的问题和现有开源库的局限，从代码直接生成可编辑的 Word 文档长期以来一直被视为非常困难。
• "Autoresearch"循环通过迭代将 HTML 渲染为 Word 、把生成结果与原始截图比对，并用得到的评分来改进生成策略，从而提升转换的保真度。
• 尽管当前实现对复杂独立布局元素的渲染表现良好，但仍需更多测试以确保在处理大型多页文档时的稳定性。
• 对 Microsoft Word 的测试至关重要，因为其官方套件比 LibreOffice 有更严格的验证：即便文件在其他程序中看似正常，Word 也常会将其判定为损坏。
• 与传统的测试驱动开发不同，Autoresearch 更侧重于基于度量的持续改进，而不是简单的通过 / 失败二元判断。
• 将项目以 TypeScript 开发相比基于 Haskell 的现有解决方案（如 Pandoc）在开发体验上具有显著优势。
• Autoresearch 模式高度通用，已在 SQL 性能优化、基于锦标赛的 AI 脚本生成等多种任务上取得成效。
• 借助当前的 AI 辅助开发工具，可以以相对较低的 token 成本和最小的时间投入完成复杂技术项目。
• DOCX 格式在专业工作流中的主导地位仍然是个重大障碍，迫使开发者为这一遗留标准构建复杂的转换器。
• 尽管 CSS 提供了强大的文档布局工具，浏览器原生的打印样式经常被开发者忽视，导致打印输出效果不佳。
本次讨论集中在如何在现代基于 Web 的文档生成与僵化、封闭的 OOXML 标准之间调和技术挑战。参与者对作者提出的迭代化、基于评分的方案反应积极，认为它有助于解决长期存在的布局保真问题，且作为对现有 Haskell 工具的更易上手的替代方案具有吸引力。大家强调，实践中需要把测试范围从小片段扩展到面向 Microsoft Word 的严格验证，因为哪怕很小的偏差也可能导致生成文件无法满足专业用户的使用要求。总体而言，讨论反映出在现代开发环境中支持遗留格式带来的普遍挫败感，但共识是：这类项目对搭建 Web 技术与传统办公软件之间的桥梁至关重要。 • Generating editable Word documents from code is notoriously difficult due to cryptic errors and the limitations of existing open-source libraries.
• An "autoresearch" loop can improve conversion fidelity by iteratively rendering HTML to Word, comparing the output against a source screenshot, and using the resulting score to refine the generation logic.
• While the current implementation excels at rendering complex, isolated layout elements, further testing is required to ensure stability when handling larger, multi-page documents.
• Testing against Microsoft Word is essential, as the official suite enforces stricter validation than LibreOffice, often flagging files as corrupted even when they appear correct elsewhere.
• Unlike traditional test-driven development, the autoresearch approach optimizes for continuous metric-based improvement rather than simple pass/fail outcomes.
• Choosing TypeScript for this project provides a significant developer experience advantage over existing solutions like Pandoc, which is built in Haskell.
• The autoresearch pattern is highly versatile, proving effective for diverse tasks like SQL performance optimization and tournament-based AI script generation.
• Using current AI-assisted development tools allows for complex technical projects to be completed with relatively low token costs and minimal time investment.
• The persistent dominance of the DOCX format in professional workflows remains a significant friction point, forcing developers to build complex converters for a legacy standard.
• Browser-native print styles are often neglected by developers, leading to poor print output even though robust tools for document layout already exist in CSS.
The conversation centers on the technical challenges of reconciling modern web-based document generation with the rigid, proprietary nature of the OOXML standard. There is clear enthusiasm for the author's iterative, score-driven approach to solving long-standing layout fidelity issues, particularly as a more accessible alternative to existing Hasekll-based tools. Participants emphasize that real-world utility requires moving beyond small test fragments toward robust validation against Microsoft Word, as minor deviations can render generated files unusable for professional end-users. Ultimately, the thread highlights a shared frustration with the necessity of supporting legacy formats in a modern development landscape, though the consensus remains that projects like this are vital for bridging the gap between web technologies and traditional office software.