在系统对接中,XML 常被当作文档的中间格式:上游导出、下游解析,或者归档留存。但“XML”在 Word 生态里并不是一种文件,而是好几种:有人指 Word 2003 的 WordprocessingML,有人指 Word 2007 起的扁平 OPC 包,也有人指某个组件自己的原生 XML。选错一个枚举值,得到的文件用 Word 要么打不开,要么只能看到满屏标签。
本文用 Spire.Doc for JavaScript 在浏览器中完成三个方向的转换。整个过程基于 WebAssembly 在浏览器端进行,不需要安装 Office,也不依赖后端服务,文档始终留在用户的设备上。
本文介绍三个核心功能点:
有关安装和项目配置,请参考 React 项目中集成 Spire.Doc for JavaScript。下面的示例假定 Spire.Doc 已安装、WebAssembly 模块已初始化。
三种 XML 格式的区别
FileFormat 里与 XML 相关的枚举值有三个,输出的是三种不同的文件,差别不在于写法,而在于“谁能读”:
| 枚举值 | 实际输出 | 能否在 Word 中按文档打开 |
|---|---|---|
FileFormat.Xml |
Spire.Doc 自有的 XML,根元素为 OML,UTF-16 编码,图片以 Base64 内嵌 |
不能,Word 会按通用 XML 展开成标签文本 |
FileFormat.WordML |
Word 2003 XML,根元素为 w:wordDocument |
可以,Word 2003 及以上 |
FileFormat.WordXml |
Word 2007 起的扁平 OPC,根元素为 pkg:package |
可以,Word 2007 及以上 |
三者都把整篇文档收进一个文件,不产生附件目录,图片也随文件一起走。选择时先看下游是谁:只在 Spire.Doc 内部往返、或者作为留档备份,用 FileFormat.Xml 最稳妥,属性保留得最全;要把文件交给 Word 或其他系统打开,就用 FileFormat.WordML 或 FileFormat.WordXml。
三者的体积差别不大,实测同一份两页的产品规格书:原 docx 约 58 KB,导出为 FileFormat.Xml 约 402 KB,FileFormat.WordML 约 383 KB,FileFormat.WordXml 约 450 KB。
将 Word 导出为 XML
把 Word 导出为 XML,通常是为了让另一个系统读取内容结构,而不是继续排版。XML 逐段记录样式、段落属性、表格与图片,比纯文本更完整,也比 docx 的二进制压缩包更容易被其他程序解析。
SaveToFile() 决定输出格式:传入的 fileFormat 是 FileFormat.Xml,得到的就是 Spire.Doc 自己的 XML。
具体操作步骤如下:
- 获取 Spire.Doc 的 WASM 模块,确认已就绪。
- 把中文字体与待转换的
ProductSpec.docx载入 VFS。 - 创建
Document对象并加载文档。 - 以
FileFormat.Xml保存为ProductSpec.xml。 - 从 VFS 读出文件并触发浏览器下载。
将 Word 导出为 XML 的代码如下:
function App() {
const wordToXml = async () => {
// 获取 Spire.Doc 的 WASM 模块
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// 载入中文字体与源文档
await window.spire.FetchFileToVFS('msyh.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
await window.spire.FetchFileToVFS('msyhbd.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
await window.spire.FetchFileToVFS('ProductSpec.docx', '', `${process.env.PUBLIC_URL}/data/`);
// 加载文档
const doc = new docModule.Document();
doc.LoadFromFile('ProductSpec.docx');
// 以 Spire.Doc 自有 XML 格式保存
const outputFileName = 'ProductSpec.xml';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Xml });
// 从 VFS 读取生成的文件,触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([fileArray], { type: 'application/xml' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
doc.Dispose();
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>Word 转 XML</h1>
<button onClick={wordToXml}>生成</button>
</div>
);
}
export default App;
用于转换的产品规格说明书共两页,含一份信息表、一张尺寸图和三个数据表:

