【C#】【EXCEL】BumblebeeComponentsAnalysisGH_Ex_Ana_CondTopPercent.cs

这段代码定义了一个名为 GH_Ex_Ana_CondTopPercent 的 Grasshopper 组件，其主要功能是为 Excel 工作表中的特定范围添加条件格式。具体来说，它允许用户基于数值的前N%来设置单元格的格式。以下是该组件的主要特点和功能：

1. 功能介绍：

   • 组件名称：Conditional Top Percent（条件性顶部百分比）
   • 简称：Top%
   • 描述：根据前N%的值为Excel范围添加条件格式

2. 主要输入参数：

   • 工作表和范围：指定要应用格式的Excel区域
   • 百分比：要高亮显示的值的百分比（默认为0.5，即50%）
   • 单元格颜色：高亮显示的颜色（默认为浅灰色）
   • 翻转选项：是否高亮显示底部百分比而非顶部
   • 清除选项：是否在应用新格式前清除现有条件
   • 激活选项：是否应用条件格式

3. 输出：

   • 经过条件格式处理的Excel范围

4. 工作流程：

   • 获取用户输入的参数
   • 检查是否需要激活条件格式
   • 如果激活，可能会先清除现有条件
   • 应用新的条件格式（基于顶部或底部百分比）
   • 输出处理后的范围

5. 使用场景：
   这个组件特别适用于需要快速识别和突出显示数据集中最高或最低一定比例值的情况。例如：

   • 在销售报表中突出显示前20%的高绩效产品
   • 在学生成绩单中标记前10%的优秀成绩
   • 在财务分析中凸显底部15%的低效投资

6. 特点：

   • 灵活性：用户可以自定义百分比、颜色和是否翻转
   • 可选的清除功能：允许用户在应用新格式前清除现有格式
   • 激活控制：用户可以控制是否实际应用格式，便于预览或临时禁用

总的来说，这个组件为Excel数据分析提供了一个强大而灵活的工具，使用户能够快速可视化数据集中的重要百分比段，从而更容易识别关键数据点和趋势。

Flow diagram

解释:

1. A: Start / 开始

   • 对应代码: 类的开始 public class GH_Ex_Ana_CondTopPercent : GH_Ex_Rng__Base

2. B: Initialize Component / 初始化组件

   • 对应代码: 构造函数 public GH_Ex_Ana_CondTopPercent()

3. C: Register Input Parameters / 注册输入参数

   • 对应代码: RegisterInputParams 方法

4. D: Register Output Parameters / 注册输出参数

   • 对应代码: RegisterOutputParams 方法

5. E: SolveInstance Method / SolveInstance 方法

   • 对应代码: protected override void SolveInstance(IGH_DataAccess DA)

6. F: Activate? / 是否激活?

   • 对应代码: if (activate)

7. G: Clear Existing Conditions / 清除现有条件

   • 对应代码: if (clear) range.ClearConditions();

8. H: Add Conditional Top Percent / 添加条件性顶部百分比

   • 对应代码: range.AddConditionalTopPercent(percent, color, flip);

9. I: Set Output Data / 设置输出数据

   • 对应代码: DA.SetData(0, range);

10. J: End / 结束

    • 对应代码: 方法结束

这个流程图展示了组件的主要执行步骤,从初始化到最终输出数据。它清晰地显示了条件格式应用的逻辑流程,包括激活检查和清除现有条件的选项。

Description

1. 构造函数

public GH_Ex_Ana_CondTopPercent()
  : base("Conditional Top Percent", "Top%",
      "Add conditional formatting to a Range based on the top percent",
      Constants.ShortName, Constants.SubAnalysis)
{
}

解释：

• 这是组件的构造函数。
• 它调用基类构造函数，传递组件的名称、简称、描述和分类信息。
• 英文注释：Initializes a new instance of the GH_Ex_An_CondTopPercent class.
• 中文注释：初始化 GH_Ex_An_CondTopPercent 类的新实例。

2. Exposure 属性

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

解释：

• 这个属性设置组件在Grasshopper界面中的显示级别。
• 将其设置为 secondary 表示它是次要组件，通常在子菜单中显示。
• 英文注释：Set Exposure level for the component.
• 中文注释：设置组件的暴露级别。

3. RegisterInputParams 方法

protected override void RegisterInputParams(GH_Component.GH_InputParamManager pManager)
{
    base.RegisterInputParams(pManager);
    pManager[1].Optional = true;
    pManager.AddNumberParameter("Percentage", "P", "The percentage of the values to highlight", GH_ParamAccess.item, 0.5);
    pManager.AddColourParameter("Cell Color", "C", "The cell highlight color", GH_ParamAccess.item, Sd.Color.LightGray);
    // ... 其他参数注册 ...
}

