单元格复选框

单元格复选框是嵌入在工作表单元格中的交互式控件。它支持三种状态：选中、未选中、不确定，并且与单元格值（真/假/空值）相绑定。复选框属于单元格的一部分，在执行排序、筛选、插入行/列、删除行/列等操作时，会随单元格一同移动。GcExcel Java 支持在工作表中创建、设置和移除单元格复选框，并且导出为 PDF 和图片时可保留复选框的显示样式。

当单元格包含复选框时，单元格值与复选框状态的对应关系如下表所示：

单元格值（IRange.Value）	复选框状态	显示效果
真	选中
假	未选中
空值	不确定
文本/数字/错误值	无复选框	显示原始单元格值

为单元格添加复选框

GcExcel Java 提供了 ICellControl 接口的 setCheckbox 方法，可对所选区域内所有单元格添加复选框。该操作会替换目标区域现有的单元格控件格式，但不会更改单元格原有数值。若要实现与微软 Excel 一致的效果（即复选框初始为未选中状态），可在添加复选框后通过 IRange.setValue 将单元格值设置为 false。

添加复选框后，可使用 ICellControl 接口的 getType 方法获取当前区域的控件类型。若区域内所有单元格控件类型一致，则返回对应类型；否则返回 CellControlType.None。当前版本仅支持复选框这一种控件类型。

以下示例演示如何批量为单元格添加复选框，并设置不同单元格值以展示不同的复选框状态。

// 新建工作簿
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getWorksheets().get(0);
// 设置单元格数据
worksheet.getRange("B3:D12").setValue(new Object[][]{        
{"任务", "分配人", "是否完成"},        
{"撰写项目方案", "爱丽丝", false},        
{"设计项目架构", "鲍勃", true},        
{"开发项目模块", "查理", false},        
{"测试项目组件", "戴安娜", true},        
{"项目部署上线", "伊森", false},        
{"编写用户文档", "菲奥娜", true},        
{"开展培训会议", "乔治", null},        
{"执行代码重构", "蕾切尔", true},        
{"组织团队会议", "山姆", "不确定"}
});
worksheet.getRange("B:B").setColumnWidth(28);
worksheet.getRange("C:D").setColumnWidth(12);
worksheet.getRange("F:G").setColumnWidth(14);
worksheet.getRange("B3:D3").getInterior().setColor(Color.FromArgb(155, 194, 230));
worksheet.getRange("F3:G3").getInterior().setColor(Color.FromArgb(155, 194, 230));
worksheet.getRange("B3:G3").getFont().setBold(true);
// 为 D4:D12 区域单元格添加复选框
worksheet.getRange("D4:D12").getCellControl().setCheckbox();
worksheet.getRange("F3:G6").setValue(new Object[][]{        
{"复选框状态", "数量"},        
{"已选中", null},        
{"未选中", null},        
{"总计", null}
});
worksheet.getRange("G4").setFormula("=COUNTIF(D4:D12, TRUE)");
worksheet.getRange("G5").setFormula("=COUNTIF(D4:D12, FALSE)");
worksheet.getRange("G6").setFormula("=COUNTA(D4:D12)");
// 保存为 Excel 文件
workbook.save("CellCheckbox.xlsx");

运行效果如下图所示：

配置复选框格式

复选框作为单元格的组成部分，会继承单元格的格式样式，包括填充色、对齐方式、字体大小和字体颜色等。

以下示例演示通过设置单元格字体样式来自定义复选框外观。

