wangEditor v5实现Word批注与修订导入的完整方案

如果你在wangEditor里导入过带批注的Word文档，大概率会骂娘——正文倒是正常进来了，但是同事给你的批注像人间蒸发一样，修订痕迹也全变成了普通文本，等于整个审阅过程白干了。这个事我前前后后折腾了两周，最后在wangEditor v5里成功把Word导入、批注侧边展示、修订痕迹都做了出来，甚至还顺手解决了几个表格双线变单线的兼容问题。今天就把这套实现思路和踩坑记录整理出来，给同样被在线文档审阅折磨的朋友一点参考。

1. 需求背景与整体方案选型

在线文档一旦涉及多人协作，批注和修订记录就是刚需。你可以把Word当成“审阅者的红笔”，批注是贴便利贴，修订是直接在稿子上画删除线、写替换文字。但wangEditor本身是一个纯前端富文本编辑器，并没有原生支持Word批注和修订的导入，Word文档上传后默认只能提取正文内容，丢掉审阅信息。这会让很多团队在从Office搬到Web端时非常痛苦，尤其是合同审批、论文评审、方案会签这类场景，批注和修订就是核心资产，丢不起。

我当时接到的需求更直接：用户把一份带审阅意见的Word文档丢进网页编辑器，正文能编辑不说，批注要能点开看，修订要能区分出是谁改了哪一句、什么时候改的。如果这些做不到，功能上线等于没做。

1.1 为什么批注和修订必须被保留

很多人觉得批注和修订只是格式问题，实际上它们是“审阅流程”的载体。批注保存的是人和人的沟通上下文，“这里写得不清楚”“这个数字需要再确认”，这些信息一旦丢失，接收到文档的人就不知道之前发生了什么。修订记录则更关键，它保存了文档的演进历史，谁在什么时候添加了什么、删除了什么、改了什么格式，这是合规审计和团队追责的重要依据。

更重要的是，用户对这类功能有强烈的心理预期。他们在Word里已经习惯了“批注挂在右侧，修订用颜色标出来”，如果导入web编辑器后这些痕迹全部消失，第一反应就是系统有bug，而不是格式不支持。所以我们在技术选型上，第一优先级就是尽可能保留原文档中的批注和修订元数据，哪怕是只读展示，也比完全丢失强。

1.2 可行技术路线对比

实现Word转HTML并保留批注修订，业内其实有几种常见路线，我这里直接做了个对比：

我最终选择了方案B，核心技术栈是JSZip + mammoth + fast-xml-parser + cheerio，前端自己解析docx。理由很直接：需求是“导入并保留批注修订”，并不要求做一个完整的Office兼容内核。wangEditor本身是前端编辑器，数据在浏览器里走一遍，不需要后端参与，部署成本最低，而且docx格式是开放的zip+XML结构，完全有能力自己解析。

这里也多说一句，如果你所在团队有Java后端，方案A其实也成熟，POI对批注和修订的提取都有对应的API，但前后端联调成本不低。如果你要做的是中文团队内部工具，我更推荐前端方案，迭代快、可定制性强，遇到问题直接在浏览器里打断点，比在后端绕一圈舒服得多。

2. 核心细节解析：docx中批注和修订到底存在哪

很多人被“docx”这个后缀骗了，以为它就是一个文件，其实它本质上是一个zip压缩包。包里面有一堆XML文件，其中最关键的是word/document.xml（正文内容）、word/comments.xml（批注内容）、word/people.xml（人员信息）。修订记录则直接嵌在document.xml里，通过特定的标签标记插入、删除和格式修改。搞懂这几个文件的关系，后面实现就顺了。

2.1 批注的存储结构

批注在docx里分两部分。第一部分是正文中的锚点，在word/document.xml里表现为一对标签：

<w:commentRangeStart w:id="1"/> <w:r><w:t>需要审阅的文字</w:t></w:r> <w:commentRangeEnd w:id="1"/>