解释：

• 这个方法注册组件的所有输入参数。
• 它首先调用基类方法来注册基本参数。
• 然后添加特定于此组件的参数，如百分比、颜色、翻转选项等。
• 每个参数都有名称、简称、描述、访问类型和默认值。
• 英文注释：Registers all the input parameters for this component.
• 中文注释：注册此组件的所有输入参数。

4. RegisterOutputParams 方法

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

解释：

• 这个方法注册组件的输出参数。
• 在这个例子中，它只调用基类方法，可能是因为输出参数在基类中已经定义。
• 英文注释：Registers all the output parameters for this component.
• 中文注释：注册此组件的所有输出参数。

5. SolveInstance 方法

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

解释：

• 这是组件的核心方法，执行实际的工作。
• 它从输入参数中获取数据，执行条件格式化操作，并设置输出。
• 主要步骤包括：获取工作表和范围、获取格式化参数、应用条件格式（如果激活）。
• 英文注释：This is the method that actually does the work.
• 中文注释：这是实际执行工作的方法。

6. Icon 属性

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

解释：

• 这个属性提供组件在Grasshopper界面中显示的图标。
• 它返回一个预定义的位图资源。
• 英文注释：Provides an Icon for the component.
• 中文注释：为组件提供一个图标。

7. ComponentGuid 属性

public override Guid ComponentGuid
{
    get { return new Guid("36cddfee-89f8-46d9-acab-95bf5f139d6f"); }
}

解释：

• 这个属性返回组件的唯一标识符（GUID）。
• GUID用于在Grasshopper中唯一标识此组件。
• 英文注释：Gets the unique ID for this component. Do not change this ID after release.
• 中文注释：获取此组件的唯一ID。发布后请勿更改此ID。

这些方法和属性共同定义了 GH_Ex_Ana_CondTopPercent 组件的行为和外观。它们处理参数注册、数据处理、条件格式应用以及组件在Grasshopper界面中的表示。理解这些方法有助于掌握Grasshopper组件的开发流程和最佳实践。

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
{
    // 定义一个Grasshopper组件，用于在Excel范围内添加基于顶部百分比的条件格式
    public class GH_Ex_Ana_CondTopPercent : GH_Ex_Rng__Base
    {
        /// <summary>
        /// 初始化 GH_Ex_An_CondTopPercent 类的新实例。
        /// </summary>
        public GH_Ex_Ana_CondTopPercent()
          : base("Conditional Top Percent", "Top%",
              "Add conditional formatting to a Range based on the top percent",
              Constants.ShortName, Constants.SubAnalysis)
        {
        }

        /// <summary>
        /// 设置组件的暴露级别。
        /// 这里设置为secondary，表示它是一个次要组件。
        /// </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.AddNumberParameter("Percentage", "P", "要高亮显示的值的百分比", GH_ParamAccess.item, 0.5);
            // 添加单元格颜色参数
            pManager.AddColourParameter("Cell Color", "C", "单元格高亮颜色", GH_ParamAccess.item, Sd.Color.LightGray);
            // 添加翻转选项参数
            pManager.AddBooleanParameter("Flip", "F", "如果为true，将高亮显示底部百分比", GH_ParamAccess.item, false);
            // 添加清除选项参数
            pManager.AddBooleanParameter("Clear", "_X", "如果为true，将清除现有条件", GH_ParamAccess.item, false);
            // 添加激活选项参数
            pManager.AddBooleanParameter("Activate", "_A", "如果为true，将应用条件", GH_ParamAccess.item, false);
            // 设置第七个参数（索引6）为可选
            pManager[6].Optional = true;
        }

        /// <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;

            // 获取百分比参数
            double percent = 0.5;
            DA.GetData(2, ref percent);

            // 获取颜色参数
            Sd.Color color = Sd.Color.LightGray;
            DA.GetData(3, ref color);

            // 获取翻转选项
            bool flip = false;
            DA.GetData(4, ref flip);

            // 获取清除选项
            bool clear = false;
            DA.GetData(5, ref clear);

            // 获取激活选项
            bool activate = false;
            DA.GetData(6, ref activate);

            // 如果激活，执行条件格式化
            if (activate)
            {
                // 如果清除选项为true，清除现有条件
                if (clear) range.ClearConditions();
                // 添加基于顶部百分比的条件格式
                range.AddConditionalTopPercent(percent, color, flip);
            }

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

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

        /// <summary>
        /// 获取此组件的唯一ID。发布后请勿更改此ID。
        /// </summary>
        public override Guid ComponentGuid
        {
            get { return new Guid("36cddfee-89f8-46d9-acab-95bf5f139d6f"); }
        }
    }
}