距离我上一次被“样式丢失”这个需求折腾到抓狂其实还不到两个月。事情本身不复杂用户把一份排好版的Word文档复制到后台富文本编辑器点发布结果正文里的标题、加粗、颜色、行距全部变成默认值表格线也断了大半。最尴尬的是测试环境怎么复现都正常最后跑到用户电脑前才发现同样是“CtrlC / CtrlV”Windows版Word和Mac版WPS送出来的剪贴板数据完全不是一个东西。这个问题的搜索热度一直不低说明它不只是接入层没写好而是很多前端团队第一次做富文本功能时都会踩的同一个坑。它看起来是样式问题本质上是数据格式问题、清洗策略问题和编辑器底层API问题三件事纠缠在一起。这篇文章我把完整的排查思路和一套已验证的清洗流程写出来希望能帮你少走点弯路。1. 先把“样式丢失”拆成四种不同症状再谈方案1.1 剪贴板里的Word内容并不只有一个“版本”在处理“Word转存编辑器”之前必须建立一个认知从Word按CtrlC之后剪贴板里放进去的不是一个“纯文本文件”而是同时投放了多种格式的数据。Windows和macOS的剪贴板机制都支持多格式并存浏览器读到的其实是其中一部分。最常见到的三种格式格式内容浏览器读取方式text/plain去掉了所有格式的纯文本clipboardData.getData(text/plain)text/html带HTML标签的富文本结构clipboardData.getData(text/html)Files图片、附件等二进制对象clipboardData.files很多前端一上来就调getData(text/html)拿到什么就插什么这是第一个坑。因为不同浏览器对剪贴板格式的暴露策略不一样Windows Chrome返回的HTML通常是完整的一段文档里面带着微软Office专用的命名空间macOS Safari有时把text/html字段裁剪得很少甚至数据为空只剩text/plain可用还有的浏览器会把Word里插入的图片从HTML引用中剥离独立放到Files里。所以第一步永远是先打印剪贴板内容确认数据长什么样document.addEventListener(paste, (e) { const cd e.clipboardData || window.clipboardData; if (!cd) return; console.log(types:, [...cd.types]); for (const type of cd.types) { const text cd.getData(type); console.log( type ); console.log(text ? text.slice(0, 500) : (empty)); } console.log(files:, cd.files.length); });这段排查代码建议直接留到项目里线上问题定位会非常有用。“样式全丢了”和“只有样式丢了”是两种完全不同的故障前者往往是数据源没有HTML可用后者才是清洗逻辑的问题。1.2 四种常见丢失症状和它们的真实成因不同用户说的“样式丢失”背后的原因经常不是同一件事。我自己把这些反馈拆成四种症状方便对照定位用户看到的现象真正原因字体、颜色、字号全部变成默认编辑器只拿到了text/plain或者清洗层把style直接删光了文字内容在但段落缩进、行距、标题层级没了Word用CSS类名和内联样式混合控制排版清洗时丢了类名对应的样式表表格结构还在但列宽、边框、合并单元格错乱Word生成的HTML里包含大量colgroup、固定pt宽度、mso边框属性普通浏览器渲染规则不兼容图片显示不出来或者发布后变成一串神秘base64图片以Files对象或二进制格式存在HTML里只有一个引用占位没有走图片上传流程公式变成乱码或图片Word公式用的是OMML/MathType对象HTML里无法直接映射这里面最容易被误判的是第一种。如果你在清洗代码里用了innerHTML.replace(/style[\s\S]*?/gi, )那Word嵌在head里的样式表确实被删了但正文的内联font-family、font-size也被某些粗放的正则顺带清掉了。用户看到的结果就是“样式丢了”。1.3 判断粘贴来源的简单指纹处理之前先识别来源这一步不是强迫症而是为了采用不同的清洗策略。Word、WPS、普通网页复制的HTML结构差异非常大用同一套规则去洗一定会出现要么洗太狠、要么洗不干净的结果。识别方法很简单在HTML字符串里找特征function detectPasteSource(html) { if (!html) return plain; if (/class?Mso|urn:schemas-microsoft-com:office:office|\/\/\[if gte mso/i.test(html)) { return word; } if (/WPS|wps\.cn/i.test(html)) { return wps; } if (/html[\s\S]*?body/i.test(html)) { return web; } return unknown; }这个函数我放在工具库最前面所有后续的样式映射逻辑都围绕它展开。Word和WPS虽然都是国产办公环境高频出现的但WPS生成的私有标签和Word并不完全一样需要单独处理。2. 为什么“原样粘进去”和“纯文本粘进去”两条路都走不通2.1 原样粘贴浏览器会留下一堆你看不见的私人订制把Word生成的HTML直接塞进编辑器表面上是保留了样式实际上等于把一个带私有命名空间的文档硬塞进Web页面。Word输出的HTML里充满了类似这样的标记html xmlns:ourn:schemas-microsoft-com:office:office xmlns:wurn:schemas-microsoft-com:office:word xmlns:vurn:schemas-microsoft-com:vml head !--[if gte mso 9]xmlw:WordDocument.../w:WordDocument/xml![endif]-- style page WordSection1 {size:595.3pt 841.9pt; margin:72.0pt 72.0pt 72.0pt 72.0pt;} p.MsoNormal, li.MsoNormal, div.MsoNormal {margin:0cm; margin-bottom:.0001pt; ...} /style /head body p classMsoNormal styletext-indent:24.0pt; span stylefont-size:14.0pt;font-family:等线;color:#333333;内容/span /p /body /html注意这里的几个特征o:p这种标签在HTML5里根本不存在MsoNormal这类类名没有任何全局CSS定义pt单位在浏览器里虽然能识别但如果你没有对应的CSS规则这些类名就是一堆死代码。直接插入的结果是页面上看起来也许正常因为部分内联样式还能生效但一旦编辑器需要把内容转存到另一个平台比如生成公众号文章、导出PDF、同步到CMS这些私有标签就会原形毕露。典型的例子就是Word表格里的列宽设置它依赖colgroup里的width值和table-layout: fixed脱离Word环境后经常出现“列宽无法拖动”的诡异现象这在热搜词里也频繁出现。2.2 纯文本粘贴样式保住了语义丢了另一种极端是只读text/plain禁止一切HTML进入。这种做法的好处是绝对安全、绝对不会出现XSS也不会看到任何私有标签缺点同样致命用户从Word复制一个带标题、列表、加粗、有序层级的内容进来全部变成一段没有结构的文字。这时候用户反馈同样是“样式丢失”但和第一种不同的地方在于这次连语义都没了。前端可以把它包装成“用纯文本模式粘贴”但对编辑者来说他的排版意图全丢了等于整个复制动作白做。我之前的团队就有一版这样的实现产品经理在验收时把一个多级列表粘进去发现编号全部消失当场就否了。纯文本只能作为兜底不能作为主方案。2.3 编辑器自带清理为何经常帮倒忙现在很多富文本编辑器都自带粘贴过滤比如TinyMCE、CKEditor、wangEditor、Quill都有所谓的“清除格式”机制。但它们针对的是常规网页复制场景Word的私有结构并没有被完整覆盖。举几个我见过的实际表现有些编辑器会把Word的o:p标签保留成空段落导致粘贴后出现大量空白行有些编辑器会把Word的mso-spacerun:yes处理成一连串nbsp;删除文字时出现“一个字符一个空格”的奇怪现象有些编辑器自带规则会删除所有style只留下strong、em这类语义标签导致字号颜色全部丢失。这些行为的本质是编辑器的内置清理器不够了解Word的私有约定。它不是完全不能用但直接默认开启效果就是“时灵时不灵”。所以下面这种自定义清洗流程在很多项目里是绕不开的一步。3. 一套可落地的清洗流程拦截、解析、白名单重建3.1 第一步在paste事件做数据源分流清洗流程的入口是拦截paste事件然后根据数据源类型走不同的分支。这里的关键点是不要阻止默认行为之前就做异步操作否则剪贴板数据会失效。我习惯的写法是这样的editorRoot.addEventListener(paste, async (e) { const cd e.clipboardData || window.clipboardData; const html cd.getData(text/html); const plainText cd.getData(text/plain); const source detectPasteSource(html); if (source word || source wps) { e.preventDefault(); const cleaned cleanWordHTML(html); insertIntoEditor(cleaned); } else if (html) { // 普通网页复制按编辑器默认规则处理 return; } else if (plainText) { e.preventDefault(); insertIntoEditor(escapeHtml(plainText)); } });这里有个容易踩的细节e.preventDefault()必须在读取剪贴板之后、且在同步代码里调用。如果你先await了一个上传图片的接口再阻止默认行为某些浏览器会直接清空剪贴板内容导致getData拿到空串。3.2 第二步用DOMParser剥掉微软私有标记拿到Word的完整HTML字符串之后我不会用正则去做全局替换而是先用DOMParser把它变成真实的DOM树再做元素级清洗。正则处理嵌套标签太容易出错比如span style...里的style值可能包含字符或属性值里有引号都可能导致一次性match失败。基本的清洗函数骨架function cleanWordHTML(html) { const doc new DOMParser().parseFromString(html, text/html); // 删掉微软专用的命名空间声明 document.querySelectorAll(*).forEach(el { [...el.attributes].forEach(attr { const name attr.name.toLowerCase(); const value attr.value || ; // 剥掉 xmlns:o / xmlns:w / xmlns:v 等 if (name.startsWith(xmlns:)) { el.removeAttribute(attr.name); } // 剥掉所有 mso- 开头的属性或值 if (/^mso-/.test(name) || value.includes(urn:schemas-microsoft-com)) { el.removeAttribute(attr.name); } // Word 会在 class 里写 MsoNormal、MsoHeader、MsoListParagraph if (el.className /Mso|WordSection|ms-/.test(el.className)) { el.className el.className .split(/\s/) .filter(c !/Mso|WordSection|ms-/.test(c)) .join( ); } }); }); // 处理特定标签 doc.querySelectorAll(o\\:p, w\\:p, o:p, w:p).forEach(node { const p doc.createElement(p); while (node.firstChild) p.appendChild(node.firstChild); node.replaceWith(p); }); // 处理 Word 的连续空格占位 doc.querySelectorAll([mso-spacerunyes], span[mso-spacerun]).forEach(node { node.replaceWith(doc.createTextNode(node.textContent)); }); // 清理空span doc.querySelectorAll(span).forEach(span { if (span.childNodes.length 0 || span.textContent.trim() ) { span.remove(); } else if (!span.getAttribute(style) !span.getAttribute(class)) { span.replaceWith(doc.createTextNode(span.textContent)); } }); return doc.body.innerHTML; }这里的核心逻辑是先清理命名空间和属性级的私有标记再处理标签级的私有标记最后压缩空节点。顺序很重要如果先删空span再处理o:p有些内容会被误删。3.3 第三步按需求映射Word样式到编辑器协议清洗掉私有标记之后还有一个核心问题没有解决Word的样式体系和浏览器/编辑器的样式体系不是一一对应的。这里需要做一个“映射决策”我列一个常用映射表Word / MS私有表现推荐处理方式说明字体font-family:等线, 宋体, sans-serif保留为内联样式但补一份通用字体栈用户本机字体≠读者本机字体需要兜底字号font-size:14.0pt转成14px或换算成em如果目标是打印保留pt如果是H5展示转px首行缩进text-indent:21.0pt转成text-indent:2em或21px视觉一致性更好也适配移动端行距line-height: 150%保留百分比浏览器支持良好主题色mso-themecolor提取对应的十六进制色值Word主题色在网页上没有定义必须落到具体色值表格width:415.3pt转成百分比或auto固定pt宽在响应式布局下会撑破页面边框border:.5pt solid windowtext转成1px solid #000或按需简化windowtext不是合法CSS颜色单位换算这部分如果项目里用的是px体系我在工具函数里写了一个简化版的pt转pxfunction ptToPx(val) { const num parseFloat(val); if (isNaN(num)) return val; // 浏览器标准1pt 4/3 px return Math.round(num * 4 / 3) px; }把Word的—.0pt统一转成px之后编辑器和最终渲染端对样式的解析就没有歧义了。这段映射逻辑取决于你的目标场景如果是做仿A4纸打印那保留pt反而更好。关键在于“先明确目标再决定映射规则”不要一刀切。3.4 第四步把结果交给编辑器并防止二次粘贴清洗完的HTML最终要插入编辑器。不同编辑器的插入API不同但思路大同小异// 原生contenteditable function insertIntoEditor(html) { const sel window.getSelection(); if (sel sel.rangeCount 0) { const range sel.getRangeAt(0); range.deleteContents(); const frag range.createContextualFragment(html); range.insertNode(frag); } } // wangEditor 或类似编辑器 // editor.insertHTML(cleanedHTML) // Quill // quill.clipboard.dangerouslyPasteHTML(cleanedHTML) // TinyMCE // editor.execCommand(mceInsertContent, false, cleanedHTML)有个细节清洗后插入会触发新的DOM操作某些编辑器会再次执行粘贴过滤器。所以要在插入前设置一个标志位let isHandlingPaste false; editorRoot.addEventListener(paste, (e) { if (isHandlingPaste) { e.preventDefault(); return; } isHandlingPaste true; try { // 清洗并插入 } finally { setTimeout(() { isHandlingPaste false; }, 0); } });这个标志能避免“插进去的内容又被编辑器二次清洗”的问题尤其是Quill这类会监听DOM变化的编辑器不加这层保护很容易出现粘贴内容再被处理一遍的情况。4. 哪些场景直接用编辑器内置能力哪些必须自己动手4.1 常用编辑器对Word粘贴支持的现状如果项目只是简单后台文档格式不复杂那么优先使用编辑器自带能力是更理性的选择自己维护清洗函数是有成本的尤其在后续迭代中很容易因为边界case反复修补。几个主流编辑器的情况编辑器对Word粘贴的内置支持适用场景TinyMCEpaste插件提供paste_word_valid_elements等配置能处理大部分常规标签只需要基础标题、段落、列表、加粗的团队CKEditor 5官方提供Paste from Word插件对Word样式映射做得比较细需要保留色彩、字体、表格形状的中后台系统Quillclipboard模块有matcher机制但没有专门针对Word的完整方案定制性强但需要自己补一套Word过滤器wangEditor内置了基础的粘贴过滤复杂表格仍会出问题国内项目用的多适合快速交付这些编辑器内置的方案能解决80%的“样式丢失”问题。那剩下的20%恰恰是导致用户崩溃的场景合并单元格、图片跨域、公式、多级列表编号、文档目录域。4.2 何时要自己维护过滤函数我个人的判断标准很简单看你的产品有没有“样式必须严格还原”的需求。如果用户从Word复制了一份合同里面表格有复杂的合并单元格、固定列宽、页眉页脚那编辑器内置插件基本撑不住。这种情况下建议自建清洗流程但不要把清洗函数挂在页面里而是放到独立的utils/paste-sanitizer.ts模块里方便单元测试。这个模块至少包含下面这些函数detectSource(html)判断数据来源cleanWordHTML(html)剥离私有标记mapWordStyles(html)统一单位、颜色、字体栈sanitizeTags(html)白名单标签过滤删除script、iframe、object等危险节点stripEmptyNodes(html)清理空段落和多余空格。值得划清边界的是样式清洗和XSS过滤是两件事不要合并成一个函数。样式清洗的职责是把Word结构转成可接受的HTMLXSS过滤的职责是确保任何情况下都没有可执行脚本进入页面。两者偶尔会重叠比如a hrefjavascript:...既是样式问题也是安全问题但它们的处理逻辑完全不同。4.3 前端过滤和后端消毒职责怎么划分我在团队内部一直强调前端清洗是体验后端消毒是底线。前端做得再好也不能保证所有编辑器都走同一套流程。某些用户可能绕过前端直接调接口提交内容所以后端必须再做一次严格的标签白名单过滤。常见分工是层关注点工具参考前端样式映射、单位换算、图片上传、粘贴体验自定义清洗函数、DOMParser后端XSS防护、非法标签删除、属性白名单Java可参考OWASP Java HTML SanitizerNode可参考DOMPurify的服务端版这里尤其要警惕的是只依赖前端清洗会留下一条安全漏洞链路。Word粘贴的HTML可以携带iframe、object、javascript:协议链接甚至通过data:协议嵌入内容。浏览器自己会拦一部分但拦不住的场景比你想象的多。一个具体例子p styletext-indent:21.0pt; a hrefjavascript:alert(1)点我领取奖品/a /p img srcx onerroralert(document.cookie)如果清洗函数只看src和href而不检查协议这两条都能造成实际风险。白名单方案是标签白名单确认、属性白名单确认、协议白名单只允许http和https最后再把on*开头的属性全部删掉。5. 上线后最容易翻车的四个边界场景5.1 图片粘贴变成base64导致文档体积爆炸Word里插的图片在剪贴板里通常有两种存在形式一种是直接嵌在HTML里的base64字符串另一种是放在clipboardData.files里的二进制文件。前者会让整段HTML变得巨大一个2MB的图片经过base64编码后约等于2.7MB的文本这还没算其他格式的重复存储。处理图片的正确方式是在paste事件里捕获getAsFile()提前上传到对象存储然后用返回的URL替换HTML里的图片引用for (const item of cd.items) { if (item.type item.type.startsWith(image/)) { const file item.getAsFile(); const url await uploadFile(file); // 上传到你的CDN或OSS // 拿到url后替换HTML中对应的临时img占位 } }不处理这个问题的后果是内容提交时体积爆炸接口超时、上传失败都是家常便饭。之前我们线上出现过一次事故用户粘贴了一份带十张截图的Word进公告编辑器提交数据接近30MB网关直接拒收。5.2 Word表格粘贴后列宽无法拖动热搜词里“word 表格列宽无法拖动”说明这个问题绝对不是个例。Word自动生成的表格HTML长这样table classMsoNormalTable stylewidth:415.3pt; border-collapse:collapse; table-layout:fixed; colgroup col stylewidth:92.15pt col span2 stylewidth:77.8pt /colgroup tbody tr td stylewidth:92.15pt; border:solid windowtext 1.0pt;.../td /tr /tbody /table问题在于table-layout: fixed和colgroup的固定pt宽度。网页表格的列宽在fixed模式下完全由第一行决定用户想拖拽调整时发现拖不动或者拖了之后表格马上错乱。我的处理方式是在清洗阶段把colgroup直接移除把table上的固定宽度清掉让表格进入auto模式doc.querySelectorAll(table).forEach(table { if (table.getAttribute(style)) { let style table.getAttribute(style); style style.replace(/width:[^;]/gi, ); style style.replace(/table-layout:\s*fixed/gi, table-layout: auto); if (style.trim()) { table.setAttribute(style, style); } else { table.removeAttribute(style); } } table.querySelectorAll(col, colgroup).forEach(col col.remove()); });这样处理之后表格宽度变成自适应编辑器里也能正常拖动列宽。代价是原文档的精确版面比例会被打破但从Web展示的角度看反而更符合响应式需求。5.3 样式“时灵时不灵”字体、主题色、特殊符号的坑有一个很经典的坑用户说“我在Word里明明把标题设成了红色粘到编辑器却变成黑色”。排查后发现Word里设置的颜色不是具体色值而是主题色。主题色在HTML里的表现是span stylecolor:#C00000;mso-themecolor:accent1;如果没有读到mso-themecolor对应的色值只看到#C00000那确实能正常显示。问题出在另一种情况Word生成HTML时color:#C00000没有落到内联style里而是放在了一段公共样式表中加了一个类似WPS的随机类名。编辑器只保留了标签没保留类名对应的CSS于是颜色就“凭空消失”了。解决思路是如果检测到mso-theme开头的属性就用Word主题色映射表手工转成十六进制色值。这个映射表网上有公开数据也可以让后端在解析阶段统一转换。字体“时灵时不灵”的坑更隐蔽。Word文档常用的字体如“等线”“微软雅黑”“宋体”用户本机有但发布之后读者本机未必有。内联样式写成font-family:等线;在Windows上正常在macOS或手机上就会回退到默认字体用户同样会理解为“样式丢了”。所以清洗时我习惯把中文字体栈补全font-family:Microsoft YaHei,PingFang SC,Hiragino Sans GB,sans-serif;这样至少能保证不同设备上的视觉落差不会太大。5.4 安全风险Word粘贴内容离XSS只差一步上面提到过Word生成的HTML里有命名空间、有注释条件块、有object标签天然就是HTML注入的温床。更麻烦的是用户从网页复制一段内容再粘到Word再复制出来这个过程中浏览器的解析机制可能把原本安全的HTML重新编码成诡异的结构里面的script不一定能按原样活下来但iframe、javascript:协议链接完全可能残留。所以清洗函数必须做成白名单制而不是黑名单制。黑名单是“我知道哪些危险所以删掉哪些”但Word粘贴产生的标签变体太多了根本列不完。白名单是“我只留下列表里的标签和属性其他全部删掉”。一个最小的白名单配置const ALLOWED_TAGS new Set([ p, div, br, span, h1, h2, h3, h4, h5, h6, ul, ol, li, table, thead, tbody, tr, td, th, img, a, strong, em, u, s, blockquote, pre, code ]); function sanitizeNode(node) { if (node.nodeType Node.ELEMENT_NODE) { const tag node.tagName.toLowerCase(); const allowedAttrs new Set(); if (!ALLOWED_TAGS.has(tag)) { node.replaceWith(document.createTextNode(node.textContent)); return; } [src, href, alt, title, style, colspan, rowspan].forEach(attr { if (node.hasAttribute(attr)) { allowedAttrs.add(attr); } }); // 属性级过滤 if (node.tagName A) { const href node.getAttribute(href) || ; if (!/^https?:\/\//i.test(href) href ! #) { node.removeAttribute(href); } } if (node.tagName IMG) { const src node.getAttribute(src) || ; if (!/^https?:\/\/|^data:image\//i.test(src)) { node.removeAttribute(src); } } [onclick, onerror, onload, onmouseover].forEach(evt node.removeAttribute(evt)); } }后端必须再做一次同样级别的过滤不要觉得前端做了就万事大吉。前端过滤的目的是给用户一个可阅读的结果后端过滤的目的是保护读者和服务器两者缺一不可。6. 我的实践体会与一点小建议如果你问我“Word转存编辑器样式丢失”这个问题到底要怎么根治我会说没有一套代码能覆盖所有场景。Word能输出的HTML变体实在太多了不同版本、不同语言、不同字体插件、不同表格结构都会产生新的特征。我们能做的是把方案设计得足够健壮数据源识别、标签白名单、单位换算映射、图片上传机制、后端二次过滤每一层都承担一部分职责而不是指望一个正则函数解决所有问题。我个人踩过最值的一次坑是在排查表格边框丢失时发现用户看到的“边框消失”不是标签问题而是Word输出的border-color:windowtext被浏览器当成非法值丢掉了。把windowtext识别成黑色才能解决。这类边界问题只有靠线上真实用户的粘贴数据反复喂养你的清洗函数才会越来越稳。最后分享一个小习惯在所有粘贴入口加上来源指纹和关键阶段的日志输出记录粘贴源类型、清洗前后HTML长度、删除标签数量、是否有图片上传失败。线上出了“样式丢失”的工单不要靠猜直接看日志定位到是读取、清洗、映射还是上传环节出了问题。这套流程修下来再复杂的Word文档也不会让你连着加班两周了。