导出为 Word 2003 或 2007 XML 格式
如果 XML 要交给 Word 或其他系统打开,把枚举值换掉即可,其余代码不变:
// Word 2003 XML,Word 2003 及以上可直接打开
doc.SaveToFile({ fileName: 'ProductSpec-2003.xml', fileFormat: docModule.FileFormat.WordML });
// Word 2007 起的扁平 OPC,Word 2007 及以上可直接打开
doc.SaveToFile({ fileName: 'ProductSpec-2007.xml', fileFormat: docModule.FileFormat.WordXml });
这两种格式用 Word 打开后就是正常的排版页面,页数、表格与图片都与原稿一致。代价是它们只承载 Word 自己的标记体系,Spire.Doc 解析时能读到的属性不如 FileFormat.Xml 完整。
导出的 XML 里有什么
FileFormat.Xml 的输出是一份结构直白的文本,样式集中放在 <styles>,正文按 <sections> → <body> → <paragraphs> 逐层展开,每个段落、每个文本片段各占一个 <item>。下面是节选(省略了大部分属性):
<OML>
<styles>
<style id="0" Name="Normal" StyleId="0" type="ParagraphStyle">
<character-format>...</character-format>
<paragraph-format>...</paragraph-format>
</style>
</styles>
<sections>
<section BreakCode="NewPage">
<body>
<paragraphs>
<item type="Paragraph">
<items>
<item>
<character-format FontSize="10.5" TextColor="#FF1F242E">...</character-format>
<text>云雀 X7 是面向门店与仓储场景的</text>
</item>
</items>
<style ref="0" />
</item>
<item type="Picture" width="..." height="...">
<image>iVBORw0KGgoAAAANSUhEUg...</image>
</item>
</paragraphs>
</body>
</section>
</sections>
</OML>
文件是 UTF-16 编码、不带 XML 声明,用文本编辑器打开时如果显示为乱码,需要手动切换编码。图片不是文件引用,而是完整的 Base64 数据,所以整份文档只有一个文件。
XML 体积为什么明显增大
docx 内部是一组压缩后的 XML 分片,而导出的 XML 把每段文字、每个格式属性都按纯文本逐条写出,不再压缩;图片还要经过 Base64 编码,体积约为原图的 4/3。一份 58 KB 的 docx 导出后接近 400 KB,属于正常范围。若下游只需要文字,改用 FileFormat.Txt 或先把图片删除,可以显著减小体积。
将 HTML 转换为 XML
网页抓取、在线帮助与富文本编辑器保存下来的内容都是 HTML。直接解析 HTML 要面对标签不规范、属性写法各异的问题;先转换成统一的 XML,再按节点遍历或套用 XSLT,处理起来稳定得多。
Spire.Doc 加载 HTML 时先解析为文档模型,保存时再按 Word XML 写出。因此输出的是 Word 的元素组织方式,而不是原页面的 div、span 层级。
具体操作步骤如下:
- 获取 Spire.Doc 的 WASM 模块,确认已就绪。
- 把中文字体与
Article.html载入 VFS。 - 按 HTML 格式加载,并把校验级别设为宽松模式。
- 以
FileFormat.Xml保存为Article.xml。 - 从 VFS 读出文件并触发浏览器下载。
将 HTML 转换为 XML 的代码如下:
// 按 HTML 格式加载,validationType 决定标签校验的严格程度
const doc = new docModule.Document();
doc.LoadFromFile({
fileName: 'Article.html',
fileFormat: docModule.FileFormat.Html,
validationType: docModule.XHTMLValidationType.None,
});
// 页面内若有相对路径的资源,用它指定基准路径
doc.HtmlBaseUrl = '/';
const outputFileName = 'Article.xml';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Xml });
示例页面中的拓扑图用 CSS 背景绘制,因此上面的代码可以直接运行。HTML 中的图片(<img> 或 CSS 背景图)都不会写入 FileFormat.Xml;如果页面通过 <img> 引入图片,当前版本在 LoadFromFile 之后直接保存还会抛出 Arg_NullReferenceException,保存前先调用一次 doc.GetText() 即可规避。
用于转换的帮助中心页面同样由标题、步骤列表、参数表和示意图组成:

校验级别如何选择
XHTMLValidationType 提供三档:Strict 要求标签闭合、属性带引号;Transitional 允许旧式写法;None 基本不做校验。抓取来的页面常常带有未闭合标签,用 None 可以避免解析中断,代价是畸形结构会被静默修正,出错时不容易发现。对自己可控的页面,用 Transitional 更容易暴露问题。
HTML 的样式能保留多少
HTML 先解析成文档模型,再写出 XML,靠 CSS 排出来的效果只有一部分能进入模型。标题、段落、有序列表与表格结构会保留;表格边框、单元格背景、标题文字颜色这类装饰性样式,以及页面级布局,通常不会被完整保留,无序列表的项目符号也可能丢失。图片同样不会进入 FileFormat.Xml 的输出:Word 文档转 XML 时图片会以 Base64 内嵌,HTML 转 XML 时则不会保留。需要带图片的文档时,可先把 HTML 保存为 docx(FileFormat.Docx2013),图片会随文件一起写入;需要严格还原网页外观时,应改用浏览器打印或 HTML 转 PDF。
将 XML 转换回 Word
把 XML 转换回 Word,多用于两种情况:归档件需要重新编辑,或者把外部系统生成的内容渲染成可打印文档。前提是这份 XML 本身就是 Spire.Doc 能识别的格式——上一节导出的 ProductSpec.xml 可以直接读回。
具体操作步骤如下:
- 获取 Spire.Doc 的 WASM 模块,确认已就绪。
- 把中文字体与
ProductSpec.xml载入 VFS。 - 按
FileFormat.Xml加载 XML。 - 以
FileFormat.Docx2013保存为 docx。 - 从 VFS 读出文件并触发浏览器下载。
将 XML 转换回 Word 的代码如下:
const doc = new docModule.Document();
doc.LoadFromFile({ fileName: 'ProductSpec.xml', fileFormat: docModule.FileFormat.Xml });
const outputFileName = 'ProductSpecRestored.docx';
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
读回的文档与原稿基本一致:正文段落、三个数据表、页眉页脚都保留了下来。

