[]
GcExcel 允许您在工作表的单元格上嵌入多种形状,包括常规形状、连接线、图片形状和组合形状等。您可以通过访问 IShape 和 IShapes 接口的属性和方法,对这些形状进行统一管理和操作。
GcExcel 提供了 IShapes 接口的 AddShape 方法,该方法支持多种重载,可以在工作表的指定位置或者指定单元格范围内添加各种类型的形状并指定大小,您可以为新建的形状指定配自定义名称,便于后续通过名称直接访问该形状并修改其属性,而无需遍历全部形状集合。
以下示例演示如何在指定位置添加Rectangle形状并设置名称。您还可以参考 AutoShapeType 枚举添加其他类型的形状。
// 创建工作簿。
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.Worksheets[0];
// 在特定位置添加一个带自定义名称的形状。
IShape shape = worksheet.Shapes.AddShape("Rectangle", AutoShapeType.Rectangle, 50, 50, 100, 150);
// 或者添加到指定范围。
// IShape rangeShape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, worksheet.Range["F5:I10"]);
// 分配新名称并通过名称获取形状。
shape.Name = "NewRectangleName";
IShape balloon = worksheet.Shapes["NewRectangleName"];
balloon.TextFrame.TextRange.Text = "Rectangle Shape";
balloon.TextFrame.TextRange.TextAlignment=TextAlignmentAnchor.Center;
// 保存Excel文件。
workbook.Save("RectangleShape.xlsx");输出结果如下:

每个形状对象(Shape)都包含一个 Type 属性,用于指示该形状的具体类型,该属性对应 ShapeType 枚举。通过读取 Type 属性,您可以快速获取并辨识形状的具体类型(例如:标注、文本框、直线等)。
以下示例演示如何遍历工作表中所有的形状,并在形状右侧标出其类型说明。点击此处下载工作表。
// 创建工作簿。
var workbook = new GrapeCity.Documents.Excel.Workbook();
// 导入工作簿。
var fileStream = this.GetResourceStream("xlsx\\ShapeType.xlsx");
workbook.Open(fileStream);
var sheet = workbook.Worksheets[0];
int row = 2;
int column = 4;
for (int i = 0; i < sheet.Shapes.Count; i++)
{
var shape = sheet.Shapes[i];
// 在形状右侧添加一段文字,用于显示该形状的类型。
sheet.Range[row, column].Value = "This is a " + shape.Type.ToString() + ".";
sheet.Range[row, column].Font.Bold = true;
sheet.Range[row, column].Font.Size = 13;
if ((i + 1) % 4 == 0)
{
row = 2;
column += 6;
}
else
{
row += 10;
}
}
// 保存 Excel 文件。
workbook.Save("GetShapeType.xlsx");结果如下图所示:

