【C#】【EXCEL】Bumblebee/Components/Analysis/GH_Ex_Ana_CondAverage.cs

Bumblebee/Components/Analysis/GH_Ex_Ana_CondAverage.cs

这段代码定义了一个名为 GH_Ex_Ana_CondAverage 的类，它是一个 Grasshopper 组件。这个组件的主要功能是为 Excel 工作表中的一个范围添加基于平均值的’条件格式’。以下是对这个组件的功能和特点的详细介绍：

1. 组件名称和描述：

   • 名称：Conditional Average（条件平均值）
   • 描述：基于值的平均值为 Excel 范围添加条件格式

2. 输入参数：

   • Worksheet（工作表）
   • Range（范围）
   • Type（条件类型）：定义如何应用条件格式（例如，高于平均值、低于平均值等）
   • Cell Color（单元格颜色）：用于高亮显示的颜色
   • Clear（清除）：是否清除现有的条件格式
   • Activate（激活）：是否应用新的条件格式

3. 输出：

   • 处理后的 Range 对象

4. 主要功能：

   • 获取指定的 Excel 工作表和范围
   • 根据用户输入的条件类型和颜色，为指定范围添加基于平均值的条件格式
   • 可以选择性地清除现有的条件格式
   • 只有在 Activate 参数为 true 时才执行操作

5. 特殊特性：

   • 使用枚举类型 AverageCondition 来定义不同的条件类型
   • 组件的暴露级别设置为次要（secondary）
   • 包含自定义图标

6. 集成性：

   • 这个组件是一个更大的系统（ Bumblebee）的一部分，专门用于在 Grasshopper 中处理 Excel 数据

总的来说，这个组件提供了一种在 Grasshopper 环境中直接操作 Excel 数据的方法，特别是添加基于平均值的条件格式。这对于需要在参数化设计过程中分析和可视化 Excel 数据的用户来说非常有用。它简化了 Excel 数据处理的流程，使用户能够直接在 Grasshopper 中完成通常需要在 Excel 中手动执行的操作。

这个流程图对应到代码中的主要步骤如下：

1. Start / 开始：对应构造函数 GH_Ex_Ana_CondAverage()
2. Initialize Component / 初始化组件：在构造函数中完成
3. Register Inputs / 注册输入参数：对应 RegisterInputParams 方法
4. Get Worksheet / 获取工作表：DA.GetData(0, ref gooS);
5. Get Range / 获取范围：DA.GetData(1, ref gooR);
6. Get Condition Type / 获取条件类型：DA.GetData(2, ref type);
7. Get Cell Color / 获取单元格颜色：DA.GetData(3, ref color);
8. Get Clear Flag / 获取清除标志：DA.GetData(4, ref clear);
9. Get Activate Flag / 获取激活标志：DA.GetData(5, ref activate);
10. Activate? / 是否激活?：if (activate)
11. Clear? / 是否清除?：if (clear)
12. ClearConditions / 清除条件：range.ClearConditions();
13. AddConditionalAverage / 添加条件平均值：range.AddConditionalAverage((AverageCondition)type, color);
14. Set Output / 设置输出：DA.SetData(0, range);
15. End / 结束：方法结束

这个流程图展示了组件的主要执行步骤，从初始化到获取输入参数，然后根据条件执行相应的操作，最后设置输出。表示了代码的逻辑流程，特别是条件判断和相应的操作。

Description

1. 构造函数

public GH_Ex_Ana_CondAverage()
  : base("Conditional Average", "Average",
      "Add conditional formatting to a Range based on the average of the values",
      Constants.ShortName, Constants.SubAnalysis)
{
}

这是组件的构造函数。它调用基类的构造函数，设置组件的名称、昵称、描述和分类。
// This is the constructor for the component. It calls the base class constructor to set the component’s name, nickname, description, and category.

2. Exposure 属性

public override GH_Exposure Exposure
{
    get { return GH_Exposure.secondary; }
}

这个属性设置组件在Grasshopper界面中的显示级别为次要。这意味着该组件不会在主菜单中直接显示，而是在子菜单中。
// This property sets the exposure level of the component in the Grasshopper interface to secondary. This means the component won’t be directly visible in the main menu, but in a submenu.

3. RegisterInputParams 方法

