形状和图片

GcExcel Java 允许您在工作表单元格中插入各种类型的形状，包括标准形状、连接器形状、图片形状和组合形状。您可以使用 IShape 和 IShapes 接口的属性和方法统一管理和操作这些形状。

添加形状

GcExcel Java 提供了 IShapes 接口的 AddShape 方法，该方法支持多种重载形式。这使您能够在工作表的指定位置或指定单元格范围内添加各种类型的形状，并设置它们的大小。您可以为每个新创建的形状分配一个自定义名称，这样便于通过名称直接访问和修改形状的属性，而无需遍历整个形状集合。

以下示例演示了如何在指定位置添加一个矩形形状并为其分配名称。您也可以参考 AutoShapeType 枚举添加其他类型的形状。

// 创建工作簿
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getWorksheets().get(0);

// 在特定位置添加一个带有自定义名称的形状
IShape shape = worksheet.getShapes().addShape("Rectangle", AutoShapeType.Rectangle, 50, 50, 100, 150);

// 或者，将形状添加到指定范围
// IShape rangeShape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, worksheet.Range["F5:I10"]);

// 分配新名称并通过名称获取形状
shape.setName("NewRectangleName");
IShape balloon = worksheet.getShapes().get("NewRectangleName");
balloon.getTextFrame().getTextRange().setText("Rectangle Shape");
balloon.getTextFrame().getTextRange().setTextAlignment(TextAlignmentAnchor.Center);

// 保存 Excel 文件
workbook.Save("RectangleShape.xlsx");

输出结果如下图所示：

获取形状类型

每个形状对象都包含一个 Type 属性，用于指示形状的具体类型。该属性对应于 ShapeType 枚举。通过读取 Type 属性，您可以快速获取并识别形状的类型（例如标注、文本框、线条等）。

以下示例演示了如何遍历工作表中的所有形状，并在每个形状的右侧显示类型标签。点击此处下载工作表：

ShapeType.xlsx

// 创建新工作簿
Workbook workbook = new Workbook();

// 导入工作簿
InputStream fileStream = this.getResourceStream("xlsx/ShapeType.xlsx");
workbook.open(fileStream);

IWorksheet sheet = workbook.getWorksheets().get(0);

int row = 2;
int column = 4;
for (int i = 0; i < sheet.getShapes().getCount(); i++) {
    IShape shape = sheet.getShapes().get(i);

    // 在形状右侧添加文本以显示形状类型
    sheet.getRange(row, column).setValue("This is a " + shape.getType().toString() + ".");
    sheet.getRange(row, column).getFont().setBold(true);
    sheet.getRange(row, column).getFont().setSize(13);

    if ((i + 1) % 4 == 0) {
        row = 2;
        column += 6;
    } else {
        row += 10;
    }
}

// 保存到 Excel 文件
workbook.save("GetShapeType.xlsx");

输出结果如下图所示：

以下示例演示了如何遍历工作表中的所有形状，从自选形状中筛选出矩形，并输出每个矩形的像素级位置信息（包括顶部、左侧、高度和宽度）。点击此处下载工作表：

AutoShapeType.xlsx

// 创建新工作簿
Workbook workbook = new Workbook();

// 导入工作簿
workbook.open("AutoShapeType.xlsx");
IWorksheet sheet = workbook.getWorksheets().get(0);

// 遍历工作表中的所有形状对象
for (int i = 0; i < sheet.getShapes().getCount(); i++) {
    IShape shape = sheet.getShapes().get(i);
    if (shape.getType() == ShapeType.AutoShape && shape.getAutoShapeType() == AutoShapeType.Rectangle) {
        // 输出矩形的位置和大小
        System.out.println("Top: " + shape.getTop() +
                " , Left: " + shape.getLeft() +
                " , Height: " + shape.getHeight() +
                ", Width: " + shape.getWidth());
    }
}

形状调整

在 GcExcel Java 中，除了更改形状的大小外，您还可以更改形状的几何结构并修改其外观。这可以通过设置形状（如自选形状或连接器）的调整值来实现。它使您能够更好地控制形状，以便创建高效的流程图、仪表板和报告。

GcExcel Java 在 IShape 接口中提供了 Adjustments 方法，用于获取指定自选形状或连接器的调整值集合。

不同调整类型的调整值有效范围如下：

