信创环境下XHEDITOR粘贴Word公式的兼容方案与实践

网上聊到“信创环境 + XHEDITOR + Word公式粘贴”的时候，绝大多数人是真的被磨到没脾气才搜进来的。我在政务项目里折腾这套东西前后大半年，把能踩的坑基本踩完了。这篇文章不聊虚的，核心就一件事：在信创环境下，怎么让XHEDITOR老老实实把Word里复制过来的公式接住、转对、渲染出来，而不是变成一张残图、一段乱码，或者干脆消失。

先说结论：Word公式粘贴进信创Web编辑器，本质不是“粘贴”的问题，而是“三种格式互相翻译”的问题。你在Word里看到的公式，在剪贴板里往往同时存在好几种形态，而信创环境下的国产浏览器、国产系统、在线编辑器控件又各有各的脾气，导致这个翻译过程哪一环断了，公式就废了。下面我会从底层原理讲到选型思路，再给出一套可以直接复用的实现链路和排错清单，希望能帮你少加两周班。

1. 一个让所有信创项目头疼的拼接场景：Word公式进不了XHEDITOR

1.1 项目背景与核心需求

我们当时做的系统是一个面向政企客户的内容管理平台，在线文档编辑这块选型的是XHEDITOR这个Web富文本编辑器组件。业务场景很典型：办公室的人用WPS或国产Office写好公文、技术方案，里面带数学公式、化学方程式，然后复制粘贴到网页端继续编辑、审批、归档。

按理说这是个再普通不过的操作，但在信创环境下，问题被放大了好几倍。首先是操作系统，信创终端基本是麒麟、统UOS、中科方德这类国产系统；其次是浏览器，Chromium内核的国产浏览器占了绝大多数，但内核版本从74到120都有，还有个别单位用Firefox ESR的适配版本；再叠加我们项目里还嵌了电子签章、版式文件插件，剪贴板访问被各种安全策略拦了一道。

在这个环境下，XHEDITOR里的公式粘贴出现了三种典型故障：一是公式粘贴后变成一个小方块或者空白，图形丢了；二是粘贴进一大段带VML和条件注释的HTML，公式位置变成一个巨大的base64图片，版面错乱；三是公式变成了 {EQ \f(1,2)} 这样的域代码，用户直接看懵。

1.2 这个问题的本质边界

我把这个项目里反复出现的现象做了归类，最后发现真正要解决的其实是三个方面的问题：

• 剪贴板里公式数据的识别。能拿到哪些数据、拿不拿得到，每个浏览器表现不一样。
• 公式格式的互相转换。Word用OMML，标准网页用MathML，渲染引擎常用LaTeX，三套体系要能对上。
• 渲染与回写。转换后的公式要能在XHEDITOR里以可编辑、可保存、可导出的方式存在，而不只是截一张图。

如果你也存在这几个问题，那这篇文章的内容基本就是为你准备的。下文的所有方案都来自我实际跑通过的环境，不是那种纯理论分析。

2. 先搞明白Word公式在剪贴板里到底长什么样

2.1 剪贴板中公式的几种存在形态

很多人一上来就去找“万能转换库”，结果发现库根本没用，因为第一步就没搞对——你连剪贴板里那个“公式”是什么格式都没确认。以我实测的结论，Word或WPS复制公式到剪贴板后，通常会以以下几种形态出现。

这里面有个重要细节：绝大多数情况下，你在Web编辑器里通过 paste 事件拿到的 text/html，并不是剪贴板里的全部内容。剪贴板是一个多格式数据仓库，同一份公式可能同时携带OMML、HTML、纯文本多种表示。浏览器暴露出来的通常是经过解析的HTML片段，OMML可能被包裹在 <!--[if gte mso 9]> 的条件注释里，也可能以HTML命名空间标签的形式裸露在DOM中。

2.2 为什么信创环境更容易“翻车”

