形状是 Excel 中用来增强工作表视觉效果、直观传达信息的图形元素，例如箭头、矩形、椭圆、星形等。借助形状，您可以在数据旁添加标注、流程示意或装饰元素，让报表更加生动易读。Spire.XLS for JavaScript 基于 WebAssembly 在浏览器端直接完成对 Excel 形状的添加、读取与删除操作，通过虚拟文件系统（VFS）管理输入输出文件，无需后端服务支持。它提供了完整的 API 用于添加形状并自定义其外观（如填充、旋转角度、文本与阴影）、读取形状中的文本和图片，以及删除指定或全部形状。
本文介绍三个核心功能点：
有关安装和项目配置，请参考 React 项目中集成 Spire.XLS for JavaScript。以下示例默认已安装 Spire.XLS 并完成 WebAssembly 模块初始化。
在 Excel 中添加形状
在 Excel 中添加形状可以突出重点数据、美化工作表布局。Spire.XLS for JavaScript 支持通过 sheet.PrstGeomShapes.AddPrstGeomShape() 方法添加形状并同时设置其位置（行、列）与大小（宽度、高度），并通过形状的 Fill 属性设置单色、渐变、纹理或图片填充，通过 Text 属性向形状添加文本，通过 Rotation 属性设置形状的倾斜角度，通过 Shadow 属性设置阴影效果，通过 Visible 属性控制形状的显示与隐藏。具体操作步骤如下：
- 创建
Workbook对象并获取默认工作表。 - 使用
PrstGeomShapes.AddPrstGeomShape()方法添加形状，并通过参数设置形状类型、位置和大小。 - 通过
Fill属性为形状设置单色、渐变、纹理或图片填充。 - 通过
Text属性向形状添加文本，通过Rotation属性设置形状的倾斜角度。 - 通过
Shadow属性为形状设置阴影效果。 - 使用
SaveToFile()保存工作簿为 Excel 文件。
下面是一个完整的代码示例，展示了在 React 中添加并自定义各种形状：
function App() {
const addShapes = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将图片加载到虚拟文件系统（VFS）
await window.spire.FetchFileToVFS('SpireXls.png', '', `${process.env.PUBLIC_URL}/image/`);
// 创建新工作簿并获取默认工作表
const workbook = new xlsModule.Workbook();
let sheet = workbook.Worksheets.get(0);
// 添加三角形形状并填充纯色
let triangle = sheet.PrstGeomShapes.AddPrstGeomShape(2, 2, 100, 100, xlsModule.PrstGeomShapeType.Triangle);
triangle.Fill.ForeColor = xlsModule.Color.get_Yellow();
triangle.Fill.FillType = xlsModule.ShapeFillType.SolidColor;
// 向三角形添加文本并设置倾斜角度
triangle.Text = 'Triangle';
triangle.Rotation = 45;
// 添加心形形状并填充渐变色
let heart = sheet.PrstGeomShapes.AddPrstGeomShape(2, 5, 100, 100, xlsModule.PrstGeomShapeType.Heart);
heart.Fill.ForeColor = xlsModule.Color.get_Red();
heart.Fill.FillType = xlsModule.ShapeFillType.Gradient;
// 为心形设置阴影效果
heart.Shadow.Angle = 90;
heart.Shadow.Distance = 10;
heart.Shadow.Size = 150;
heart.Shadow.Color = xlsModule.Color.get_Gray();
heart.Shadow.Blur = 30;
heart.Shadow.Transparency = 1;
heart.Shadow.HasCustomStyle = true;
// 添加箭头形状
let arrow = sheet.PrstGeomShapes.AddPrstGeomShape(10, 2, 100, 100, xlsModule.PrstGeomShapeType.CurvedRightArrow);
// 添加云朵形状并填充图片
let cloud = sheet.PrstGeomShapes.AddPrstGeomShape(10, 5, 100, 100, xlsModule.PrstGeomShapeType.Cloud);
cloud.Fill.CustomPicture({ im: new xlsModule.Stream('SpireXls.png'), name: 'SpireXls.png' });
// 保存工作簿
const outputFileName = 'AddShapes.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>Add Shapes</h1>
<button onClick={addShapes}>
Generate
</button>
</div>
);
}
export default App;
使用 Spire.XLS for JavaScript 在 Excel 中添加形状后的效果
读取 Excel 形状中的文本和图片
读取形状中的文本和图片，可以帮助您批量提取形状中的数据，或对形状资源进行复用与归档。Spire.XLS for JavaScript 支持加载包含形状的 Excel 文件，通过 PrstGeomShapes.get() 方法按索引获取指定形状，再通过形状的 Text 属性读取其文本内容，通过 Fill.Picture 属性获取其填充图片。具体操作步骤如下：
- 创建
Workbook对象并加载包含形状的已有 Excel 文件。 - 通过
workbook.Worksheets.get()获取工作表。 - 使用
sheet.PrstGeomShapes.get()按索引获取指定形状。 - 通过形状的
Text属性读取形状中的文本。 - 通过
Fill.Picture属性读取形状中的填充图片。 - 将读取的文本和图片保存为 txt 和 png 文件。
下面是一个完整的代码示例，展示了在 React 中读取形状中的文本和图片（示例加载上一节生成的 AddShapes.xlsx 文件）：
function App() {
const readShapes = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将包含形状的示例文件加载到虚拟文件系统（VFS）
let excelFileName = 'AddShapes.xlsx';
await window.spire.FetchFileToVFS(excelFileName, '', `${process.env.PUBLIC_URL}data/`);
// 创建 Workbook 对象并加载已有文件
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile({ fileName: excelFileName });
// 获取第一个工作表
let sheet = workbook.Worksheets.get(0);
// 获取第一个形状（三角形）并读取其中的文本
let triangle = sheet.PrstGeomShapes.get(0);
let text = triangle.Text;
// 获取第四个形状（云朵）并读取其中的图片
let cloud = sheet.PrstGeomShapes.get(3);
let image = cloud.Fill.Picture;
const imageFileName = 'ExtractImageFromShape.png';
image.Save(imageFileName);
workbook.Dispose();
// 将读取的文本保存为 txt 文件并触发下载
const textFileName = 'ExtractTextFromShape.txt';
const textBlob = new Blob([`The text in the first shape is: ${text}`], { type: 'text/plain;charset=utf-8' });
const textUrl = URL.createObjectURL(textBlob);
const a1 = document.createElement('a');
a1.href = textUrl;
a1.download = textFileName;
a1.click();
URL.revokeObjectURL(textUrl);
// 从 VFS 读取图片文件，触发下载
const fileArray = window.dotnetRuntime.Module.FS.readFile(imageFileName);
const blob = new Blob([fileArray], { type: 'application/png' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = imageFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>Read Text and Image from Shapes</h1>
<button onClick={readShapes}>
Generate
</button>
</div>
);
}
export default App;
使用 Spire.XLS for JavaScript 读取形状中的文本和图片
删除 Excel 中的形状
当形状不再需要时，及时删除可以让工作表保持整洁、减小文件体积。Spire.XLS for JavaScript 支持通过 Remove() 方法删除指定形状，也支持遍历形状集合并逐个调用 Remove() 方法清除工作表中的全部形状。具体操作步骤如下：
- 创建
Workbook对象并加载包含形状的已有 Excel 文件。 - 通过
workbook.Worksheets.get()获取工作表。 - 使用
sheet.PrstGeomShapes.get()获取指定形状，并调用其Remove()方法删除该形状。 - 使用
SaveToFile()保存工作簿为 Excel 文件。
下面是一个完整的代码示例，展示了在 React 中删除形状（示例加载上一节生成的 AddShapes.xlsx 文件）：
function App() {
const deleteShapes = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将包含形状的示例文件加载到虚拟文件系统（VFS）
let excelFileName = 'AddShapes.xlsx';
await window.spire.FetchFileToVFS(excelFileName, '', `${process.env.PUBLIC_URL}data/`);
// 创建 Workbook 对象并加载已有文件
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile({ fileName: excelFileName });
// 获取第一个工作表
let sheet = workbook.Worksheets.get(0);
// 删除工作表中的第一个形状
sheet.PrstGeomShapes.get(0).Remove();
// 删除工作表中的全部形状
// for (let i = sheet.PrstGeomShapes.Count - 1; i >= 0; i--) {
// sheet.PrstGeomShapes.get(i).Remove();
// }
// 保存工作簿
const outputFileName = 'DeleteShapes.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>Delete Shapes</h1>
<button onClick={deleteShapes}>
Generate
</button>
</div>
);
}
export default App;
使用 Spire.XLS for JavaScript 删除指定形状后的效果
常见问题
如何获取形状的名称和类型？
原因：当工作表中形状较多时，您可能需要通过形状的名称或类型来识别和定位形状，而不是依赖索引。
解决：读取形状的 Name 和 PrstShapeType 属性即可获取形状的名称和类型：
// 获取工作表
let sheet = workbook.Worksheets.get(0);
// 获取第一个形状
let shape = sheet.PrstGeomShapes.get(0);
// 获取形状的名称
let shapeName = shape.Name;
// 获取形状的类型
let shapeType = shape.PrstShapeType;
如何判断形状当前是否可见？
原因：从文件中加载形状后，有时需要判断形状是否被隐藏，以便决定是否对其进行进一步处理。
解决：读取形状的 Visible 属性即可获知形状的可见状态：
// 获取工作表
let sheet = workbook.Worksheets.get(0);
// 获取第一个形状
let shape = sheet.PrstGeomShapes.get(0);
// 判断形状是否可见
let isVisible = shape.Visible;
获取免费许可证
如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。