// 新建工作簿
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getWorksheets().get(0);
// 设置列宽与表头样式
worksheet.getRange("B:C").setColumnWidth(28);
worksheet.getRange("B3:C3").getInterior().setColor(Color.FromArgb(155, 194, 230));
worksheet.getRange("B3:C3").getFont().setBold(true);
workbook.getActiveSheet().getRange("B3").setValue("格式设置");
workbook.getActiveSheet().getRange("C3").setValue("复选框状态");
workbook.getActiveSheet().getRange("B4").setValue("未设置格式");
workbook.getActiveSheet().getRange("B5").setValue("已设置格式");
// 为 C4:C5 单元格添加复选框并默认选中
workbook.getActiveSheet().getRange("C4:C5").setValue(true);
worksheet.getRange("C4:C5").getCellControl().setCheckbox();
// 为 C5 单元格设置自定义格式
worksheet.getRange("C5").getInterior().setColor(Color.GetOrange());
worksheet.getRange("C5").getFont().setColor(Color.GetRed());
worksheet.getRange("C5").getFont().setSize(16);
worksheet.getRange("C5").setHorizontalAlignment(HorizontalAlignment.Left);
// 保存为 Excel 文件
workbook.save("CellCheckboxFormat.xlsx");

运行效果如下图所示：

复制粘贴复选框

复制包含复选框的单元格时，复选框会随单元格一同被复制。粘贴时是否保留复选框，取决于粘贴类型是否包含格式（PasteType.Formats）。若包含格式，则复选框会粘贴到目标单元格；若不包含格式，则不会显示复选框控件。

以下示例演示带格式和不带格式两种方式复制粘贴复选框。

// 新建工作簿
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getWorksheets().get(0);
worksheet.getRange("A:A").setColumnWidth(28);
workbook.getActiveSheet().getRange("B5").setValue(true);
workbook.getActiveSheet().getRange("C5").setValue(false);
// 为 B5:C5 单元格添加复选框
worksheet.getRange("B5:C5").getCellControl().setCheckbox();
workbook.getActiveSheet().getRange("A7").setValue("带格式复制");
workbook.getActiveSheet().getRange("A8").setValue("不带格式复制");
// 复制复选框并粘贴到指定单元格
worksheet.getRange("B5").copy(worksheet.getRange("B7"));
PasteOption pasteOption = new PasteOption();
pasteOption.setPasteType(EnumSet.complementOf(EnumSet.of(PasteType.Formats)));
worksheet.getRange("B5").copy(worksheet.getRange("B8"), pasteOption);
worksheet.getRange("C5").copy(worksheet.getRange("C7"));
worksheet.getRange("C5").copy(worksheet.getRange("C8"), pasteOption);
// 保存为 Excel 文件
workbook.save("CopyCellCheckbox.xlsx");

运行效果如下图所示：

移除复选框

GcExcel 提供了 IRange 接口的 removeControls 方法，可移除单元格中的复选框控件并保留单元格原有数值。

此外，也可通过单元格内容清除策略移除复选框：

使用 IRange.clear 方法：同时移除复选框控件、单元格格式和单元格数值。
使用 IRange.clearFormats 方法：仅移除复选框控件和单元格格式，保留单元格数值。
使用 IRange.clearContents 方法：仅清除单元格数值，保留复选框控件和单元格格式。

// 移除复选框控件，保留单元格值
worksheet.getRange("A5").removeControls();
// 移除复选框控件、格式和单元格值
worksheet.getRange("B5").clear();
// 移除复选框控件和格式，保留单元格值
worksheet.getRange("C5").clearFormats();
// 清除单元格值，保留复选框控件和格式
worksheet.getRange("D5").clearContents();

注意：SpreadJS 在现代模式下复用现有的 CheckBoxCellType 适配 Excel 单元格复选框的行为。GcExcel 支持单元格复选框在 SJS 和 SSJSON 格式间无损转换：
通过 ICellControl.setCheckbox 方法创建的单元格复选框，另存为 SJS 或 SSJSON 文件时，会以现代 CheckBoxCellType 模式导出，确保 SpreadJS 可正常识别并展示。
从 SJS 或 SSJSON 格式导入 CheckBoxCellType 时，可通过 IRange.getCellControl 获取该复选框类型。现代模式下的 CheckBoxCellType 导出为 Excel 文件后，可被微软 Excel 识别并显示。若 CheckBoxCellType 开启三态属性 isThreeState: true 且单元格值为空值，GcExcel 会将其渲染为不确定状态。
CheckBoxListCellType 在显示效果和交互行为上与现代 CheckBoxCellType 保持一致。