我在非信创环境（Windows + Chrome + 在线Office）测试时，Word公式粘贴经常是能出一个图片的，虽然不可编辑，但至少“看着还在”。同样是这段内容，放到信创环境就特别容易翻车，原因有几个：

第一，国产浏览器的Chromium内核版本太杂。有些单位的安全浏览器还是Chromium 74这个级别，对MathML的支持惨不忍睹，对剪贴板自定义MIME Type的过滤也更激进。在WebKit内核的浏览器上能拿到的数据，在国产浏览器里直接被安全策略弹掉。

第二，信创终端上经常不是完整版Office，而是WPS或统信自带的办公套件。WPS在剪贴板里的公式HTML结构跟微软Office差得远，很多场景下它直接把公式转成图片，甚至把图片转成base64内嵌进HTML，识别逻辑就得额外兼容。

第三，信创环境里第三方插件冲突太多了。输入法、电子签章、打印控件，都会监听剪贴板。我遇到过粘贴事件里的 clipboardData 返回 null 的情况，也有拿到的HTML头尾被截断的情况。这些东西在Windows + Chrome下很难复现，一旦换到国产终端就各种五花八门。

2.3 格式转换的关键路径

在我实现兼容方案之前，先画了一条逻辑链路：OMML → MathML → LaTeX/Katex渲染。为什么最终渲染选择LaTeX，而不是直接让浏览器原生渲染MathML？因为信创浏览器对MathML原生支持的不确定性太大，而XHEDITOR的渲染区域本质是 contenteditable，用MathJax做整体页面扫描又太重，最终我用的是KaTeX的服务端渲染和前端渲染混合方案。

这里要形成一个认知：Word公式粘贴的“兼容”不是让所有格式都原封不动进编辑器，而是让系统先识别出公式区域，再统一转换到一条可控的渲染链路上。所有识别不了的，一律降级为图片并给出提示，而不是无声无息丢内容。

3. 兼容方案怎么选？三条路线的取舍

3.1 方案A：粘贴成图片，最省事但最坑

很多项目组为了赶工期，直接在主流程里把公式全部转成图片存到后端。这样做短平快，渲染层绝对兼容，因为图片在哪个浏览器里都能显示。但缺陷非常明显：公式不可编辑、不能全文检索、缩放后模糊、打印版式偶尔错位。更致命的是在信创环境中，图片格式本身也乱——有的Word/WPS粘贴出来是WMF或EMF，浏览器根本不渲染，必须后端转PNG，又增加一道服务。

所以我们把纯图片方案定位为“兜底预案”而不是主方案。仅当公式信息已经不可逆时（比如只能拿到图片数据），才走这个通道。

3.2 方案B：粘贴成MathML，兼容性好但渲染层要选对

MathML是W3C标准数学标记语言，好处是能在现代浏览器和排版软件间无损交换。坏处是信创终端上的浏览器对MathML的本地支持参差不齐。Chrome从109版本起才开始原生支持MathML Core，而很多国产浏览器还在80多的内核上挂着。

如果用MathML做存储格式，在旧版内核里展示时就要引入MathJax这样的库来兜底。MathJax体积大、启动慢，在线编辑器里每粘贴一个公式就整体重排一次，体验会打折扣。实测在低配信创终端上（我测过一款兆芯CPU的笔记本），MathJax渲染一个复杂分式公式要等几百毫秒，用户会认为是卡死了。

所以MathML在我的方案里是“中间格式”，不是最终呈现格式。

3.3 方案C：统一转LaTeX并用KaTeX渲染，我最终选的主路线

LaTeX公式语法在Web渲染领域生态最成熟。KaTeX的渲染速度比MathJax快一个量级，支持服务端渲染成HTML字符串，也可以前端实时渲染。关键一点是KaTeX不依赖系统数学字体，它会自动加载Web字体，这对信创环境下的字体缺失问题有奇效。

于是整体架构定为：

