Excel 批注通常只承载一段文字，用于解释某个数字或补充一句说明。当说明的对象本身即为图片——供应商标识、产品外观、零件示意——纯文字难以胜任。Spire.XLS for JavaScript 支持以图片填充批注背景，单元格旁即可显示图片，无需另行插入浮动图片对象。批注背景由填充对象控制，改用纯色时同样只需修改这一个对象。Spire.XLS for JavaScript 基于 WebAssembly 在浏览器端完成上述操作，输入输出文件通过虚拟文件系统（VFS）管理，无需后端服务。
本文介绍两个核心功能点：
有关安装和项目配置，请参考 React 项目中集成 Spire.XLS for JavaScript。以下示例默认已安装 Spire.XLS 并完成 WebAssembly 模块初始化。
为单元格插入图片批注
批注依附于单元格，为其配置图片需先在目标单元格上取得批注对象，再填入图片。填入的图片将作为批注框的底色，取代默认的淡黄色底纹，鼠标移至单元格或打开文件时即显示该图。图片按批注框的尺寸缩放，而批注框默认为扁平的矩形，方形图片会被拉伸变形，因此在填充之后还需指定批注框的宽度与高度，使其比例与图片一致；批注框在工作表上的位置则由另一组位置属性决定，无需依附于单元格边框。具体操作步骤如下：
- 将字体、图片与测试数据文件载入 VFS。
- 用
workbook.LoadFromFile加载工作簿。 - 用
sheet.Range.get('A4')取得要附上批注的单元格。 - 用
range.AddComment()在单元格上新建批注对象。 - 用
comment.Fill.CustomPicture将图片填充为批注背景，图片以new xlsModule.Stream('logo.png')构造的流传入，name参数填'None'。 - 用
comment.Width与comment.Height将批注框设为正方形，与方形图片的比例一致，图片不会被拉伸。 - 用
comment.Top与comment.Left设定批注框相对工作表左上角的位置，使其覆盖下方内容而不遮挡当前行。 - 用
comment.Visible属性将批注设为常显状态，使其在文件打开时一并显示。 - 用
workbook.SaveToFile保存工作簿。 - 用
workbook.Dispose释放 workbook 对象以释放资源。
以下为完整的代码示例，演示如何在 React 中为 Excel 单元格插入图片批注：
function App() {
const addPictureComment = 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/`);
await window.spire.FetchFileToVFS('logo.png', '', `${process.env.PUBLIC_URL}data/`);
const inputFileName = 'ProductList.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);
// 加载工作簿
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile({ fileName: inputFileName });
// 取第一个工作表，在 A4 单元格上新建批注并填充图片
const sheet = workbook.Worksheets.get(0);
const range = sheet.Range.get('A4');
const comment = range.AddComment();
comment.Fill.CustomPicture({ im: new xlsModule.Stream('logo.png'), name: 'None' });
// 设置批注框的长和宽
comment.Width = 150;
comment.Height = 150;
// 设定批注框相对工作表左上角的位置
comment.Top = 100;
comment.Left = 400;
// 让批注随文件打开一并显示
comment.Visible = true;
// 保存工作簿
const outputFileName = 'PictureComment.xlsx';
workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });
// 释放 workbook 对象以释放资源
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 id="picture-comment" onClick={addPictureComment}>为单元格插入图片批注</button>
</div>
);
}
export default App;
运行后，为单元格插入图片批注的效果：
为批注设置纯色填充
批注的底色并非只能是图片。当只需将某条批注在视觉上与周围的淡黄底纹区分开时，指定纯色比准备图片更为简便。填充图片与填充纯色使用同一个 comment.Fill 对象，只需将填充类型由图片改为纯色。具体操作步骤如下：
- 将字体与测试数据文件载入 VFS。
- 用
workbook.LoadFromFile加载工作簿。 - 用
sheet.Range.get('A4')取得要附上批注的单元格，并用range.AddComment()新建批注对象。 - 用
comment.Text写入批注文字。 - 用
workbook.CreateFont()创建字体，并用comment.RichText.SetFont将整段文字设为该字体。 - 用
comment.Fill.FillType将填充类型设为纯色，取值为xlsModule.ShapeFillType.SolidColor。 - 用
comment.Fill.ForeColor设定填充颜色。 - 用
comment.Visible属性将批注设为常显状态。 - 用
workbook.SaveToFile保存工作簿。 - 用
workbook.Dispose释放 workbook 对象以释放资源。
以下为完整的代码示例，演示如何在 React 中为 Excel 批注设置纯色填充：
function App() {
const fillCommentColor = 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/`);
const inputFileName = 'ProductList.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);
// 加载工作簿
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile({ fileName: inputFileName });
// 取第一个工作表，在 A4 单元格上新建批注
const sheet = workbook.Worksheets.get(0);
const range = sheet.Range.get('A4');
// 创建字体，供批注文字使用
const font = workbook.CreateFont();
font.FontName = 'Arial';
font.Size = 11;
font.KnownColor = xlsModule.ExcelColors.Orange;
// 写入批注文字并把整段文字设成该字体
const commentText = '本行产品为当季主推';
range.Comment.Text = commentText;
range.Comment.RichText.SetFont(0, commentText.length - 1, font);
// 把批注的填充类型设为纯色，并指定颜色
range.Comment.Fill.FillType = xlsModule.ShapeFillType.SolidColor;
range.Comment.Fill.ForeColor = xlsModule.Color.get_SkyBlue();
range.Comment.Visible = true;
// 保存工作簿
const outputFileName = 'CommentFillColor.xlsx';
workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });
// 释放 workbook 对象以释放资源
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 id="comment-fill-color" onClick={fillCommentColor}>为批注设置纯色填充</button>
</div>
);
}
export default App;
运行后，为批注设置纯色填充的效果：
常见问题
打开结果文件时图片批注为何未显示
原因：批注默认处于隐藏状态，仅在鼠标移至单元格时显示。若保存前未将其设为显示，重新打开文件时只会看到一张普通的工作表，图片批注不会主动显示。
解决：将 comment.Visible 设为 true，批注会随文件打开一并显示：
comment.Visible = true;
获取免费许可证
如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。
