装配明细表 · To Excel
将LK系统单元体装配明细数据写入Excel文件，支持多文件并行导出，内置模板引擎
📖 功能概述
该组件基于 EPPlus 5.3.1 库，将树形结构的装配明细数据写入Excel文件。核心能力：
- 内置模板（ZMB）：编译时嵌入的资源模板，新建文件时自动使用，包含预设的"装配明细表"工作表和格式。
- 多文件并行：树形数据的每个分支对应一个输出文件路径，一次触发同时写入多个文件。
- 智能类型转换：写入数据时自动识别数值类型（整数→保留整数，浮点数→保留小数，文本→保留文本），Excel中可直接参与公式计算。
- 自动目录创建：如果目标路径的目录不存在，自动创建。
- 文件存在处理：文件已存在时打开并覆盖写入（保留现有工作表结构），文件不存在时从模板新建。
⚠️ 注意：该组件没有输出参数。数据直接写入Excel文件，结果在文件系统中查看。
📥 输入参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 导出 | Boolean | 可选 | 触发信号。设为 True 执行Excel写入操作。也可使用组件内置按钮代替。默认为 False。 |
| 路径 | FilePath | 必填 | Excel导出的路径列表。每个路径需要完整文件路径并包含 .xlsx 拓展名。列表中的第 i 个路径对应树形数据的第 i 个分支。 |
| 数据 | Text | 必填 树形 | 以逗号分隔的明细数据，树形结构输入。每个分支写入对应的路径文件，每个分支内的每行字符串代表Excel中的一行数据。 |
🧠 核心算法详解
一、模板引擎与文件创建
组件在编译时内置了一个名为
新建文件：
当目标文件不存在时：
1 从内存中加载 ZMB 模板到
2 用模板流创建
3 写入数据到"装配明细表"工作表
4 调用
追加写入已存在文件：
当目标文件已存在时：
1 直接通过
2 在"装配明细表"工作表中写入数据
3 调用
Resources.ZMB 的资源文件，这是一个预先设计好格式的Excel模板。其行为如下：新建文件：
当目标文件不存在时：
1 从内存中加载 ZMB 模板到
MemoryStream2 用模板流创建
ExcelPackage（此时包中包含工作表和预设格式）3 写入数据到"装配明细表"工作表
4 调用
package.SaveAs(fi) 将内存中的包保存到目标路径追加写入已存在文件：
当目标文件已存在时：
1 直接通过
new ExcelPackage(fi) 加载现有文件2 在"装配明细表"工作表中写入数据
3 调用
package.Save() 覆盖保存
二、数据写入引擎
WriteDataToSheet 方法将平面字符串列表写入Excel工作表的指定区域：输入格式：每行字符串以逗号分隔各列值。例如：
"A01,1200,铝合金,2.5,8×M6"表示一行5列的数据。
写入流程：
1 统计总行数 = data.Count
2 统计最大列数 = 所有行中逗号分隔后最多段的数量
3 构建二维 object 数组
[rowCount, colCount]4 逐行解析：对每个单元格调用
ConvertToTypedValue• 尝试 int.TryParse → 转换为整数
• 尝试 double.TryParse → 转换为浮点数
• 都不成功 → 保留原字符串
5 批量写入到从 (rowStart=2, colStart=1) 即 A2 单元格开始的目标范围
批量写入的意义：使用二维数组批量赋值（而非逐单元格写入），大幅提升了写入性能，尤其适合数百行数据的大文件。
三、路径与分支的对应关系
组件接受树形数据输入（GH_ParamAccess.tree），路径参数为列表（自动展平 Flatten）。
对应规则：
路径列表索引 0 → 树形数据分支 0 → 写入 路径[0] 文件
路径列表索引 1 → 树形数据分支 1 → 写入 路径[1] 文件
...以此类推
数量校验（关键）：路径数量必须等于树形分支数量。不匹配时立即报错并终止，避免数据错位。
对应规则：
路径列表索引 0 → 树形数据分支 0 → 写入 路径[0] 文件
路径列表索引 1 → 树形数据分支 1 → 写入 路径[1] 文件
...以此类推
数量校验（关键）：路径数量必须等于树形分支数量。不匹配时立即报错并终止，避免数据错位。
⚙️ 完整执行流程
1. 参数获取：读取触发布尔、文件路径列表、树形数据。
2. 参数校验：
• 路径列表非空
• 树形数据非空
• 路径数量 == 分支数量（否则报错并终止）
3. 触发判断：布尔输入为 True 或内置按钮按下才执行。
4. 多文件循环写入：对每个路径+分支对：
• 跳过空路径或空分支（给出警告）
• 分支中的
• 调用 WriteToExcel → 确保目录存在 → 模板/文件加载 → 写入数据 → 保存
• 成功输出Remark提示，失败输出Error提示（含异常信息）
5. 所有文件处理完成后自动结束（无输出参数）。
2. 参数校验：
• 路径列表非空
• 树形数据非空
• 路径数量 == 分支数量（否则报错并终止）
3. 触发判断：布尔输入为 True 或内置按钮按下才执行。
4. 多文件循环写入：对每个路径+分支对：
• 跳过空路径或空分支（给出警告）
• 分支中的
GH_String 转换为 string 列表• 调用 WriteToExcel → 确保目录存在 → 模板/文件加载 → 写入数据 → 保存
• 成功输出Remark提示，失败输出Error提示（含异常信息）
5. 所有文件处理完成后自动结束（无输出参数）。
🧪 典型使用场景
| 场景 | 详细说明 |
|---|---|
| 单元体装配明细导出 | 将Grasshopper中计算的装配明细数据（构件清单、数量、材质、尺寸等）导出为Excel，用于工厂加工或项目归档。 |
| 多单元体批量导出 | 树形数据的每个分支对应一个单元体，每个分支写入对应的Excel文件。一次触发同时输出所有单元体的明细表，非常适合多单元体的大项目。 |
| 数据复查与补充 | 文件已存在时打开并覆盖数据区域，保留模板格式。可以先导出一次在Excel中手工补充信息，然后重新运行组件更新数据。 |
⚠️ 注意事项
- 路径数量必须等于树形分支数量：这是最常见的错误。请确保路径列表中的每个路径都与树形数据的每个分支一一对应。
- 数据分隔符：数据以逗号（,）分隔各列。如果数据本身包含逗号，需要事先转义或替换分隔符。
- 类型自动识别：
- 纯数字字符串 → 转为整数或浮点数存入Excel（可在Excel中参与计算）
- 非数字字符串 → 以文本形式存入
- 工作表名称固定：写入的目标工作表名称为
装配明细表。如果文件中不存在该名称的工作表，写入可能会失败。 - 起始写入位置：数据从 A2 单元格开始写入（第2行第1列）。第1行通常保留给模板的列标题。
- 覆盖写入：写入时会覆盖目标范围内原有的数据。如果旧数据行数多于新数据，多出的行不会被自动清除。
- EPPlus许可证：组件静默设置为 NonCommercial 许可证。
📋 组件信息
| 名称 | 装配明细表 |
| 英文名 | To Excel |
| 分类 | LK → Util |
| Exposure | secondary（二级显示） |
| 显示文本 | Action（按钮文本） |
| 基类 | BoolButtonComponent |
| 文件 | LK_ZPB.cs |
| GUID | {E9750616-50F7-46E4-8015-9BA9985454D6} |