• 粘贴时从HTML片段中提取OMML或MathML。
• OMML统一转成MathML。
• MathML转成LaTeX字符串，同时用KaTeX渲染成HTML。
• 如果转换失败，保留原始图片并落库，同时把LaTeX存到自定义属性里备用。

这个方案牺牲了一点“所见即所得”的公式编辑能力，但换来了可靠的页内渲染、全文检索和跨浏览器一致性。用户体验上的妥协靠工具条弥补——在编辑器里提供一个“公式编辑”按钮，点击后弹窗编辑LaTeX源码并实时预览。

3.4 方案选型对比表

选型时别光看技术指标，还要看业务诉求。我们的业务需要公式参与文档标题检索，还要支持导出PDF、DOCX，所以公式必须用可检索的文本格式存储，而不是图片，这就直接排除了纯图片方案。

4. XHEDITOR内实现公式粘贴兼容的完整链路

4.1 环境准备与依赖选型

我们项目前端用的是Vue3 + Vite，XHEDITOR以组件形式嵌入。依赖上我选了这么几个：

• katex：公式渲染，体积相对可控。
• mathml2latex：MathML转LaTeX。
• xpath或DOMParser：解析HTML节点。
• OMML转MathML，我没有用npm包，而是直接用微软公开的XSLT样式表来做转换，这样可控性和精确度都最高。

如果你用的是Java后端，也可以选 docx4j 或者直接调用Pandoc，但考虑到公式粘贴这个动作发生在前端，我把转换链路尽量往前端放，减少网络往返。

4.2 粘贴事件拦截与内容识别

XHEDITOR是 contenteditable 架构，所以标准 paste 事件必然能拦截。第一步是阻止默认粘贴行为，然后自己读取剪贴板数据。

javascript复制editor.element.addEventListener('paste', async (event) => {
  // 信创环境下部分安全插件会吞掉 clipboardData，需要多做一层防御
  const cd = event.clipboardData || window.clipboardData;
  if (!cd) {
    insertFormulaErrorTip('无法读取剪贴板，请使用公式编辑按钮录入');
    event.preventDefault();
    return;
  }

  const html = cd.getData('text/html');
  const plainText = cd.getData('text/plain');

  // 没有HTML内容时，大概率是纯文字，交给默认处理
  if (!html) return;

  event.preventDefault();
  
  const formulaResult = await analyzeAndConvertFormula(html, plainText);
  
  if (formulaResult.hasFormula) {
    // 有公式，走自有链路
    insertFormulaHtml(formulaResult.processedHtml);
  } else {
    // 没有公式，恢复默认粘贴逻辑
    insertPlainOrRichHtml(html);
  }
});

这个拦截有个容易被忽略的坑：不是所有粘贴内容都含公式，如果每次粘贴都走一遍自定义转换，会把普通文本的换行、加粗、表格样式全部打乱。所以要先判断HTML里是否存在公式特征节点，没有再放回默认粘贴流程。

4.3 从HTML中提取OMML与MathML节点

粘贴进来的HTML是带命名空间的XML片段，不同来源的公式标签并不统一。常见的有：

• <m:oMath>：新版Word
• <m:oMathPara>：Word段落级公式
• <math>：MathML
• <o:OLEObject>：OLE对象，可能是旧公式编辑器
• <v:shape>：VML图形

我的做法是用 DOMParser 解析HTML字符串，然后递归遍历所有节点，按节点名做分类处理。这段代码很关键：

javascript复制function extractFormulaNodes(htmlString) {
  const doc = new DOMParser().parseFromString(htmlString, 'text/html');
  const formulaNodes = [];
  
  const oMathNodes = doc.querySelectorAll('m\\:oMath, m\\:oMathPara');
  oMathNodes.forEach(node => {
    formulaNodes.push({ type: 'omml', node });
  });

  const mathNodes = doc.querySelectorAll('math');
  mathNodes.forEach(node => {
    formulaNodes.push({ type: 'mathml', node });
  });

  // 无命名空间时，部分国产浏览器会丢掉前缀，仍然按标签名匹配
  const genericMathNodes = doc.querySelectorAll('oMath, oMathPara');
  genericMathNodes.forEach(node => {
    formulaNodes.push({ type: 'omml', node });
  });

  return formulaNodes;
}

