在日常 Excel 文档处理中，文本框常用于为数据添加说明性文字、标注或提示信息——无论是为报表添加注释，还是从既有文档中提取标注内容，都离不开文本框的增删改查操作。Spire.XLS for JavaScript 基于 WebAssembly 在浏览器端直接完成这些操作，通过虚拟文件系统（VFS）管理输入输出文件，无需后端服务支持。
本文介绍三个核心功能点：
有关安装和项目配置，请参考 React 项目中集成 Spire.XLS for JavaScript。以下示例默认已安装 Spire.XLS 并完成 WebAssembly 模块初始化。
添加文本框
在工作表中插入文本框可以为数据提供补充说明，例如添加操作指引或注意事项。Spire.XLS for JavaScript 通过 Worksheet.TextBoxes.AddTextBox() 方法在指定位置插入文本框，随后可设置文本框的文本、对齐方式、字体和背景色，也可以用图片填充文本框。具体操作步骤如下：
- 创建
Workbook对象，并使用LoadFromFile()方法加载 Excel 文档。 - 通过
Workbook.Worksheets.get()方法获取指定工作表。 - 使用
Worksheet.TextBoxes.AddTextBox()方法插入第一个文本框，并设置其文本、水平垂直居中对齐、字体和背景色。 - 使用
Worksheet.TextBoxes.AddTextBox()方法插入第二个文本框，并用图片填充。 - 通过
Workbook.SaveToFile()方法保存文档到指定路径。
下面是一个完整的代码示例，展示了在 React 中向工作表插入两个文本框——一个包含文字，一个填充图片：
function App() {
const addTextBox = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将字体、Excel 文件和图片载入 VFS
await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
const inputFileName = 'TextBox.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);
await window.spire.FetchFileToVFS('logo.png', '', `${process.env.PUBLIC_URL}data/`);
// 加载工作簿
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile({ fileName: inputFileName });
// 获取第一个工作表
const sheet = workbook.Worksheets.get(0);
// 插入第一个文本框并设置位置和大小
const textBox = sheet.TextBoxes.AddTextBox(3, 2, 50, 196);
// 设置文本框文本
textBox.Text = '插入Excel文本框';
// 设置文本水平、垂直居中
textBox.HAlignment = xlsModule.CommentHAlignType.Center;
textBox.VAlignment = xlsModule.CommentVAlignType.Center;
// 设置文本框字体（加粗、白色、12号）
const font = workbook.CreateFont();
font.FontName = 'SimSun';
font.Size = 12;
font.IsBold = true;
font.Color = xlsModule.Color.get_White();
const rt = xlsModule.RichTextShape.Convert(textBox.RichText);
rt.SetFont(0, textBox.Text.length - 1, font);
// 设置文本框背景色为蓝灰色
textBox.Fill.FillType = xlsModule.ShapeFillType.SolidColor;
textBox.Fill.ForeKnownColor = xlsModule.ExcelColors.BlueGray;
// 插入第二个文本框并设置位置和大小
const textBox2 = sheet.TextBoxes.AddTextBox(6, 5, 90, 90);
// 加载图片并用图片填充文本框
textBox2.Fill.CustomPicture('logo.png');
textBox2.Fill.FillType = xlsModule.ShapeFillType.Picture;
// 设置第二个文本框的边框为 0
textBox2.Line.Weight = 0;
// 保存文档
const outputFileName = 'AddTextBox_output.xlsx';
workbook.SaveToFile({ fileName: 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 TextBox</h1>
<button onClick={addTextBox}>
Start
</button>
</div>
);
}
export default App;
添加文本框的结果
提取文本框中的文本和图片
当需要汇总或复用既有文档中的标注信息时，可以通过遍历文本框并提取其中的文本内容和填充图片来实现。Spire.XLS for JavaScript 通过 Worksheet.TextBoxes.Count 获取文本框数量，配合 Worksheet.TextBoxes.get() 方法遍历每个文本框：读取其 Text 属性得到文本内容，通过 Fill.FillType 判断填充类型，并用 Fill.Picture 属性提取填充图片，最终将提取结果分别保存为 txt 文件和 png 图片文件。具体操作步骤如下：
- 创建
Workbook对象，并使用LoadFromFile()方法加载 Excel 文档。 - 通过
Workbook.Worksheets.get()方法获取指定工作表。 - 通过
Worksheet.TextBoxes.Count和Worksheet.TextBoxes.get()方法遍历TextBoxes集合中的每个文本框。 - 读取文本框的
Text属性，收集其中的文本内容。 - 对使用图片填充的文本框，通过其
Fill.Picture属性获取填充图片，并保存为 png 文件。 - 将收集的文本写入 txt 文件。
下面是一个完整的代码示例，展示了在 React 中提取文本框中的文本和图片：
function App() {
const extractTextAndImage = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将字体和 Excel 文件载入 VFS
await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
const inputFileName = 'TextBox.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);
// 加载工作簿
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile({ fileName: inputFileName });
// 获取第一个工作表
const sheet = workbook.Worksheets.get(0);
// 遍历工作表中的所有文本框，提取文本与图片
const textLines = [];
const pictureFiles = [];
for (let i = sheet.TextBoxes.Count - 1; i >= 0; i--) {
const shape = sheet.TextBoxes.get(i);
// 提取文本框中的文本
if (shape.Text) {
textLines.push(shape.Text);
}
// 提取文本框中的填充图片
if (shape.Fill.FillType === xlsModule.ShapeFillType.Picture) {
const picture = shape.Fill.Picture;
const imageFile = 'ExtractedImage' + i + '.png';
picture.Save(imageFile);
pictureFiles.push(imageFile);
}
}
// 将提取的文本保存为 txt 文件
const textFile = 'ExtractedText.txt';
window.dotnetRuntime.Module.FS.writeFile(textFile, textLines.join('\r\n'));
// 释放资源
workbook.Dispose();
// 下载提取的文本文件
const txtArray = window.dotnetRuntime.Module.FS.readFile(textFile);
const txtBlob = new Blob([txtArray], { type: 'text/plain' });
const txtUrl = URL.createObjectURL(txtBlob);
const txtAnchor = document.createElement('a');
txtAnchor.href = txtUrl;
txtAnchor.download = textFile;
txtAnchor.click();
URL.revokeObjectURL(txtUrl);
// 下载提取的图片文件
for (const imageFile of pictureFiles) {
const imageArray = window.dotnetRuntime.Module.FS.readFile(imageFile);
const imageBlob = new Blob([imageArray], { type: 'application/png' });
const imageUrl = URL.createObjectURL(imageBlob);
const imageAnchor = document.createElement('a');
imageAnchor.href = imageUrl;
imageAnchor.download = imageFile;
imageAnchor.click();
URL.revokeObjectURL(imageUrl);
}
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>Extract Text And Image From TextBox</h1>
<button onClick={extractTextAndImage}>
Start
</button>
</div>
);
}
export default App;
提取文本框中的文本和图片结果
删除文本框
当文档中的标注信息不再需要时，可以将其删除以保持工作表整洁。Spire.XLS for JavaScript 通过 Worksheet.TextBoxes.RemoveAt() 方法按索引删除指定的文本框。具体操作步骤如下：
- 创建
Workbook对象，并使用LoadFromFile()方法加载 Excel 文档。 - 通过
Workbook.Worksheets.get()方法获取指定工作表。 - 使用
Worksheet.TextBoxes.RemoveAt()方法删除指定索引的文本框。 - 通过
Workbook.SaveToFile()方法保存文档到指定路径。
下面是一个完整的代码示例，展示了在 React 中删除工作表内的文本框：
function App() {
const removeTextBox = async () => {
// 获取 Spire.XLS WASM 模块
const xlsModule = window.wasmModule?.spirexls;
// 检查模块是否就绪
if (!xlsModule) {
alert('Spire.Xls is not ready yet');
return;
}
// 将字体和 Excel 文件载入 VFS
await window.spire.FetchFileToVFS('simsun.ttc', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
const inputFileName = 'TextBox.xlsx';
await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);
// 加载工作簿
const workbook = new xlsModule.Workbook();
workbook.LoadFromFile({ fileName: inputFileName });
// 获取第一个工作表
const sheet = workbook.Worksheets.get(0);
// 删除第一个文本框
sheet.TextBoxes.RemoveAt(0);
// 保存文档
const outputFileName = 'RemoveTextBox_output.xlsx';
workbook.SaveToFile({ fileName: 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>Remove TextBox</h1>
<button onClick={removeTextBox}>
Start
</button>
</div>
);
}
export default App;
删除文本框的结果
常见问题
添加的文本框在结果文档中无法显示
原因：AddTextBox() 方法中指定的行、列坐标越界，或未将字体文件载入 VFS，导致文本框中的文字无法正常渲染。
解决：确认行、列坐标在工作表范围内，并确保在使用前已通过 FetchFileToVFS() 加载所需字体，例如：
await window.spire.FetchFileToVFS(
'simsun.ttc', '/Library/Fonts/', '/'
);
提取图片时提示填充类型错误
原因：直接访问 Fill.Picture 属性仅适用于使用图片填充的文本框。若文本框未设置图片填充（例如使用纯色填充），访问该属性会抛出异常。
解决：在访问 Fill.Picture 前先判断文本框的 Fill.FillType 是否为 Picture，确认是图片填充后再获取图片并调用 Save() 方法保存。
获取免费许可证
如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。