以下示例演示如何遍历工作表中所有的形状对象,筛选出属于自动形状(AutoShape)中的矩形(Rectangle),并输出每个矩形的像素级位置信息(包括上边距、左边距、高度和宽度)。
// 创建工作簿。
var workbook = new GrapeCity.Documents.Excel.Workbook();
// 导入工作簿。
var fileStream = this.GetResourceStream("xlsx\\AutoShapeType.xlsx");
workbook.Open(fileStream);
var sheet = workbook.Worksheets[0];
// 遍历工作表中的所有形状对象。
for (int i = 0; i < sheet.Shapes.Count; i++)
{
var shape = sheet.Shapes[i];
if (shape.Type == ShapeType.AutoShape && shape.AutoShapeType == AutoShapeType.Rectangle)
{
// 输出矩形的位置及尺寸信息。
Console.WriteLine("Top: " + shape.Top + " , Left: " + shape.Left + " , Height: " + shape.Height + ", Width: " + shape.Width);
}
}Apart from changing the size of a shape in GcExcel, you can also change the geometry of a shape and modify its appearance. This can be achieved by setting the adjustment values of shapes, such as AutoShapes or Connectors. It allows you to have more control over the shapes in order to create efficient flowcharts, dashboards and reports.
GcExcel provides the Adjustments property in the IShape interface to get a collection of adjustment values for the specified AutoShape or Connector.
The valid ranges of adjustent values for different adjustement types are described below:
Adjustment type | Valid values |
|---|---|
Linear (horizontal or vertical) | Value 0.0 represents the left or top edge of the shape. Value 1.0 represents the right or bottom edge of the shape. For shapes such as connectors and callouts, the values 0.0 and 1.0 correspond to the rectangle defined by the starting and ending points of the connector or callout line. Values lesser than 0.0 and greater than 1.0 are also valid. The valid values for the adjustment correspond to the valid adjustments that can be made to shapes in Excel by extending the adjustment points. For example, if you can only pull an adjustment point half way across the shape in Excel, the maximum value for the corresponding adjustment will be 0.5. |
Radial | Value 1.0 represents the shape width. Hence, the maximum value for radial adjustment is 0.5, which is half way across the shape. |
Angle | Value is expressed in degrees. If you specify the value outside the range of 180 degree, it will be normalized to be within that range. |
In most cases, if a value exceeds the valid range, it is normalized to the closest valid value.
Refer to the following example code to adjust the dimensions of a shape in Excel:
public void AdjustmentPointForShape()
{
// Initialize workbook
Workbook workbook = new Workbook();
// Fetch default worksheet
IWorksheet worksheet = workbook.Worksheets[0];
// Add a right arrow callout
IShape shape = worksheet.Shapes.AddShape(AutoShapeType.RightArrowCallout, 20, 20, 200, 100);
IAdjustments adjustments = shape.Adjustments;
// Get the count of adjustment values for shape
int c = adjustments.Count;
Console.WriteLine("Count of Adjustment Values: " + c.ToString());
// Set adjustment values for shapes
adjustments[0] = 0.5;// arrow neck width
adjustments[1] = 0.4;// arrow head width
adjustments[2] = 0.5;// arrow head height
adjustments[3] = 0.6;// text box width
// Saving workbook to Xlsx
workbook.Save(@"AdjustmentPointForShape.xlsx", SaveFileFormat.Xlsx);
}The order of overlapping shapes in a worksheet is decided by their z-order positions. GcExcel allows its users to set the z-order of shapes so that their positions can be controlled while creating flow charts or business diagrams etc.
The ZOrder method in GcExcel API can be used to move the specified shape in front of or behind the other shapes. It takes ZOrderType enum as a parameter to specify the position of a shape relative to the other shapes.
The ZOrderPosition property of the IShape interface can be used to retrieve the position of a specified shape in the z-order.
Note: If the z-order of a shape is changed, the index of the shape in Worksheet.Shapes collection is also changed.
Refer to the below example code to add various shapes, change their z-order and get their positions in z-order in a worksheet.
// Initialize workbook
Workbook workbook = new Workbook();
// Fetch default worksheet
IWorksheet worksheet = workbook.Worksheets[0];
IShapes shapes = worksheet.Shapes;
//add shapes
IShape rectangle = shapes.AddShape(AutoShapeType.Rectangle, 20, 20, 100, 100);
rectangle.Fill.Color.RGB = System.Drawing.Color.Blue;
IShape oval = shapes.AddShape(AutoShapeType.Oval, 50, 50, 100, 100);
oval.Fill.Color.RGB = System.Drawing.Color.Green;
IShape pentagon = shapes.AddShape(AutoShapeType.Pentagon, 80, 80, 100, 100);
pentagon.Fill.Color.RGB = System.Drawing.Color.Red;
IShape triangle = shapes.AddShape(AutoShapeType.IsoscelesTriangle, 100, 100, 100, 100);
triangle.Fill.Color.RGB = System.Drawing.Color.Orange;
//set rectangle above oval
rectangle.ZOrder(ZOrderType.BringForward);
//get position of rectangle in z-order
Console.WriteLine("Z-Order rectangle: " + rectangle.ZOrderPosition);
//set triangle to bottom
triangle.ZOrder(ZOrderType.SendToBack);
//get position of triangle in z-order
Console.WriteLine("Z-Order triangle: " + triangle.ZOrderPosition);
//save to an excel file
workbook.Save("setshapezorder.xlsx");
Note:
GcExcel.NET also provides support for loading and saving SpreadJS JSON files with shapes. For more information, refer to Import and Export SpreadJS Files.
The targetRange and the shape to be added must exist in the same worksheet. Otherwise, it results into an InvalidOperationException.