注意一个细节：有些国产浏览器在解析粘贴HTML时去掉了命名空间前缀，导致标准选择器匹配不到。这就是为什么我加了一句 oMath, oMathPara 这种通用匹配。这也是我在实际项目中踩过的坑，最初只按带前缀的写法做，结果在WPS + 奇安信浏览器环境下，公式直接漏掉。

4.4 OMML转MathML的XSLT实现

OMML转MathML的官方XSLT样式表是微软在Office Open XML标准里提供的，网上能搜到 OMML2MML.XSL。我把它内置到前端资源里，用浏览器XSLT处理器执行转换。

javascript复制function convertOmmlToMathml(ommlNode) {
  // 将节点包装为完整XML片段
  const xmlSerializer = new XMLSerializer();
  const ommlString = xmlSerializer.serializeToString(ommlNode);
  
  // 使用内置XSLT转换
  const xsltProcessor = new XSLTProcessor();
  const xslDoc = loadXsltDocument(); // 加载OMML2MML.XSL
  xsltProcessor.importStylesheet(xslDoc);
  
  const ommlDoc = new DOMParser().parseFromString(ommlString, 'application/xml');
  const resultDoc = xsltProcessor.transformToDocument(ommlDoc);
  const result = new XMLSerializer().serializeToString(resultDoc);
  
  return result; // MathML字符串
}

这里要特别说一个实际操作要点：XSLTProcessor 在Chromium内核的国产浏览器里支持程度差异很大，我遇到过在某个安全浏览器上直接抛“未定义”的情况。所以前端转换不能作为唯一通道，必须做服务端转换兜底。

服务端我用Java实现了一个转换接口，输入OMML字符串，输出MathML。核心思路是把OMML wrapper包成最小WordprocessingML标签，再通过Java的 Transformer 应用XSLT。

java复制public String omml2Mathml(String omml) throws Exception {
    String template = "<w:document xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\" "
        + "xmlns:m=\"http://schemas.openxmlformats.org/officeDocument/2006/math\">"
        + "<w:body><m:oMathPara>" + omml + "</m:oMathPara></w:body></w:document>";
    
    Source xmlSource = new StreamSource(new StringReader(template));
    Source xsltSource = new StreamSource(new FileInputStream("OMML2MML.XSL"));
    
    TransformerFactory factory = TransformerFactory.newInstance();
    Transformer transformer = factory.newTransformer(xsltSource);
    
    StringWriter writer = new StringWriter();
    transformer.transform(xmlSource, new StreamResult(writer));
    return writer.toString();
}

前端调用转换接口时，如果前端本地转换成功就优先用前端结果，失败才落到后端接口。这个“前端优先、后端兜底”的模式在信创项目里很好用，能显著降低单点依赖。

4.5 MathML转LaTeX并渲染

拿到MathML之后，我用 mathml2latex 库将MathML转成LaTeX字符串。如果转换结果为空或者还是原样，说明公式结构太复杂或者MathML不合法，此时直接降级为“原样保留MathML + 图片”。

javascript复制import { MathMLToLaTeX } from 'mathml2latex';

function mathml2latex(mathmlString) {
  const converter = new MathMLToLaTeX();
  const latex = converter.convert(mathmlString);
  return latex;
}

再调用KaTeX渲染成可以直接插入编辑器的HTML：

javascript复制import katex from 'katex';

function renderLatexToHtml(latex) {
  try {
    return katex.renderToString(latex, {
      throwOnError: false,
      displayMode: false,
      output: 'html',
      trust: false
    });
  } catch (e) {
    console.error('KaTeX渲染失败', e);
    return '';
  }
}