protected override void RegisterInputParams(GH_Component.GH_InputParamManager pManager)
{
    base.RegisterInputParams(pManager);
    pManager[1].Optional = true;
    pManager.AddIntegerParameter("Type", "T", "The condition type", GH_ParamAccess.item, 0);
    pManager[2].Optional = true;
    // ... (其他参数注册)
}

这个方法注册组件的输入参数。它首先调用基类的方法，然后添加额外的参数如条件类型、单元格颜色等。每个参数都有一个名称、简称、描述和默认值。
// This method registers the input parameters for the component. It first calls the base class method, then adds additional parameters such as condition type, cell color, etc. Each parameter has a name, nickname, description, and default value.

4. RegisterOutputParams 方法

protected override void RegisterOutputParams(GH_Component.GH_OutputParamManager pManager)
{
    base.RegisterOutputParams(pManager);
}

这个方法注册组件的输出参数。在这个例子中，它只是调用基类的方法，没有添加额外的输出。
// This method registers the output parameters for the component. In this case, it only calls the base class method without adding any additional outputs.

5. SolveInstance 方法

protected override void SolveInstance(IGH_DataAccess DA)
{
    // ... (获取输入数据)
    if (activate)
    {
        if (clear) range.ClearConditions();
        range.AddConditionalAverage((AverageCondition)type, color);
    }
    DA.SetData(0, range);
}

这是组件的核心方法，执行主要的逻辑。
// This is the core method of the component, executing the main logic.
它首先获取所有输入数据，然后根据条件执行操作：

1. 如果激活标志为真，它会：
   a. 如果清除标志为真，清除现有的条件格式
   b. 添加新的基于平均值的条件格式

2. 最后，它设置输出数据（处理后的范围对象）
   // It first retrieves all input data, then performs operations based on conditions:
   // 1. If the activate flag is true, it will:
   // a. Clear existing conditional formatting if the clear flag is true
   // b. Add new conditional formatting based on average
   // 2. Finally, it sets the output data (the processed range object)

3. Icon 属性

protected override System.Drawing.Bitmap Icon
{
    get
    {
        return Properties.Resources.BB_Cond_Average_01;
    }
}

这个属性返回组件的图标。它使用预定义的资源图片。
// This property returns the icon for the component. It uses a predefined resource image.

7. ComponentGuid 属性

public override Guid ComponentGuid
{
    get { return new Guid("b2854323-ef9f-470f-9f52-1d80fa90fb2a"); }
}

这个属性返回组件的唯一标识符。这个GUID在组件发布后不应更改，用于在Grasshopper中唯一标识这个组件。
// This property returns the unique identifier for the component. This GUID should not be changed after the component is released, as it’s used to uniquely identify this component in Grasshopper.

总结：
这个组件展示了如何创建一个自定义的Grasshopper组件，特别是用于Excel数据处理。它利用了面向对象编程的继承特性，重写了基类的多个方法来定制组件的行为。通过这种方式，它实现了在Grasshopper环境中直接操作Excel数据的功能，为用户提供了强大而灵活的数据处理工具。
// In summary, this component demonstrates how to create a custom Grasshopper component, especially for Excel data processing. It utilizes object-oriented programming inheritance features, overriding multiple base class methods to customize the component’s behavior. Through this approach, it implements functionality to directly manipulate Excel data within the Grasshopper environment, providing users with a powerful and flexible data processing tool.

Code

using Grasshopper.Kernel;
using Grasshopper.Kernel.Parameters;
using Grasshopper.Kernel.Types;
using Rhino.Geometry;
using System;
using System.Collections.Generic;
using Sd = System.Drawing;

namespace Bumblebee.Components
{
    // 定义一个条件平均值组件类，继承自基础范围组件
    public class GH_Ex_Ana_CondAverage : GH_Ex_Rng__Base
    {
        /// <summary>
        /// 初始化 GH_Ex_An_CondAverage 类的新实例。
        /// </summary>
        public GH_Ex_Ana_CondAverage()
          : base("Conditional Average", "Average",
              "Add conditional formatting to a Range based on the average of the values",
              Constants.ShortName, Constants.SubAnalysis)
        {
            // 构造函数调用基类构造函数，设置组件的名称、昵称、描述和分类
        }

