在报表系统与数据展示场景中,Excel 和 HTML 各有适用边界。Excel 适合结构化数据存储与二次编辑,HTML 则便于直接嵌入网页、邮件或工单系统进行查看。手工另存为网页格式效率有限,也难以在批量流程中串联。借助 WebAssembly 技术,这一转换过程可以在浏览器端完成,无需依赖后端服务或本地 Office 环境。本文以 React 为框架,介绍如何将 Excel 工作表导出为 HTML 文件,以及将 HTML 文件加载并保存为 Excel 工作簿,并对代码中的关键环节与常见问题加以说明。
环境准备与模块加载
示例所用的表格处理库以 WebAssembly 形式运行,通过 npm 安装:
npm i spire.office
安装完成后,需要将运行时所需的文件复制到 React 项目的 public 目录下,包括 spire.xls.js、Spire.Xls.Wasm.zip、spire.common.js、Spire.Common.Wasm.zip 以及 _framework 文件夹。字体文件放置在 public/font 路径下,待转换的源文件放置在 public/static/data 路径下。
在 React 组件中,通过 useEffect 异步加载模块并挂载到 window.wasmModule,同时用状态变量控制按钮可用性:
useEffect(() => {
(async () => {
try {
const publicUrl = process.env.PUBLIC_URL || '';
const spireModule = await import(/* webpackIgnore: true */ `${publicUrl}/spire.xls.js`);
const rawModule = spireModule.default || spireModule;
window.wasmModule = typeof rawModule === 'function'
? await rawModule({ locateFile: p => p.endsWith('.wasm') ? `${publicUrl}/${p}` : p })
: rawModule;
setWasmModule(window.wasmModule);
} catch (error) {
console.error('Failed to load WASM module:', error);
}
})();
}, []);
加载成功后,Excel 处理 API 通过 window.wasmModule.spirexls 访问,虚拟文件系统接口通过 window.spire 与 window.dotnetRuntime.Module.FS 访问。需要留意的是,部分较新版本的包可能将 API 直接暴露在 window.spirexls 上,而非嵌套在 wasmModule 中,实际使用时可根据控制台输出确认可用的全局对象。
Excel 工作表导出为 HTML
将工作表保存为 HTML 的核心方法是 Worksheet.SaveToHtml()。整体流程分为:加载字体与源文件到虚拟文件系统、创建工作簿并载入 Excel、获取目标工作表、配置 HTML 选项、保存并触发下载。
首先通过 FetchFileToVFS 将字体与 Excel 文件写入虚拟文件系统。代码中使用的是 simsun.ttc(宋体),适合包含中文内容的 Excel 文件:
await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
const inputFileName = 'sample.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);
随后创建工作簿、加载文件并取得第一个工作表:
const workbook = new wasmModule.Workbook();
workbook.LoadFromFile({ fileName: inputFileName });
let sheet = workbook.Worksheets.get(0);
创建 HTMLOptions 对象并设置 ImageEmbedded 为 true,可将工作表中的图片以 Base64 数据 URI 形式内嵌到 HTML 中,生成自包含的单文件。该属性的默认值为 false,此时图片会输出到同名的 _files 文件夹并以相对路径引用,分发时需要与文件夹一并保留。
let options = new wasmModule.HTMLOptions();
options.ImageEmbedded = true;
const outputFileName = 'ToHtml.html';
sheet.SaveToHtml({ fileName: outputFileName, saveOption: options });
保存后的文件位于虚拟文件系统中,通过 FS.readFile 读出字节数组,构造 Blob 对象并触发下载:
const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([modifiedFileArray], { type: 'text/html' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
URL.revokeObjectURL(url);
workbook.Dispose();
HTML 文件加载并保存为 Excel
反向转换使用 Workbook.LoadFromHtml() 方法。HTML 文件没有工作表概念,库在加载时会将其内容解析并映射到工作簿的默认工作表中,随后通过 SaveToFile 保存为 Excel 格式。
const inputFileName = 'in.html';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);
const workbook = new wasmModule.Workbook();
workbook.LoadFromHtml({ fileName: inputFileName });
const outputFileName = 'ToExcel.xlsx';
workbook.SaveToFile({ fileName: outputFileName, version: wasmModule.ExcelVersion.Version2013 });
保存时通过 version 参数指定 Excel 版本,Version2013 对应 .xlsx 格式。生成的 Blob 类型需设置为 Excel 对应的 MIME 类型,以确保浏览器正确识别:
const modifiedFile = new Blob([modifiedFileArray], { type:'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
下载逻辑与前一节相同,操作结束后同样调用 workbook.Dispose() 释放资源。
实践中的注意事项
字体路径的一致性:两份代码中字体加载路径均为 ${process.env.PUBLIC_URL}/font/,因此字体文件应放置在 public/font/ 目录下,而非 public/static/font/。若放置位置不匹配,FetchFileToVFS 将无法找到字体文件,可能导致文本渲染异常或转换失败。示例使用 simsun.ttc 是为了覆盖中文内容,若文档仅含拉丁字符,可替换为体积更小的字体。
图片输出模式的选择:ImageEmbedded 设为 true 时生成单文件,便于分发,但文件体积会随图片增大;设为 false 时 HTML 与 _files 文件夹需一并保留,适用于对文件体积敏感或需要独立管理图片资源的场景。两种模式各有取舍,需根据实际分发方式选择。
HTML 转 Excel 的样式保留程度:LoadFromHtml 能够解析 HTML 表格结构,但并非所有 CSS 样式都能完整映射到 Excel 的格式模型中。复杂布局或非表格元素可能在转换后丢失。如果 HTML 来源是结构清晰的 <table> 元素,转换结果通常较为理想;如果是任意 HTML 页面,建议先验证输出效果。
资源释放:在 React 单页应用中,组件可能被多次挂载与卸载。每次转换完成后手动调用 workbook.Dispose() 是必要的,否则工作簿对象占用的内存不会自动回收。
虚拟文件系统路径:FetchFileToVFS 的第二个参数是虚拟文件系统中的目标目录,第三个参数是浏览器中的源路径,两者需要区分清楚。字体通常放入 /Library/Fonts/,业务文件可以放在根路径或自定义目录。
结语
本文梳理了在 React 应用中使用 WebAssembly 方案完成 Excel 与 HTML 双向转换的流程。Excel 转 HTML 借助 SaveToHtml 并配合 HTMLOptions 控制图片内嵌方式;HTML 转 Excel 通过 LoadFromHtml 解析后以指定版本保存。该方案的特点在于转换逻辑运行在浏览器端,不依赖后端服务或本地 Office 环境。代价是需额外处理 WASM 文件部署与字体资源加载,且 HTML 到 Excel 的样式映射存在固有局限,复杂页面结构未必能完整还原。对于已有 React 技术栈且需要在客户端完成格式转换的项目,这一方案具备参考价值。