加载失败时先确认来源
LoadFromFile 指定 FileFormat.Xml 时,期望的是 Spire.Doc 导出的那份 XML。普通的配置、报文或 RSS 文件缺少对应的结构,实测会直接抛出异常(提示类似 Arg_NullReferenceException),而不是给出可读的错误说明。处理这类文件,应先用脚本转换成 HTML 再加载,或者在代码中逐段构建文档,不要指望它能被当作 Word XML 解析。
往返转换后哪些地方会变
Word → XML → Word 的往返对文字内容是可靠的:示例文档读回后,43 个段落、3 张表格与页眉页脚逐项比对完全一致。但版式层面有几处会变化,值得在上线前检查:
- 图片尺寸:读回时按原始像素尺寸插入,不再沿用导出前设置的显示宽度。600 像素宽的图片会按 96 dpi 展开成约 15.9 cm,可能顶到页边距。若对版式敏感,应在制作源文档时就把图片像素尺寸调到与目标宽度匹配。
- 图片写法:内联图片会从 DrawingML 改写为 VML,Word 显示正常,但只按
w:drawing读取图片的下游工具可能读不到。 - 表格列宽:单元格宽度会按内容重新计算,信息表这类列宽不均的表格,读回后比例可能与原稿略有出入。
因此对需要长期反复编辑的文档,仍应以 docx 为准,把 XML 当作单向导出的交换格式。
三个方向的调用对照
| 方向 | 加载 | 保存 |
|---|---|---|
| Word → XML | LoadFromFile('a.docx') |
SaveToFile({ fileName, fileFormat: FileFormat.Xml }) |
| HTML → XML | LoadFromFile({ fileName, fileFormat: FileFormat.Html, validationType }) |
SaveToFile({ fileName, fileFormat: FileFormat.Xml }) |
| XML → Word | LoadFromFile({ fileName, fileFormat: FileFormat.Xml }) |
SaveToFile({ fileName, fileFormat: FileFormat.Docx2013 }) |
三个方向的结构一致:加载、保存、读出、下载,最后释放实例。批量处理时,建议每个文件单独创建 Document,处理完立即调用 Dispose(),避免多个实例同时占用 WASM 内存。
常见问题
导出的 XML 能直接用 Word 打开编辑吗
取决于用哪个枚举值导出。FileFormat.Xml 输出的是 Spire.Doc 自有的 XML,Word 打开时会把它当作通用 XML 显示标签文本(实测一份两页文档会展开成上百页标记),看不到排版;FileFormat.WordML 与 FileFormat.WordXml 才是 Word 能按文档打开的格式。
为什么导出的 XML 比原 docx 大好几倍
XML 用文本描述每一个元素,样式定义与段落属性都逐条写出且不压缩,图片还要转成 Base64,体积约为原图的 4/3。一份 58 KB 的 docx 导出后接近 400 KB,属于正常现象。只需要文字时,可以考虑改为导出纯文本。
加载自己系统的 XML 为什么会报错
LoadFromFile 指定 FileFormat.Xml 时,期望的是带 Spire.Doc 结构的 XML。普通的配置或报文类 XML 缺少对应节点,实测会抛出类似 Arg_NullReferenceException 的异常。遇到这种情况,先把内容转成 HTML 再加载,或在代码中逐段构建文档,通常比强行解析更省事。
转成 XML 再转回 Word,图片为什么变大了
图片在 XML 中以 Base64 保存,读回 docx 时按原始像素尺寸插入,导出前设置的显示宽度不再生效。96 dpi 下 1 厘米约合 38 像素,600 像素宽的图片会展开到 15.9 cm 左右。制作源文档时按目标宽度预留像素尺寸,读回后就不必再调整。
HTML 转成的 XML 和网页样式对不上
HTML 转换走的是文档模型:先把页面解析成标题、段落、列表与表格,再按 Word 的规则写出。表格边框、背景色、页面布局这些靠 CSS 呈现的效果,不会完整进入模型;标题层级、段落顺序与表格数据则会保留。图片也不会写入 XML 输出,包括 <img> 与 CSS 背景图。需要像素级还原网页时,应改用 HTML 转 PDF 或浏览器打印。
HTML 里有 <img>,保存 XML 为什么会报错
当前版本中,HTML 通过 <img> 引入图片时,LoadFromFile 完成后直接调用 SaveToFile({ fileName, fileFormat: FileFormat.Xml }) 会抛出 Arg_NullReferenceException。保存前先调用一次 doc.GetText(),让图片等对象完成解析,即可正常输出:
doc.LoadFromFile({
fileName: 'Article.html',
fileFormat: docModule.FileFormat.Html,
validationType: docModule.XHTMLValidationType.None,
});
doc.HtmlBaseUrl = '/';
doc.GetText(); // 触发图片解析,避免保存 XML 时抛异常
doc.SaveToFile({ fileName: 'Article.xml', fileFormat: docModule.FileFormat.Xml });
需要注意,即使保存成功,HTML 中的图片也不会出现在 XML 里。需要保留图片时,先把 HTML 保存为 docx,再用 docx 转 XML。
获取免费许可证
如果您希望删除结果文档中的评估消息,或者摆脱功能限制,请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。