渲染结果插入XHEDITOR时，我在公式外层包了一个自定义标签：

html复制<span class="xh-formula" data-latex="\frac{1}{2}" data-mathml="...渲染后HTML...">
  <!-- KaTeX生成的HTML -->
</span>

data-latex 和 data-mathml 是给后续后端导出使用的。这样不管最终存档是走富文本HTML转PDF还是转Word，都能从自定义属性里再提取公式源码。

4.6 图片公式的回退处理

如果粘贴到的内容里公式已经被转成图片，这就要分两种情况处理。

第一种是HTML里还能看到 v:shape 和 img，但图片源是WMF/EMF，信创浏览器无法渲染。这种情况下我们会把公式区域整体替换为提示文案，同时在后端保留原始docx文件，等文档归档时再从docx中提取原公式。

第二种是图片本身是PNG或SVG，浏览器能显示。此时我们不做公式识别，直接把图片作为图片插入编辑器，并把图片上传到后端对象存储。这样至少保证内容不丢，只是公式不具备可编辑性。

javascript复制async function handleImageFormula(imgElement) {
  const src = imgElement.getAttribute('src') || '';
  if (!src) return null;
  
  // 如果是base64图片，先上传到后端换取url
  if (src.startsWith('data:image')) {
    const uploadedUrl = await uploadBase64Image(src);
    return `<img src="${uploadedUrl}" class="xh-formula-image" />`;
  }
  
  // 如果是WMF/EMF，直接拒绝渲染并提示
  if (src.endsWith('.wmf') || src.endsWith('.emf')) {
    return `<span class="xh-formula-error">[公式暂不支持显示，请下载原文档查看]</span>`;
  }
  
  return `<img src="${src}" class="xh-formula-image" />`;
}

这里必须强调一点：图片方案永远是最后手段，不要轻易让主流程落入图片分支。一开始我们为了快速上线，把图片命中率调得过高，结果导致后续用户反馈“公式不能改”，回头改成可编辑方案时，历史数据已经攒了一大堆图片，迁移成本极高。

4.7 与XHEDITOR工具栏和命令的集成

光在粘贴事件里处理还不够，用户还会希望粘贴之后能再次编辑公式。我们在XHEDITOR工具栏里加了一个“公式编辑”按钮，点击时读取光标附近的 .xh-formula 节点，拿到 data-latex 后在弹窗里编辑，编辑完成后再重新渲染一次替换原来节点。

这里有一个非常关键的操作细节：在替换公式节点时，千万不要直接操作 innerHTML，否则会破坏 contenteditable 的选区状态。正确的方式是找到公式节点后用 outerHTML 替换，然后手动触发一次编辑器内容同步。

javascript复制function replaceFormulaNode(formulaNode, newLatex) {
  const newHtml = renderLatexToHtml(newLatex);
  const wrapper = document.createElement('span');
  wrapper.className = 'xh-formula';
  wrapper.setAttribute('data-latex', newLatex);
  wrapper.innerHTML = newHtml;
  formulaNode.replaceWith(wrapper);
  editor.sync();
}

editor.sync() 在XHEDITOR里用于把DOM内容同步到编辑器内部缓存，不调用的话，保存文档时可能还是旧内容。这个细节非常坑，我在联调时经常遇到公式编辑完一保存就回滚，就是没触发同步。

5. 常见问题与排查技巧实录

5.1 问题速查表

5.2 几个容易忽略的排查点

第一个是浏览器对 text/html 数据的裁剪。我之前遇到过，HTML在剪贴板里是完整的，但经过国产浏览器的安全策略后，拿到的字符串尾部被截断，导致 DOMParser 解析后公式节点少了一部分。排查时可以用 console.log(html.length, html.slice(-500)) 看看尾部是否存在未闭合标签。如果尾部被截断，一个临时方案是补一个闭合标签再解析。