简单理解，commentRangeStart和commentRangeEnd就像两个括号，把被批注的文字包起来。id用来关联批注内容。

第二部分是批注的具体内容，在word/comments.xml里：

<w:comment w:id="1" w:author="张三" w:date="2025-01-15T10:30:00Z"> <w:p> <w:r><w:t>这里的数据需要再核实一下</w:t></w:r> </w:p> </w:comment>

这里能看到批注者、批注时间和批注文本。所以解析思路很清晰：先读取comments.xml拿到批注内容和作者信息，再去document.xml里通过id找到对应的文字范围，最后把这段文字包裹成一个带批注信息的HTML节点。

如果你还见过word/people.xml，它是用于存储参与者信息的（尤其是Office 2016以后），很多批注的author会指向people.xml里的displayName，解析时如果发现comments.xml里只剩一个id，就需要去people.xml里再查一次。

2.2 修订记录的存储结构

修订记录比批注稍微复杂一点，因为它直接在正文流里标记。

插入的内容放在w:ins标签里，表示这段文字是后来加进去的：

<w:ins w:id="2" w:author="李四" w:date="2025-01-16T09:00:00Z"> <w:r><w:t>新增的这段话</w:t></w:r> </w:ins>

删除的内容放在w:del标签里，被删除的文字通常用w:delText而不是w:t包裹，目的是让解析器知道“这段文字已经不存在了”，但仍然保留在文档里供审阅者查看：

<w:del w:id="3" w:author="李四" w:date="2025-01-16T09:00:00Z"> <w:r><w:delText>这段被删掉了</w:delText></w:r> </w:del>

还有格式修改，比如有人把一段文字从红色改成黑色，底层会用w:rPrChange记录修改前后的格式。不过大多数导入场景下，我们可以先只关注插入和删除两类修订，格式类的修订在HTML里不好还原，一般用特殊底色提示即可。

这里有一个容易踩的坑：如果你的解析逻辑只读取<w:t>来取文本，遇到删除修订就会漏掉内容，因为被删除的文字写在<w:delText>里。实际开发中一定要两个标签都处理，特别是需要展示修订痕迹时，delText的内容通常要渲染成带删除线样式的文字。

2.3 如何把XML锚点映射到HTML文本

理论清楚了，实际落地还有个麻烦：mammoth.js 负责把document.xml转成干净的HTML，但它默认不会保留批注和修订。经过测试，mammoth对未知的commentRangeStart这类标签几乎是无视的，直接跳过。所以我们需要自己做锚点映射。

我在项目里用了一个不算优雅但很稳定的办法：在把document.xml交给mammoth转HTML之前，先预处理XML，把批注锚点和修订标签替换成特殊的占位符。比如遇到commentRangeStart就插入一个文本标记【批注开始 id=1】，遇到w:ins就插入【修订插入开始】，等mammoth转换完HTML，再用cheerio把这些占位符替换成真正的自定义节点。

为什么不用正规的<span>npm install @wangeditor/editor @wangeditor/editor-for-vue@next jszip mammoth fast-xml-parser cheerio

这里有个细节，vue2项目里用wangEditor v5要装@wangeditor/editor-for-vue@next，老版本是给v4用的，直接装最新npm包可能会拿到for-vue3版本，导入的时候就会报“createEditor is not a function”之类的错误。如果你在vue2里使用，务必确认版本。

然后初始化编辑器：

import { createEditor, createToolbar, DomEditor } from '@wangeditor/editor' import '@wangeditor/editor/dist/css/style.css'

3.2 解析docx的批注和修订

上传文件后拿到ArrayBuffer，先用JSZip解压，读取需要的XML：

const zip = await JSZip.loadAsync(arrayBuffer) const commentsXML = await zip.file('word/comments.xml')?.async('string') const documentXML = await zip.file('word/document.xml').async('string')

