在文档处理场景中,Word 与 OpenXML 之间的格式转换是一个出现频率较高的需求。将 Word 文档导出为 OpenXML 平面文件,可以剥离二进制包结构,便于跨系统数据交换、内容提取或归档;反过来,将结构化的 OpenXML 数据还原为 Word 文档,则能直接从已有数据生成规范的可编辑文档。本文介绍如何在 React 项目中,借助 WebAssembly 方案在浏览器端完成这两个方向的转换,全程无需后端服务参与。
一、技术背景与格式说明
基于 WebAssembly 的文档处理库在浏览器内通过虚拟文件系统(VFS)管理字体与文档资源。转换过程不依赖 Microsoft Word 或 Office 组件,文档数据始终留在客户端。
需要先明确的是,OpenXML 平面文件存在两种常见格式,对应不同的 Word 版本:
- WordML :Word 2003 使用的 XML 格式,保存时对应
FileFormat.WordML,根元素为<w:wordDocument>。 - WordXml(Flat OPC) :Word 2007 及以后版本使用的平面文件格式,保存时对应
FileFormat.WordXml,根元素为<pkg:package>。
两者虽然都能以 .xml 为扩展名输出,但内部结构并不相同。保存时需要根据目标 Word 版本选择对应的格式枚举值。若用低版本 Word 打开高版本格式保存的文件,会出现格式报错。
二、环境前提
以下示例假设文档处理库已安装,且 WebAssembly 模块已完成初始化(即 window.wasmModule.spiredoc 可用)。字体文件与待转换文档均需通过 FetchFileToVFS 载入虚拟文件系统后方可被文档引擎读取。项目中通常需要将 WASM 相关文件放置于 public 目录下,示例文档则放在 public/static/data/ 路径下,以确保构建后可正常访问。
在 React 组件中,每个转换函数都遵循同一套结构:检查模块就绪状态、载入输入文件、创建文档实例、加载并保存、释放资源、从 VFS 读取结果并触发浏览器下载。理解这一骨架后,两个方向的转换只是枚举值与输入输出文件名的差异。
三、将 Word 转换为 OpenXML
Word 转 OpenXML 分为两种输出格式,下面分别给出。
3.1 输出为 WordML(Word 2003 格式)
javascript
function App() {
const WordToWordML = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
let inputFileName = 'WordToWordXML.docx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);
const doc = new docModule.Document();
doc.LoadFromFile(inputFileName);
// 保存为 Word 2003 格式的 OpenXML 文件
const outputFileName = 'WordToWordXML-result.xml';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.WordML });
doc.Dispose();
const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([modifiedFileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>将 Word 文档转换为 WordML 文件</h1>
<button onClick={WordToWordML}>开始</button>
</div>
);
}
export default App;
通过 SaveToFile 指定 FileFormat.WordML 后,Word 文档被转换为一份 Word 2003 格式的 XML 平面文件。
3.2 输出为 WordXml(Word 2007 格式)
代码结构与上例一致,区别仅在于保存时的枚举值改为 FileFormat.WordXml,输出文件名也相应调整:
javascript
const WordToWordXml = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
let inputFileName = 'WordToWordXML.docx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);
const doc = new docModule.Document();
doc.LoadFromFile(inputFileName);
// 保存为 Word 2007 格式的 OpenXML 文件
const outputFileName = 'WordToWordXML-result-2007.xml';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.WordXml });
doc.Dispose();
const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([modifiedFileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
两种格式的选择应以实际使用场景中 Word 的版本为准。若下游系统需要被旧版 Word 打开,应选 WordML;若是现代 Office 环境或作为数据交换的中间格式,WordXml 更为通用。
四、将 OpenXML 转换为 Word
反向转换的逻辑同样直接:将符合规范的 OpenXML 平面文件载入 VFS,用 LoadFromFile 加载后,以 Word 格式保存即可。LoadFromFile 会根据文件内容自动识别 WordML 与 WordXml 格式。
javascript
function App() {
const XMLToWord = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
let inputFileName = 'XMLToWord.xml';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);
const doc = new docModule.Document();
doc.LoadFromFile(inputFileName);
const outputFileName = 'XMLToWord-result.docx';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
doc.Dispose();
const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([modifiedFileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>将 XML 文件转换为 Word 文档</h1>
<button onClick={XMLToWord}>开始</button>
</div>
);
}
export default App;
这里有一个容易忽略的前提:LoadFromFile 能够识别的是完整的 WordprocessingML 平面文件,而非任意自定义结构的 XML。如果输入文件的根元素不是规范所要求的结构,加载过程可能失败,或得到内容为空的文档。因此,输入 XML 应来源于 Word 或同类文档库的导出结果。
五、实践中需要注意的问题
字体缺失导致渲染偏差。WASM 环境不直接访问系统字体,若文档使用了特定字体而 VFS 中未载入对应字体文件,转换后的排版可能与原始文档存在差异。中文场景下建议至少载入一种中文字体到虚拟文件系统的字体目录。
资源释放 。每次转换结束后调用 doc.Dispose() 释放文档对象,避免在频繁转换的场景中累积内存占用。生成的 VFS 文件也可在下载触发后按需清理。
格式枚举的版本对应关系 。WordML 与 WordXml 并非同一格式的不同名称,而是分属不同 Word 版本的标准。混用会导致输出文件在目标 Word 中无法正常打开。保存为 Word 时 FileFormat.Docx2013 与 FileFormat.Docx 在多数场景下结果相近,但明确指定较新版本枚举值更为稳妥。
模块就绪检查 。示例中统一使用 window.wasmModule?.spiredoc 判空并在未就绪时给出提示,这是因为 WebAssembly 模块的初始化是异步的。在真实项目中,更稳妥的做法是在应用启动阶段完成初始化,再渲染转换按钮,避免用户点击时模块尚未加载完成。
六、小结
在 React 项目中使用 WebAssembly 方案进行 Word 与 OpenXML 的双向转换,核心操作集中在 FetchFileToVFS、LoadFromFile 和 SaveToFile 三个方法上。三个转换示例的代码骨架高度一致,差异主要体现在输入输出文件名与保存格式枚举值。实际落地时的主要成本在于格式枚举的正确选择、字体资源的预载以及输入文件规范性的把控。对于需要在浏览器端完成文档格式互转、且不希望引入后端服务的场景,这一方案具备可操作性。