第二个是XSLT转换时命名空间不一致问题。OMML节点如果使用 m: 前缀但文档没声明对应的 xmlns:m，XSLT匹配会失败。解决办法是在序列化OMML字符串之前，先检查节点所属文档的根节点是否有正确的命名空间声明。如果缺失，需要动态补上。

javascript复制function ensureOmmlNamespace(ommlString) {
  if (!ommlString.includes('xmlns:m=')) {
    ommlString = ommlString.replace(
      '<m:oMath',
      '<m:oMath xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"'
    );
  }
  return ommlString;
}

第三个是KaTeX的字体加载时序问题。KaTeX渲染公式时依赖woff2字体，如果字体文件被部署在CDN或反代后面，加载慢会导致公式先闪烁再完全显示。在信创内网环境，首次加载几百个公式时特别明显。建议把KaTeX字体打包进项目本地静态资源，并且设置 preload 或 font-display: swap。

5.3 原创性实用技巧

这里分享几个我在实际项目中摸索出来的细节。

第一，在粘贴处理的HTML清洗阶段，保留一个“原始存档”。我通常不会直接修改原始的 html 字符串，而是先把它存到编辑器的临时缓存里，等整个转换链路全部走完且新内容插入成功后，再清掉。这样一旦转换逻辑有Bug，用户刷新页面后打开历史版本还能找回原始内容，不至于彻底丢数据。

第二，公式粘贴以后尽量用“占位符 + 延迟渲染”的方式。用户从Word复制一大堆内容，可能包含几十个公式，如果全部同步渲染，主线程会被KaTeX占满，低配信创终端直接卡死。我的做法是先插入一个轻量占位符（显示“公式加载中”），然后用 requestIdleCallback 或 setTimeout 分批渲染。这样用户看到的不再是整段空白，体验会好很多。

第三，一定要给公式粘贴失败留一个人工入口。哪怕转换链路再完善，总有特殊情况，比如公式里有无穷级数、矩阵、多行对齐这类复杂结构，转出来的LaTeX很可能语义不完整。我们在XHEDITOR的粘贴处理里加了一个“以图片粘贴”或“以LaTeX源码粘贴”的手动选择弹窗，用户可以在粘贴结果不如预期时主动切换模式。这个功能上线后，后台的转换失败工单量直接降了一半。

6. 后续扩展建议

公式粘贴只是信创环境下文档兼容性的一环。做完这个功能，我建议你把同样的思路复制到“从DOCX导入”和“导出Word”两条链路里。粘贴只是富文本编辑器的入口之一，用户还有大量已有文档需要通过导入功能进入系统。

后端导入DOCX时的推荐方案是Pandoc：

bash复制pandoc -f docx -t markdown+tex_math_dollars --extract-media=assets -o output.md input.docx

这条命令会把Word文档里的公式自动转成 $...$ 形式的LaTeX，同时把图片抽取到 assets 目录。之后再导入编辑器时，直接使用我们前面提到的KaTeX渲染链路，就能复用粘贴功能里的全部代码。导出Word反向操作时，用Pandoc把带 data-latex 公式的HTML还原成DOCX，也能保证公式以Word原生公式形式呈现，而不是一张图片。

如果你们项目文档数量多，对公式语义化要求高，还可以考虑在导入时顺便做一次公式归一化，把历史文档里散落的OMML、MathML、图片公式统一转成一种格式存库。这样未来的全文检索、公式比对、版本差异分析都会轻松很多。

最终我想说的是，信创环境下的兼容问题不会因为某个浏览器版本更新就彻底消失，因为操作系统、浏览器、应用软件的交叉矩阵实在太复杂。比较实际的策略是：把转换链路设计成多级兜底，前端能转就前端转，前端不行后端转，后端转不了保留原始数据。只要原始数据不丢，任何一层转换失败都有机会修复和补救。这套思路，比我最初试图用一套代码通杀所有情况的方案可靠多了。