        /// <summary>
        /// 设置组件的暴露级别。
        /// </summary>
        public override GH_Exposure Exposure
        {
            // 将组件设置为次要暴露级别，意味着它会在子菜单中显示
            get { return GH_Exposure.secondary; }
        }

        /// <summary>
        /// 注册此组件的所有输入参数。
        /// </summary>
        protected override void RegisterInputParams(GH_Component.GH_InputParamManager pManager)
        {
            // 调用基类方法注册基本输入参数
            base.RegisterInputParams(pManager);
            // 设置第二个参数（索引1）为可选
            pManager[1].Optional = true;
            // 添加整数参数用于条件类型
            pManager.AddIntegerParameter("Type", "T", "The condition type", GH_ParamAccess.item, 0);
            pManager[2].Optional = true;
            // 添加颜色参数用于单元格颜色
            pManager.AddColourParameter("Cell Color", "C", "The cell highlight color", GH_ParamAccess.item, Sd.Color.LightGray);
            pManager[3].Optional = true;
            // 添加布尔参数用于清除现有条件
            pManager.AddBooleanParameter("Clear", "_X", "If true, the existing conditions will be cleared", GH_ParamAccess.item, false);
            pManager[4].Optional = true;
            // 添加布尔参数用于激活条件
            pManager.AddBooleanParameter("Activate", "_A", "If true, the condition will be applied", GH_ParamAccess.item, false);
            pManager[5].Optional = true;

            // 为条件类型参数添加命名值
            Param_Integer paramA = (Param_Integer)pManager[2];
            foreach (AverageCondition value in Enum.GetValues(typeof(AverageCondition)))
            {
                paramA.AddNamedValue(value.ToString(), (int)value);
            }
        }

        /// <summary>
        /// 注册此组件的所有输出参数。
        /// </summary>
        protected override void RegisterOutputParams(GH_Component.GH_OutputParamManager pManager)
        {
            // 调用基类方法注册基本输出参数
            base.RegisterOutputParams(pManager);
        }

        /// <summary>
        /// 这是实际执行工作的方法。
        /// </summary>
        /// <param name="DA">DA 对象用于从输入检索数据和存储到输出。</param>
        protected override void SolveInstance(IGH_DataAccess DA)
        {
            // 获取工作表数据
            IGH_Goo gooS = null;
            DA.GetData(0, ref gooS);
            ExWorksheet worksheet = new ExWorksheet();
            bool hasWs = gooS.TryGetWorksheet(ref worksheet);

            // 获取范围数据
            IGH_Goo gooR = null;
            DA.GetData(1, ref gooR);
            ExRange range = new ExRange();
            if (!gooR.TryGetRange(ref range, worksheet)) return;
            if (!hasWs) worksheet = range.Worksheet;

            // 获取条件类型
            int type = 0;
            DA.GetData(2, ref type);

            // 获取单元格颜色
            Sd.Color color = Sd.Color.LightGray;
            DA.GetData(3, ref color);

            // 获取清除标志
            bool clear = false;
            DA.GetData(4, ref clear);

            // 获取激活标志
            bool activate = false;
            DA.GetData(5, ref activate);

            // 如果激活，执行条件格式操作
            if (activate)
            {
                // 如果需要清除，先清除现有条件
                if (clear) range.ClearConditions();
                // 添加新的条件平均值格式
                range.AddConditionalAverage((AverageCondition)type, color);
            }

            // 设置输出数据
            DA.SetData(0, range);
        }

        /// <summary>
        /// 提供组件的图标。
        /// </summary>
        protected override System.Drawing.Bitmap Icon
        {
            get
            {
                // 返回组件的图标
                return Properties.Resources.BB_Cond_Average_01;
            }
        }

        /// <summary>
        /// 获取此组件的唯一ID。发布后不要更改此ID。
        /// </summary>
        public override Guid ComponentGuid
        {
            // 返回组件的唯一标识符
            get { return new Guid("b2854323-ef9f-470f-9f52-1d80fa90fb2a"); }
        }
    }
}

这段代码现在包含了详细的中文注释，解释了每个方法和属性的功能。这些注释涵盖了以下几个方面：

1. 类的整体功能和继承关系
2. 构造函数的作用
3. 各个方法（如RegisterInputParams、SolveInstance等）的具体功能
4. 输入参数的设置和含义
5. 主要逻辑流程（在SolveInstance方法中）
6. 图标和GUID的设置及其重要性