然后用fast-xml-parser解析XML，注意要保留属性，把下划线后的@_转成驼峰命名也打开，方便后面取值：

const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@_' }) const commentsDoc = parser.parse(commentsXML)

拿到批注列表后，按id存成数组，例如：

const commentMap = {} commentsDoc['w:comments']['w:comment'].forEach(item => { const id = item['@_w:id'] const author = item['@_w:author'] const date = item['@_w:date'] // 从p→r→t链上取批注文本 const text = extractText(item) commentMap[id] = { author, date, text } })

同一时间，在document.xml里遍历所有w:commentRangeStart，拿到位置信息，插入占位符。由于一个文档里批注可能很多，我会先给每个批注生成一个全局唯一ID，然后以类似__COMMENT_START_1__的形式插入到文本流中。同理，修订标签也做相同处理。

3.3 生成带批注和修订标识的HTML

预处理完document.xml后，交给mammoth转换正文：

const result = await mammoth.convertToHtml({ arrayBuffer: buf }, options) let html = result.value

此时HTML里会有一堆__COMMENT_START_1__这类占位符。接下来用cheerio把占位符替换成真正自定义元素：

const $ = cheerio.load(html) $('body').html($('body').html().replace(/__COMMENT_START_(\d+)__/g, (match, id) => { return `<span>const commentModule = { type: 'comment', parseElemHtml(elemDom) { return { type: 'comment', commentId: elemDom.getAttribute('data-comment-id'), } }, renderElem(elem, children) { const vnode = h('span', { class: 'wangeditor-comment', attrs: { 'data-comment-id': elem.commentId, contenteditable: 'false', title: `批注：${commentMap[elem.commentId]?.text || ''}`, }, }, children) return vnode }, toHtml(elem) { return `<span>const editor = createEditor({ selector: '#editor', html: '', config: { EXTEND_CONF: { commentModule, insModule, delModule, }, }, })

注册完成后，把之前生成好的HTML交给编辑器：

editor.setHtml(html)

这样编辑器就能识别>.wangEditor-tabble { border-collapse: collapse; } .wangEditor-tabble td { border: 1px solid #d0d7de; }

如果需要精确还原双线，可以在解析表格XML时把边框宽度信息提取出来，转成内联CSS。但说实话大多数场景下用户能接受“单线灰色边框”，优先保证布局一致，不要过度纠结边框样式。

4.5 加载大文档卡死

如果Word文档有几百个批注，或者正文有几十页，前端一次性解析所有XML再转HTML，确实会卡。我实测一个18MB的docx，在普通笔记本上解析要好几秒。

优化建议：把JSZip解压和mammoth转换都放到Web Worker里跑，主线程只负责接收结果。另外占位符替换阶段，如果HTML很大，不要用字符串全局replace，用cheerio遍历文本节点，这样能省掉很多无谓的重复匹配。

5. 扩展方向与个人体会

这个功能做完之后，再回头看其实只是“解析docx + 自定义节点渲染”的组合拳，但前期对OOXML结构不熟的时候确实头大。如果你们团队也在做类似的东西，有几个扩展方向可以提前考虑。

5.1 导出为Word时保留批注和修订

很多系统只要求“导入看”，但真正完整的审阅闭环是需要再把文档导回Word，并且批注修订都还在。这个可以用docx.js实现，把你编辑器里的自定义节点反向转成OOXML里的commentRangeStart、commentRangeEnd、w:ins、w:del。工作量比导入还要大一点，因为要处理嵌套和顺序，但方向是明确的。

5.2 配合只读模式和AI审稿

如果你做的是审阅场景，通常导入后要让普通用户“只能看不能改”，这就用到了wangEditor的只读模式：editor.disable()或者editor.config.readOnly = true。批注在这种模式下反而更适合展示，因为用户不需要删除或修改批注，只需要阅读。现在也有团队把AI模型接进来，让AI在正文里生成批注，底层就是新增>