【C#】【EXCEL】Bumblebee/Classes/ExWorksheet.cs

Bumblebee/Classes/ExWorksheet.cs

Flow diagram

当然，我会为您创建一个基于这段代码的流程图，并提供中英双语说明。这个流程图将展示 ExWorksheet 类的主要功能和方法。

这个流程图展示了 ExWorksheet 类的主要结构和功能：

1. 构造函数 (Constructors):

   • 默认构造函数 (Default Constructor)
   • 从 ExRange 构造 (Construct from ExRange)
   • 从 XL.Worksheet 构造 (Construct from XL.Worksheet)
   • 复制构造函数 (Copy Constructor)

2. 属性 (Properties):

   • Name (名称)
   • Workbook (工作簿)
   • ParentApp (父应用程序)

3. 方法 (Methods):

   • ActiveWorksheet (获取活动工作表)
   • Freeze/UnFreeze (冻结/解冻屏幕更新)
   • SetSheet (设置工作表)
   • Activate (激活工作表)
   • Listen (监听变化)
   • ClearSheet (清除工作表内容)
   • WriteData (写入数据):
     • 写入 ExRow 数据
     • 写入 ExColumn 数据
     • 写入 GH_String 数据
   • GetRange (获取单元格范围):
     • 通过起始和结束单元格获取
     • 通过范围字符串获取
   • GetUsedRange (获取已使用范围)
   • AddPicture (添加图片)

这个流程图展示了 ExWorksheet 类的主要功能和结构，有助于理解代码的整体架构和各个部分的关系。

Description

1. Freeze() 和 UnFreeze() 方法

public void Freeze()
{
    this.ComObj.Application.ScreenUpdating = false;
}

public void UnFreeze()
{
    this.ComObj.Application.ScreenUpdating = true;
}

这两个方法用于控制Excel的屏幕更新。

• Freeze(): 暂停屏幕更新，可以提高大量数据操作时的性能。
• UnFreeze(): 恢复屏幕更新，通常在完成数据操作后调用。

英文说明：
These methods control Excel’s screen updating.

• Freeze(): Pauses screen updating to improve performance during large data operations.
• UnFreeze(): Resumes screen updating, typically called after data operations are complete.

2. SetSheet() 方法

public void SetSheet(XL.Worksheet comObject)
{
    this.ComObj = comObject;
    this.name = comObject.Name;
}

这个方法用于设置当前ExWorksheet对象的工作表。

• 它接受一个XL.Worksheet对象作为参数。
• 更新内部的ComObj引用和name属性。

英文说明：
This method sets the worksheet for the current ExWorksheet object.

• It takes an XL.Worksheet object as a parameter.
• Updates the internal ComObj reference and name property.

3. Activate() 方法

public void Activate()
{
    this.ComObj.Activate();
}

这个方法用于激活当前工作表，使其成为活动工作表。

英文说明：
This method activates the current worksheet, making it the active sheet.

4. Listen() 方法

public void Listen(GH_Component component, bool activate)
{
    this.ComObj.Change -= (o) => { component.ExpireSolution(true); };
    if(activate) this.ComObj.Change += (o) => { component.ExpireSolution(true); };
}

这个方法用于设置工作表变化的监听器。

• 它接受一个Grasshopper组件和一个布尔值作为参数。
• 如果activate为true，则添加一个事件处理器来监听工作表的变化。
• 当工作表发生变化时，会使Grasshopper组件的解决方案过期。

英文说明：
This method sets up a listener for worksheet changes.

• It takes a Grasshopper component and a boolean as parameters.
• If activate is true, it adds an event handler to listen for worksheet changes.
• When the worksheet changes, it expires the Grasshopper component’s solution.

5. ClearSheet() 方法

public void ClearSheet()
{
    ExRange range = this.GetUsedRange();
    range.ClearContent();
    range.ClearFormat();
}

这个方法用于清除工作表的内容和格式。

• 获取已使用的单元格范围。
• 清除该范围内的内容和格式。

英文说明：
This method clears the content and formatting of the worksheet.

• Gets the used range of cells.
• Clears both content and formatting within that range.

6. WriteData() 方法

这个方法有多个重载版本，用于将不同类型的数据写入工作表。我们以其中一个版本为例：

public ExRange WriteData(List<ExColumn> data, ExCell source)
{
    // ... (代码略)
}

这个方法用于将列数据写入工作表。

• 接受一个ExColumn列表和一个起始单元格作为参数。
• 将数据转换为二维数组。
• 根据数据类型（文本或数字）设置单元格格式。
• 写入数据并返回写入的单元格范围。

英文说明：
This method writes column data to the worksheet.

• Takes a list of ExColumn and a starting cell as parameters.
• Converts data to 2D arrays.
• Sets cell formats based on data type (text or numeric).
• Writes the data and returns the range of cells written.

7. GetRange() 方法

public ExRange GetRange(ExCell start, ExCell extent)
{
    XL.Range rng = this.ComObj.Range[start.ToString(), extent.ToString()];
    return new ExRange(rng);
}

这个方法用于获取指定范围的单元格。

• 接受起始和结束单元格作为参数。
• 返回一个ExRange对象，表示指定的单元格范围。

英文说明：
This method gets a specified range of cells.

