表单控件

表单控件是一种可以被添加到工作表上的浮动对象，以便与工作表中可用的单元格或区域进行交互。通过使用表单控件，可以获取最终用户的输入内容，或者提供选项供其选择。因此往往用于创建填报表单。

GcExcel通过com.grapecity.documents.excel.forms命名空间提供了九种表单控件。其中包含每个表单控件的相关类和接口。

下表列出了支持的表单控件和其呈现的效果。

表单控件	快照
Button
Dropdown
Checkbox
Spinner
Listbox
Option button
Group box
Label
Scrollbar

所有表单控件都具有一些通用功能，这些功能由com.grapecity.documents.excel.forms 命名空间的IControl接口提供。您可以通过 setEnabled 方法设置为false来禁用这些控件，这样用户就无法将焦点放在该控件上。通过 setLocked 方法设置为true，可以锁定控件，使其不接受用户输入。可以使用 setPlacement 方法，将控件添加到某个单元格上。还可以使用 bringToFront 和 sendToBack 方法更改控件的ZOrder，控制表单空格键的Z-index。

添加与删除表单控件

GcExcel允许您使用 IWorksheet 接口的 getControls 方法向工作表添加或删除表单控件。

GcExcel提供了 IControl 接口的 delete 方法，用于从工作表中删除特定表单控件。如果要从工作表中删除所有控件，可以使用 IControlCollection 接口的 clear 方法。

下面的代码演示如何在工作表中添加或删除表单控件：

// Create a new workbook
Workbook workbook = new Workbook();
IWorksheet ws = workbook.getWorksheets().get("Sheet1");

// Add two controls
ILabel lblResolution = ws.getControls().addLabel(12.6, 20.4, 49.2, 18.6);
lblResolution.setText("Resolution");
lblResolution.setPrintObject(true);

IButton btnNative = ws.getControls().addButton(199.8, 21, 127.8, 17.4);
btnNative.setText("Use native resolution");
btnNative.setPrintObject(true);

// Remove the first one
ws.getControls().get(0).delete();
        
// Remove all the controls
// ws.getControls().clear();

将表单控件与单元格区域关联

基于选择的表单控件，即Checkbox、Option button、Listbox、Dropdown和Scrollbar，提供了 ICellLinkControl 接口的 setLinkedCell 方法，该方法支持表单控件的值与关联的单元格范围之间进行双向绑定。关联的单元格范围使得在表单控件中有一组明确的值，以避免最终用户输入无效数据。只需编辑链接单元格区域中的值，即可更新表单控件的值，反之亦然。

下面的代码演示了如何将单元格值关联到 Checkbox 表单控件：

// Link a check box 
ICheckBox checkBox1 = ws.getControls().addCheckBox(54, 13.2, 64.2, 18); 
checkBox1.setLinkedCell(ws.getRange("$A$2"));

查找表单控件

将表单控件设置在工作表上时，GcExcel使用从0开始的索引。可以通过表单控件的名称或类型在工作表中找到表单控件。若要按名称查找excel表单控件，可以使用 getName 方法查找指定的名称。要使用其类型查找表单控件，可以使用 getFormControlType 方法。

下面的代码演示了如何按名称查找表单控件：

// Create a new workbook
Workbook workbook = new Workbook();
IWorksheet ws = workbook.getWorksheets().get("Sheet1");
        
// Add the control
ILabel lblResolution = ws.getControls().addLabel(12.6, 20.4, 49.2, 18.6);
lblResolution.setText("Resolution");
lblResolution.setPrintObject(true);
lblResolution.setName("lblResolution");
        
// Find the control by name
System.out.println(ws.getControls().get("lblResolution").getName());

下面的代码演示了如何按类型查找表单控件：

for (IControl ctl : ws.getControls())
{
    switch (ctl.getFormControlType())
    {
        case Button:
            ctl.setWidth(70);
            break;
        case CheckBox:  
            ctl.setWidth(60);
            break;
        default:
            break;
    }
}

导出表单控件

使用 Workbook 类的 save 方法，可以将带有表单控件的工作表导出为 PDF、XLSX、XLSM、HTML、.sjs 或 SSJSON 格式，并使用 IWorksheet 接口的 toImage 方法导出为 PNG、SVG、JPG 或 GIF 格式。GcExcel 在 IControl 接口中提供了 setVisible 方法，使你能够在导出时包含或排除窗体控件。如果将窗体控件的 Visible 属性设置为 false，则该窗体控件不会导出为 PDF、XLSX、XLSM、.sjs、SSJSON、HTML、PNG、SVG、JPG 或 GIF 格式。

请参阅以下示例代码以从导出中排除窗体控件：

// Add dropdown.
IDropDown dropDown = ws.getControls().addDropDown(28.8, 81.8, 103.8, 31.4);
dropDown.setPrintObject(true);
dropDown.getItems().add(new DropDownItem("Item 1"));
dropDown.getItems().add(new DropDownItem("Item 2"));
dropDown.getItems().add(new DropDownItem("Item 3"));
dropDown.setSelectedIndex(0);
  
// Set Visible to false.
dropDown.setVisible(false);

type=warning
注意：GcExcel 将窗体控件导出为 PNG、SVG、JPG、GIF、HTML 或 PDF 格式的静态图像。

