docx-edit用虚拟树的方式优雅地编辑 Word 文档项目地址github.com/CZ600/docxEdit在 Node.js 中处理 Word 文档.docx一直是个让人头疼的事。传统库要么只能读取要么在修改时会丢失格式、图片或结构更别提在保持原样的情况下对文档进行精细的编辑和排版迁移了。今天想向你介绍一个我最近在维护的库 ——docx-edit。它在底层 OOXML 之上构建了一棵可 diff / patch 的虚拟树让你可以像操作前端组件树一样自由修改 .docx 中的段落、表格、页眉、脚注、批注甚至数学公式并高保真地保存回原文件。 为什么需要虚拟树Word 文档的底层 OOXML 是非常“碎片化”的一个段落可能被拆成若干个w:rrun文本散落其中样式属性还分散在样式表、主题和直接属性里。直接修改 XML 不仅容易出错还会破坏文档结构。docx-edit的做法是将整个文档解析为一棵虚拟树类似 React 的 Virtual DOM。你在虚拟树上增、删、改、移节点。调用doc.patch(nextTree)引擎会算出最小的diff并精准地回写到 XML 中。格式、样式、脚注引用、数学公式等全部得到保留。这样的设计让“在 Word 里批量替换公司名称”“给所有标题统一调样式”“把 A 文档的格式迁移到 B 文档”这些需求变得异常简单。 快速开始安装只需一行npminstalldocx-edit一个最简单的“查找替换”例子const{loadDocx}require(docx-edit);asyncfunctionmain(){constdocawaitloadDocx(./sample.docx);doc.replaceAll(旧词,新词);// 支持字符串、正则awaitdoc.saveAs(./sample.modified.docx);}main();如果你需要更精细的控制可以直接操作虚拟树constdocawaitloadDocx(./sample.docx);consttreedoc.toComponentTree();// 拿到整棵虚拟树constbodytree.children.find(nn.typebody);body.children[0].props.text新段落内容;// 修改文本body.children[0].props.style{alignment:center,spacing:{after:240}};awaitdoc.patch(tree);// diff 回写awaitdoc.saveAs(output.docx); 虚拟树模型一览库的虚拟树结构非常直观符合你对文档的直觉document ├── body │ ├── paragraph │ │ ├── run → text │ │ └── run → text (粗体) │ └── table │ └── table-row │ └── table-cell │ └── paragraph → ... ├── header ├── footer ├── comments ├── footnotes └── endnotes支持的节点类型非常多paragraph、run、text、table、table-row、table-cell、hyperlink、text-box、image、math、footnoteReference、endnoteReference等等。基本上Word 文档里你能看到的东西这里都能准确表达。 样式模型段落和文字属性完全建模库对样式的支持不再是简单的“粗体/斜体”开关而是完整的 OOXML 样式映射。段落样式 (paragraph.props.style){styleId:BodyText,alignment:center,keepNext:true,spacing:{before:120,after:240,line:360},indent:{left:240,hanging:240}}文字样式 (run.props.style){styleId:Emphasis,bold:true,italic:true,color:FF0000,fontSize:28,vertAlign:superscript,// 上标/下标fontFamily:{ascii:Calibri,eastAsia:宋体,asciiTheme:minorHAnsi// 主题字体引用}}你可以直接新建样式、修改现有样式甚至把一个段落的样式完整复制到另一个段落constparaAdoc.getBody().getParagraph(0);constparaBdoc.getBody().getParagraph(1);paraB.copyStyleFrom(paraA); 样式档案跨文档格式一键迁移这是一个重磅功能。你可以把整个文档的命名样式来自word/styles.xml导出为一个 JSON 档案并在另一个文档中应用它。constdocAawaitloadDocx(template.docx);constprofiledocA.getStyleProfile();// 导出样式定义constdocBawaitloadDocx(report.docx);docB.applyStyleProfile(profile);// 应用样式awaitdocB.saveAs(styled-report.docx);更常见的情形是两个文档的样式 ID 可能不同比如文档 A 的标题1 叫1文档 B 叫2。库允许你按样式名称进行智能匹配只迁移格式保留目标文档的继承结构// 按名称映射样式实现格式迁移constsrcProfiledocA.getStyleProfile();constdstProfiledocB.getStyleProfile();constmapped{defaults:srcProfile.defaults,styles:{}};for(const[srcId,srcStyle]ofObject.entries(srcProfile.styles)){for(const[dstId,dstStyle]ofObject.entries(dstProfile.styles)){if(dstStyle.namesrcStyle.namedstStyle.typesrcStyle.type){mapped.styles[dstId]{name:srcStyle.name,type:srcStyle.type,basedOn:dstStyle.basedOn,// 保留原继承链paragraphStyle:srcStyle.paragraphStyle,// 格式来自源文档runStyle:srcStyle.runStyle};break;}}}docB.applyStyleProfile(mapped);这让企业模板统一化、报告自动排版等任务变得极其轻松。 高级文本操作脚注、尾注和数学公式在 Word 里脚注、尾注和公式往往是修改时的“重灾区”。docx-edit用特殊占位符巧妙地解决了这个问题。读取段落文本时它们会显示为[[FOOTNOTE_REF:id]]脚注引用[[ENDNOTE_REF:id]]尾注引用[[MATH:公式内容]]数学公式当你通过虚拟树修改段落文本时这些占位符会被自动保留不会被误删。你也可以手动创建带有脚注引用的段落constfnIddoc.addFootnote(这是脚注内容);// 新建脚注consttreedoc.toComponentTree();constbodytree.children.find(nn.typebody);body.children.push(createVNode({type:paragraph,props:{text:这是正文[[FOOTNOTE_REF:${fnId}]]},children:[createVNode({type:run,props:{text:这是正文}}),createVNode({type:run,props:{style:{vertAlign:superscript}},children:[createVNode({type:footnoteReference,props:{id:String(fnId)}})]})]}));awaitdoc.patch(tree);这样就能在文档任意位置精确添加脚注标注并自动维护正确的 ID 和样式。 提取为 HTML支持标题、表格、公式你还可以把整个文档包括页眉页脚提取为结构良好的 HTMLconsthtmldoc.extractHtml({partTypes:[body,headers,footers]});输出会包含h1h6自动识别标题级别、strong、em、table含colspan、数学公式块span classmath甚至还能正确处理中文样式的标题如“标题 1”。 稳健的控制器 API 向虚拟树收敛如果你习惯面向对象的操作方式库依然保留了传统的控制器 APIParagraphController、RunController、TableController等constbodydoc.getBody();body.getParagraph(0).setText(新内容);body.replaceAll(北京,上海);doc.getTables()[0].fill([[姓名,年龄],[张三,30]]);但需要注意这些控制器在内部也会生成虚拟树、执行 patch、再同步 XML所以最终效果和高阶虚拟树 API 完全一致不会出现两种操作方式结果不同的问题。✅ 测试覆盖与可靠性库目前已经过丰富的测试包括段落整段读取/回写、tab/break 保留虚拟树文本、结构 patch表格 patch 与fill()混用页眉/页脚/批注/文本框持久化样式建模、新增、修改、迁移word/styles.xml解析与样式继承链合并样式档案导出/导入/回写真实样本文档回归上标/下标、脚注/尾注引用、数学公式的读写 round-trip兼容Node.js 18CommonJS 导出可直接在服务端、CLI 工具、云函数中使用。 总结docx-edit把 Word 文档变成了可编程的组件树。它的优势非常明确修改不失真– 虚拟树 diff/patch 保证最小改动不会破坏原有格式。文本操作高可靠– 自动保留脚注、尾注、公式占位符。样式全覆盖– 支持段落和 run 的完整属性样式档案可导出、迁移。新旧 API 并存– 既可以直接操作虚拟树也可以用熟悉的控制器。功能丰富– 支持页眉页脚、批注、脚注、尾注、文本框、数学公式、表格填充、HTML 提取……如果你正需要批量处理报告、合同、标书或者在 Node.js 中动态生成/修改 .docx 文档不妨试试docx-edit。npminstalldocx-editGitHub 文档欢迎 Star、提 Issue 和 PR一起让 Word 文档的自动化更简单