• Takes start and end cells as parameters.
• Returns an ExRange object representing the specified cell range.

8. GetUsedRange() 方法

public ExRange GetUsedRange()
{
    return new ExRange(this.ComObj.UsedRange);
}

这个方法返回工作表中已使用的单元格范围。

英文说明：
This method returns the range of cells that are currently in use in the worksheet.

9. AddPicture() 方法

public void AddPicture(string name, string fileName, double x, double y, double scale)
{
    // ... (代码略)
}

这个方法用于在工作表中添加图片。

• 接受图片名称、文件名、位置和缩放比例作为参数。
• 如果存在同名图片，先删除旧图片。
• 添加新图片并设置其属性。

英文说明：
This method adds a picture to the worksheet.

• Takes picture name, file name, position, and scale as parameters.
• Removes any existing picture with the same name.
• Adds the new picture and sets its properties.

这些方法共同构成了ExWorksheet类的核心功能，允许用户以编程方式操作Excel工作表。通过这些方法，可以实现数据写入、范围操作、图片插入等多种功能，为Excel自动化提供了强大的工具。

Code

public class ExWorksheet
{
    // ComObj 存储 Excel 工作表的 COM 对象
    public XL.Worksheet ComObj { get; private set; }
    // name 存储工作表的名称
    public string name { get; private set; }

    // 构造函数，初始化 ExWorksheet 对象
    public ExWorksheet(XL.Worksheet comObject)
    {
        this.SetSheet(comObject);
    }

    // 暂停屏幕更新，提高大量数据操作时的性能
    public void Freeze()
    {
        this.ComObj.Application.ScreenUpdating = false;
    }

    // 恢复屏幕更新，通常在完成数据操作后调用
    public void UnFreeze()
    {
        this.ComObj.Application.ScreenUpdating = true;
    }

    // 设置当前 ExWorksheet 对象的工作表
    public void SetSheet(XL.Worksheet comObject)
    {
        this.ComObj = comObject;
        this.name = comObject.Name;
    }

    // 激活当前工作表，使其成为活动工作表
    public void Activate()
    {
        this.ComObj.Activate();
    }

    // 设置工作表变化的监听器
    public void Listen(GH_Component component, bool activate)
    {
        // 移除现有的事件处理器，防止重复添加
        this.ComObj.Change -= (o) => { component.ExpireSolution(true); };
        // 如果 activate 为 true，添加新的事件处理器
        if(activate) this.ComObj.Change += (o) => { component.ExpireSolution(true); };
    }

    // 清除工作表的内容和格式
    public void ClearSheet()
    {
        ExRange range = this.GetUsedRange();
        range.ClearContent(); // 清除内容
        range.ClearFormat(); // 清除格式
    }

    // 将列数据写入工作表
    public ExRange WriteData(List<ExColumn> data, ExCell source)
    {
        // ... (此处省略具体实现，可以根据需要添加详细注释)
    }

    // 获取指定范围的单元格
    public ExRange GetRange(ExCell start, ExCell extent)
    {
        XL.Range rng = this.ComObj.Range[start.ToString(), extent.ToString()];
        return new ExRange(rng);
    }

    // 获取工作表中已使用的单元格范围
    public ExRange GetUsedRange()
    {
        return new ExRange(this.ComObj.UsedRange);
    }

    // 在工作表中添加图片
    public void AddPicture(string name, string fileName, double x, double y, double scale)
    {
        // 检查是否存在同名图片，如果存在则删除
        foreach (XL.Shape shape in this.ComObj.Shapes)
        {
            if (shape.Name == name)
            {
                shape.Delete();
                break;
            }
        }

        // 添加新图片
        XL.Shape pic = this.ComObj.Shapes.AddPicture(fileName, 
            Microsoft.Office.Core.MsoTriState.msoFalse, 
            Microsoft.Office.Core.MsoTriState.msoCTrue, 
            x, y, -1, -1);

        // 设置图片属性
        pic.Name = name;
        pic.ScaleWidth(scale, Microsoft.Office.Core.MsoTriState.msoTrue);
        pic.ScaleHeight(scale, Microsoft.Office.Core.MsoTriState.msoTrue);
    }
}

这段代码定义了一个 ExWorksheet 类，用于封装 Excel 工作表的操作。以下是每个方法的详细说明：

1. 构造函数：初始化 ExWorksheet 对象，设置工作表。

2. Freeze() 和 UnFreeze()：控制 Excel 的屏幕更新，用于优化性能。

3. SetSheet()：设置当前 ExWorksheet 对象的工作表，更新内部引用和名称。

4. Activate()：激活当前工作表，使其成为活动工作表。

5. Listen()：设置工作表变化的监听器，用于在 Grasshopper 中响应 Excel 的变化。

6. ClearSheet()：清除工作表的内容和格式。

7. WriteData()：将列数据写入工作表（具体实现未显示）。

8. GetRange()：获取指定范围的单元格。

9. GetUsedRange()：获取工作表中已使用的单元格范围。

10. AddPicture()：在工作表中添加图片，包括删除同名图片和设置新图片属性。

这个类提供了一系列方法来操作 Excel 工作表，包括基本的工作表管理、数据写入、范围操作和图片插入等功能。通过这些方法，可以实现对 Excel 的程序化控制，为自动化处理 Excel 文档提供了强大的工具。