任务清单、检查表和待办列表常需要逐项打勾。与在单元格里输入“是/否”相比，复选框让完成状态一目了然，也减少了输入错误。本文使用 Spire.XLS for JavaScript 在浏览器端为 Excel 添加复选框，输入输出文件通过虚拟文件系统（VFS）管理，无需后端服务。

本文介绍两个核心功能点：

• 添加复选框并设置标题
• 调整复选框的大小与立体效果

有关安装和项目配置，请参考 React 项目中集成 Spire.XLS for JavaScript。以下示例默认已安装 Spire.XLS 并完成 WebAssembly 模块初始化。

添加复选框并设置标题

复选框以表单控件的形式浮在单元格上方，位置由所在行列决定，大小以像素为单位。添加后可以先设置标题文字，让读者知道这个复选框代表哪一项，再按需要调整位置和尺寸。

添加复选框并设置标题的写法与结果：

具体操作步骤如下：

1. 用 window.spire.FetchFileToVFS 把字体文件与 Excel 测试文件载入 VFS。
2. 用 new Workbook() 新建工作簿，再用 workbook.LoadFromFile 载入测试文件。
3. 调用 workbook.Worksheets.get(0) 取得任务清单工作表。
4. 用 sheet.CheckBoxes.AddCheckBox(row, column, height, width) 在第 2、3、4 行第 4 列各添加一个复选框。
5. 把三个复选框的 checkbox.Text 分别设为“未完成”、“已完成”和“部分完成”。
6. 把三个复选框的 checkbox.CheckState 分别设为 xlsModule.CheckState.Unchecked、xlsModule.CheckState.Checked 和 xlsModule.CheckState.Mixed，展示三种状态。
7. 用 workbook.SaveToFile 写出结果文件，再用 workbook.Dispose 释放资源并从 VFS 读取工作簿触发下载。

以下为完整的代码示例，演示如何添加复选框并设置标题：

function App() {
  const addCheckbox = 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 = 'CheckBoxData.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);

    // 在第 2、3、4 行第 4 列各添加一个复选框
    const uncheckedBox = sheet.CheckBoxes.AddCheckBox(2, 4, 20, 120);
    const checkedBox = sheet.CheckBoxes.AddCheckBox(3, 4, 20, 120);
    const mixedBox = sheet.CheckBoxes.AddCheckBox(4, 4, 20, 120);

    // 分别设置三个复选框的标题
    uncheckedBox.Text = '未完成';
    checkedBox.Text = '已完成';
    mixedBox.Text = '部分完成';

    // 分别设置未勾选、已勾选和混合状态
    uncheckedBox.CheckState = xlsModule.CheckState.Unchecked;
    checkedBox.CheckState = xlsModule.CheckState.Checked;
    mixedBox.CheckState = xlsModule.CheckState.Mixed;

    // 将结果保存到 VFS
    const outputFileName = 'AddCheckbox.xlsx';
    workbook.SaveToFile({ fileName: outputFileName });

    // 释放 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>在 React 中为 Excel 添加复选框</h1>
      <button id="add-checkbox" onClick={addCheckbox}>添加复选框</button>
    </div>
  );
}

export default App;

添加复选框后的工作簿：

调整复选框的大小与立体效果

默认尺寸适合短标题，标题较长或需要更醒目的区域时，可以在添加时指定更大的宽高。立体效果会给复选框加上内凹的边框和阴影，让它更接近传统表单控件的外观。

调整复选框的大小与立体效果的写法与结果：

具体操作步骤如下：

1. 用 window.spire.FetchFileToVFS 把字体文件与 Excel 测试文件载入 VFS。
2. 用 new Workbook() 新建工作簿，再用 workbook.LoadFromFile 载入测试文件。
3. 调用 workbook.Worksheets.get(0) 取得任务清单工作表。
4. 用 sheet.CheckBoxes.AddCheckBox(2, 4, 24, 160) 添加一个更大的复选框，并设置标题。
5. 把 checkbox.Display3DShading 设为 true。
6. 用 workbook.SaveToFile 写出结果文件，再用 workbook.Dispose 释放资源并从 VFS 读取工作簿触发下载。

以下为完整的代码示例，演示如何调整复选框的大小与立体效果：

function App() {
  const customizeCheckbox = 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 = 'CheckBoxData.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 checkbox = sheet.CheckBoxes.AddCheckBox(2, 4, 24, 160);
    checkbox.Text = '已完成';

    // 显示立体边框与阴影
    checkbox.Display3DShading = true;

    // 将结果保存到 VFS
    const outputFileName = 'CheckboxSizeAndShading.xlsx';
    workbook.SaveToFile({ fileName: outputFileName });

    // 释放 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>在 React 中为 Excel 添加复选框</h1>
      <button id="size-and-shading" onClick={customizeCheckbox}>调整大小与立体效果</button>
    </div>
  );
}

export default App;

调整复选框大小与立体效果后的工作簿：

常见问题

添加的复选框没有出现在预期位置

原因：复选框的位置由添加时指定的行号和列号决定，如果行列号对应的是隐藏行、合并单元格或尺寸很小的单元格，复选框可能被遮挡或挤在一起。

解决：先确认目标行列号，并调整对应列宽和行高；需要更精确的位置时，可以再设置复选框的 Left、Top、Width 和 Height。

复选框标题仍然是默认的“Check Box 1”

原因：新建复选框会带有默认标题，不设置 Text 就会保留这个名称。

解决：添加后立即把 checkbox.Text 设为需要的文字，例如“已完成”或该行的任务名称。

复选框尺寸不合适或文字显示不完整

原因：添加时指定的高度和宽度以像素为单位，宽高过小会让较长的标题被截断，行高或列宽过小也会让复选框显示不全。

解决：按标题长度增加 AddCheckBox 的宽度和高度，并适当调大所在列的列宽、所在行的行高。

获取免费许可证

如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。