调整类型	有效值
线性（水平或垂直）	值 0.0 表示形状的左边缘或上边缘。值 1.0 表示形状的右边缘或下边缘。对于连接器和标注等形状，值 0.0 和 1.0 对应于由连接器或标注线的起点和终点定义的矩形。小于 0.0 和大于 1.0 的值也是有效的。调整的有效值对应于在 Excel 中通过拉伸调整点可以对形状进行的有效调整。例如，如果在 Excel 中只能将调整点拉到形状的一半位置，则相应调整的最大值将为 0.5。
径向	值 1.0 表示形状宽度。因此，径向调整的最大值为 0.5，即形状宽度的一半。
角度	值以度为单位。如果指定的值超出 180 度范围，它将被规范化到该范围内。

调整类型

有效值

线性（水平或垂直）

值 0.0 表示形状的左边缘或上边缘。

值 1.0 表示形状的右边缘或下边缘。

对于连接器和标注等形状，值 0.0 和 1.0 对应于由连接器或标注线的起点和终点定义的矩形。

小于 0.0 和大于 1.0 的值也是有效的。

调整的有效值对应于在 Excel 中通过拉伸调整点可以对形状进行的有效调整。

例如，如果在 Excel 中只能将调整点拉到形状的一半位置，则相应调整的最大值将为 0.5。

径向

值 1.0 表示形状宽度。因此，径向调整的最大值为 0.5，即形状宽度的一半。

角度

值以度为单位。如果指定的值超出 180 度范围，它将被规范化到该范围内。

在大多数情况下，如果值超出有效范围，会将其规范化为最接近的有效值。

参考以下示例代码调整 Excel 中形状的尺寸：

private static void AdjustmentPointForShape() {
    // 初始化工作簿
    Workbook workbook = new Workbook();
    // 获取默认工作表
    IWorksheet worksheet = workbook.getWorksheets().get(0);
    // 添加右箭头标注
    IShape shape = worksheet.getShapes().addShape(AutoShapeType.RightArrowCallout, 20, 20, 200, 100);

    // 设置形状的调整点
    IAdjustments adjustments = shape.getAdjustments();

    // 计算调整点数量
    int c = adjustments.getCount();
    System.out.println("调整值的数量：" + c);

    adjustments.set(0, 0.5);// 箭头颈部宽度
    adjustments.set(1, 0.4);// 箭头头部宽度
    adjustments.set(2, 0.5);// 箭头头部高度
    adjustments.set(3, 0.6);// 文本框宽度

    // 将工作簿保存为 Xlsx 格式
    workbook.save("17-AdjustmentPointForShape.xlsx", SaveFileFormat.Xlsx);
}

控制重叠形状的位置

工作表中重叠形状的顺序由它们的 z 顺序位置决定。GcExcel Java 允许用户设置形状的 z 顺序，以便在创建流程图或业务图表等时控制它们的位置。

GcExcel API 中的 zOrder 方法可用于将指定形状移到其他形状的前面或后面。它接受 ZOrderType 枚举作为参数，用于指定形状相对于其他形状的位置。

IShape 接口的 getZOrderPosition 方法可用于获取指定形状在 z 顺序中的位置。

!type=note
注意：如果形状的 z 顺序发生更改，该形状在 Worksheet.Shapes 集合中的索引也会更改。

参考以下示例代码在工作表中添加各种形状、更改它们的 z 顺序并获取它们在 z 顺序中的位置。

// 创建新工作簿
Workbook workbook = new Workbook();
// 获取默认工作表
IWorksheet worksheet = workbook.getActiveSheet();

IShapes shapes = worksheet.getShapes();

// 添加形状
IShape rectangle = shapes.addShape(AutoShapeType.Rectangle, 20, 20, 100, 100);
rectangle.getFill().getColor().setRGB(Color.GetBlue());

IShape oval = shapes.addShape(AutoShapeType.Oval, 50, 50, 100, 100);
oval.getFill().getColor().setRGB(Color.GetGreen());

IShape pentagon = shapes.addShape(AutoShapeType.Pentagon, 80, 80, 100, 100);
pentagon.getFill().getColor().setRGB(Color.GetRed());

IShape triangle = shapes.addShape(AutoShapeType.IsoscelesTriangle, 100, 100, 100, 100);
triangle.getFill().getColor().setRGB(Color.GetOrange());

// 将矩形移到椭圆上方
rectangle.zOrder(ZOrderType.BringForward);

// 获取矩形在 z 顺序中的位置
System.out.println("矩形的 z 顺序：" + rectangle.getZOrderPosition());

// 将三角形移到最底部
triangle.zOrder(ZOrderType.SendToBack);

// 获取三角形在 z 顺序中的位置
System.out.println("三角形的 z 顺序：" + triangle.getZOrderPosition());

// 保存到 Excel 文件
workbook.save("SetShapeZOrder.xlsx");

另请参见

合并单元格