由报表系统导出的 Excel 文件往往只带一个系统名作为作者，标题、主题、关键词等摘要条目一律留空；企业内部又常需要往工作簿里附加导出批次、责任人、审批状态等字段，供归档与检索使用。这些信息都不占用任何单元格，全部保存在工作簿的文档属性中，用 Excel 打开时可在「文件 > 信息 > 属性」里查看。Spire.XLS for JavaScript 基于 WebAssembly 在浏览器端写入这些属性，通过虚拟文件系统（VFS）管理输入输出文件，无需后端服务支持。
本文介绍三个核心功能点：
有关安装和项目配置，请参考 React 项目中集成 Spire.XLS for JavaScript。以下示例默认已安装 Spire.XLS 并完成 WebAssembly 模块初始化。
设置工作簿的摘要属性
摘要属性是 Excel 文件在资源管理器和「文件 > 信息」中展示的一层描述，也是归档检索时最先被看到的信息。报表由程序生成时通常只有系统名作为作者，其余条目留空，补全这些条目可以让文件在流转过程中具备可读的上下文。文本条目直接赋值即可，时间条目则要传入日期对象。具体操作步骤如下：
- 加载工作簿，通过
workbook.DocumentProperties取得摘要属性集合。 - 对
Title、Subject、Author、Keywords、Comments、Category等文本条目直接赋值。 - 对
Company、Manager这类由 Excel 扩展属性承载的条目同样直接赋值。 - 将
CreatedTime与LastSaveTime设为Date对象。 - 保存工作簿。
下面是一个完整的代码示例，展示了在 React 中设置工作簿摘要属性：
function App() {
const setSummaryProperties = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将中文字体载入 VFS
await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
// 将 Excel 文件载入 VFS
const inputFileName = 'WorkbookProperties.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);
// 加载工作簿
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile(inputFileName);
// 设置摘要属性中的文本条目
const summary = workbook.DocumentProperties;
summary.Title = '2026 年第三季度销售报表';
summary.Subject = '各销售部季度业绩汇总';
summary.Author = 'E-iceblue';
summary.Keywords = '销售, 报表, Excel';
summary.Comments = '由报表系统导出后补充的摘要信息';
summary.Category = '销售报表';
// 设置由扩展属性承载的条目
summary.Company = 'E-iceblue';
summary.Manager = 'Sales Manager';
// 设置文档时间，此处必须传入 Date 对象
summary.CreatedTime = new Date(2026, 8, 1);
summary.LastSaveTime = new Date(2026, 8, 20);
// 保存工作簿
const outputFileName = 'SetSummaryProperties.xlsx';
workbook.SaveToFile(outputFileName);
// 释放资源
workbook.Dispose();
// 从 VFS 读取结果文件，触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([fileArray], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
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>设置工作簿摘要属性</h1>
<button onClick={setSummaryProperties}>Start</button>
</div>
);
}
export default App;
运行后，设置工作簿摘要属性的效果：
添加自定义属性
自定义属性用于承载摘要属性容纳不下的业务字段，例如导出批次、责任人电话、版本号或审批日期。与摘要属性不同，自定义属性没有固定条目，名称与类型都由调用方决定，Excel 支持文本、整数、小数、布尔和日期时间五种取值。具体操作步骤如下：
- 加载工作簿，通过
workbook.CustomDocumentProperties取得自定义属性集合。 - 调用
Add添加属性，名称与值可以写成{ strName, boolValue }这样的具名对象，也可以直接传入名称与值两个参数。 - 按值的类型选择对应的成员：整数用
intValue，小数用dblValue。 - 日期时间值用
dtValue传入Date对象。 - 保存工作簿。
下面是一个完整的代码示例，展示了在 React 中为工作簿添加自定义属性：
function App() {
const addCustomProperties = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将中文字体载入 VFS
await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
// 将 Excel 文件载入 VFS
const inputFileName = 'WorkbookProperties.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);
// 加载工作簿
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile(inputFileName);
// 添加布尔值属性，_MarkAsFinal 表示文档已定稿
workbook.CustomDocumentProperties.Add({ strName: '_MarkAsFinal', boolValue: true });
// 添加文本属性，也可直接传入名称与值两个参数
workbook.CustomDocumentProperties.Add('The Editor', 'E-iceblue');
// 添加整数属性
workbook.CustomDocumentProperties.Add({ strName: 'Phone number', intValue: 81705109 });
// 添加小数属性
workbook.CustomDocumentProperties.Add({ strName: 'Revision number', dblValue: 7.12 });
// 添加日期时间属性
workbook.CustomDocumentProperties.Add({ strName: 'Revision date', dtValue: new Date(2026, 8, 1) });
// 保存工作簿
const outputFileName = 'AddCustomProperties.xlsx';
workbook.SaveToFile(outputFileName);
// 释放资源
workbook.Dispose();
// 从 VFS 读取结果文件，触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([fileArray], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
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>添加自定义属性</h1>
<button onClick={addCustomProperties}>Start</button>
</div>
);
}
export default App;
运行后，添加自定义属性的效果：
修改自定义属性的值
业务字段的值会随统计口径变化，例如导出记录数在补充数据后需要按新的口径重写。自定义属性没有提供直接改值的入口，但 Add 以名称为键，对同名属性再次调用时并不会新增重复条目，而是把原有条目的值替换掉。具体操作步骤如下：
- 加载工作簿，通过
workbook.CustomDocumentProperties取得自定义属性集合。 - 再次调用
Add，传入与已有条目相同的名称和新的值。 - 保存工作簿。
下面是一个完整的代码示例，展示了在 React 中修改工作簿的自定义属性：
function App() {
const updateCustomProperties = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将中文字体载入 VFS
await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
// 将 Excel 文件载入 VFS
const inputFileName = 'WorkbookProperties.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);
// 加载工作簿
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile(inputFileName);
// 按新的统计口径重写导出记录数，同名属性会被覆盖而不会重复添加
workbook.CustomDocumentProperties.Add({ strName: 'ExportedRecords', intValue: 256 });
// 保存工作簿
const outputFileName = 'UpdateCustomProperties.xlsx';
workbook.SaveToFile(outputFileName);
// 释放资源
workbook.Dispose();
// 从 VFS 读取结果文件，触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([fileArray], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
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>修改自定义属性的值</h1>
<button onClick={updateCustomProperties}>Start</button>
</div>
);
}
export default App;
运行后，修改自定义属性的效果：
常见问题
为什么给 CreatedTime 赋值会报 Assert failed: Value is not a Date
原因：CreatedTime 与 LastSaveTime 只接受 JavaScript 的 Date 对象。写成日期字符串（如 '2026-09-01'）、时间戳数字，或者自己拼一个只带 toISOString() 方法的普通对象，都会在这一步被类型校验挡下来，抛出 Assert failed: Value is not a Date。
解决：先用 new Date(...) 构造出 Date 对象，再赋值给它：
// 2026 年 9 月 1 日；月份从 0 开始计数，8 表示 9 月
workbook.DocumentProperties.CreatedTime = new Date(2026, 8, 1);
为什么给自定义属性的 Value 赋值会报 ArgumentNull_Generic
原因：Value 属性只提供读取，直接赋值会抛出 ArgumentNull_Generic Arg_ParamName_Name, value，原值不会改变。要更新一条已有属性，需要走 Add。
解决：用同名 Add 覆盖原值：
workbook.CustomDocumentProperties.Add({ strName: 'ExportedRecords', intValue: 256 });
获取免费许可证
如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。