有关将表单控件导出到 PDF 中的交互式表单域，请参阅导出表单控件。

表单控件与形状

在GcExcel Java中表单控件也属于形状。因此，为了识别特定形状是否为窗体控件，ShapeType 枚举提供了一个 FormControl 属性。此外，如果形状是表单控件，则可以使用 IShape 接口的 getControl 方法获取与形状关联的表单控件。另外，您还可以使用 IControl 接口的 getShapeRange 方法获取与表单控件关联的形状。

请参阅以下代码以通过形状控制表单控件：

Workbook workbook = new Workbook();
IWorksheet ws = workbook.getWorksheets().get("Sheet1");
        
// Add form control
IButton button1 = ws.getControls().addButton(50, 100, 120, 40);
IShape buttonShape1 = button1.getShapeRange().get(0);
        
// Duplicate
buttonShape1.duplicate();
        
// Size and move
buttonShape1.setLeft(66.6);
buttonShape1.setTop(22.8);
buttonShape1.setWidth(155.4);
buttonShape1.setHeight(49.2);
        
// Delete
buttonShape1.delete();

限制

不支持导出GcExcel Java表单控件中的富文本和样式。
获取或设置窗体控件中的宏名称需要 VBA 项目。
在操作时调用宏需要 VBA 项目和 COM 交互。
链接对象和“复制到剪贴板”功能需要 Window OLE 自动化交互。
Excel表单控件中的拼写检查需要 Windows 语言包交互。
在Excel输入/输出图形Xml和Vml中的替代内容时，会丢失一些节点。

添加单选按钮组

在 GcExcel 中，可以将两个或多个选项按钮分组到一个分组框中，以便您可以从多个相关但相互排斥的选项中选择一个选项。GcExcel 使用 IOptionButton 接口的 getGroupBox 方法（只读）对选项按钮进行分组，该方法由选项按钮和分组框的边界标识。如果选项按钮完全位于分组框中，则 getGroupBox 方法是第一个匹配的分组框。如果没有匹配的分组框，则选项按钮位于默认组（即工作表）中。

当两个或多个选项按钮位于同一组中时，它们会影响其他选项按钮的选择状态，并允许您在同一组中一次只选择一个选项按钮。它们还共享 setLinkedCell 方法，这意味着您可以为组中的一个选项按钮定义 setLinkedCell，而同一组中的其他选项按钮可以使用 setLinkedCell 值。

type=warning
注意：当分组框或选项按钮失去焦点时，通过在每个分组框控件上调用Cut（Left，Top）来显式重新计算选项按钮组。

请参阅以下示例代码以添加两个单独的分组框，每个分组框都有各自的链接选项按钮：

// Initialize Workbook.
Workbook workbook = new Workbook();

// Create a worksheet.
IWorksheet ws = workbook.getWorksheets().get("Sheet1");

// Add option buttons and group boxes to the worksheet.
String rngB2 = "Option buttons are grouped by group boxes.";
ws.getRange("B2").setValue(rngB2);
ws.getRange("B13:C13").setValue( new Object[][] {
    { "Value", 1d}
});

ws.getRange("E13:F13").setValue(new Object[][] {
    { "Value", 2d}
});

ws.getRange("A:A").setColumnWidthInPixel(37d);

// Add first group box.
IGroupBox group1 = ws.getControls().addGroupBox(29.75, 48.2, 136.5, 113.99);
group1.setText("Group 1");

// Add option buttons.
IOptionButton optionButton2 = ws.getControls().addOptionButton(39.45, 67.1, 98, 15.60);
optionButton2.setLinkedCell(ws.getRange("C13"));
optionButton2.setIsChecked(true);

ws.getControls().addOptionButton(39.45, 97.5, 98, 17.40);

ws.getControls().addOptionButton(39.45, 131.2, 98, 17.5);

// Add second group box.
IGroupBox group2 = ws.getControls().addGroupBox(191.95, 48.2, 136.5, 113.99);
group2.setText("Group 2");

// Add option buttons.
ws.getControls().addOptionButton(200.35, 65.7, 117.6, 18.5);

IOptionButton optionButton7 = ws.getControls().addOptionButton(200.35, 95.99, 117.6, 21.28);

// Set linked cell.
optionButton7.setLinkedCell(ws.getRange("F13"));
optionButton7.setIsChecked(true);

ws.getControls().addOptionButton(200.35, 129.2, 117.6, 21.40);
    
// Save the workbook.
workbook.save("OptionButtonsBasicUsage.xlsx");

type=warning
注意：将选项按钮添加到重叠的分组框可能与在 Microsoft Excel 中不同。

限制

不支持在 GcExcel Java 表单控件中导出富文本和样式。
在窗体控件中获取或设置宏名称需要 VBA 项目。
VBA 项目和 COM 互操作性是 OnAction 时调用宏所必需的。
LinkedObject 和“复制到剪贴板”功能需要 Window OLE 自动化互操作性。
Excel 窗体控件中的拼写检查需要 Windows 语言包互操作性。
在绘图 Xml 和 Vml 中的替代内容的 Excel I/O 期间，某些节点会丢失。
在选项按钮组中，当测量结果与 Excel 不同时，某些选项按钮将加入不同的组。