# YellowJExcel

**Repository Path**: xiaoyi1314/yellow-jexcel

## Basic Information

- **Project Name**: YellowJExcel
- **Description**: 高性能 .NET Excel 读写库，兼容 MiniExcel 设计思想，支持灵活样式与列控制，适合大数据量高效导入导出。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-08-02
- **Last Updated**: 2025-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Excel, miniExcel, ClosedXML

## README

# YellowJExcel

> 高性能 .NET Excel 读写库，兼容 MiniExcel 设计思想，支持灵活样式与列控制，适合大数据量高效导入导出。

---

## 特性

- 🚀 **极致性能**：底层结合 MiniExcel（高性能流式读写）与 ClosedXML（灵活样式），兼顾速度与美观。
- 🧩 **简洁 API**：一行代码即可完成 Excel 的读写。
- 🎨 **丰富样式**：支持、列/行背景色、条件格式、隐藏列、列顺序等。
- 📄 **Sheet 操作**：支持多 Sheet 读写。
- 📝 **实体映射**：基于实体对象和 List 进行读写，类型安全。
- 🛠️ **灵活配置**：导出时可随意设置导出列、隐藏列、列顺序、列颜色、条件颜色等。
- 🏆 **对比优势**：兼容 MiniExcel 语法，样式能力更强。

---

## 安装

1. 安装 NuGet 包：

    ```shell
    dotnet add packageYellowJExcel
    ```

2. 引用命名空间：

    ```csharp
    using YellowJExcel;
    ```

---

## 快速开始

### 1. 定义实体类

```csharp
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
}
```

### 2. 读取 Excel 到 List

```csharp
var users = YellowJExcel.Read<User>("input.xlsx");
// 可指定 sheet 名
var usersSheet2 = YellowJExcel.Read<User>("input.xlsx", "Sheet2");
```

### 3. 导出 List 到 Excel（默认橘黄色表头）

```csharp
YellowJExcel.Write("output.xlsx", users);
```

### 3.1 导出 List 到 Excel（多个Sheet工作表）

```csharp
var data1 = new List<YourClass> { /* 数据1 */ };
var data2 = new List<YourClass> { /* 数据2 */ };

var config1 = new ExcelConfig<YourClass> { SheetName = "工作表1" };
var config2 = new ExcelConfig<YourClass> { SheetName = "工作表2" };

var sheets = new Dictionary<List<YourClass>, ExcelConfig<YourClass>>
{
    { data1, config1 },
    { data2, config2 }
};

YellowJExcel.Write("output.xlsx", sheets);
```
这个实现保持了原有的所有功能，同时支持多工作表写入，每个工作表可以有自己独立的配置。
### 4. 高级导出配置

```csharp
var config = new ExcelConfig<User>
{
    SheetName = "用户数据",
    ExcludedColumns = new HashSet<string> { "Email" }, // 不导出 Email 列
    HiddenColumns = new HashSet<string> { "Id" },      // 隐藏 Id 列
    ColumnOrder = new List<string> { "Name", "Age", "Id" }, // 自定义列顺序
    ColumnColors = new Dictionary<string, string>
    {
        ["Age"] = "#FFFACD" // Age 列背景色为柠檬黄
    },
    MergeColumns = new HashSet<string> { "Name" } // 自动合并 Name 列中重复的单元格
};
// 条件样式：未成年人行高亮
config.ConditionalRules.Add((u => u.Age < 18, "#FFB6C1")); // 粉色

YellowJExcel.Write("output.xlsx", users, config);
```



---
## 属性特性说明：继承MiniExcel支持 [ExcelColumnName] 属性自定义表头

- 你可以在实体属性上加 `[ExcelColumnName("自定义列名")]`，导出时表头会自动采用该名称，无需额外配置。
- 不影响 ExcludedColumns、HiddenColumns、ColumnOrder 等导出配置功能。

### 示例

```csharp
public class User
{
    public int Id { get; set; }
    [ExcelColumnName("姓名")]
    public string Name { get; set; }
    [ExcelColumnName("年龄")]
    public int Age { get; set; }
    public string Email { get; set; }
}
```
导出的表头将为：Id、姓名、年龄、Email

---
## API 说明

### YellowJExcel.Read<T>

```csharp
List<T> YellowJExcel.Read<T>(string filePath, string sheetName = null)
```
- **filePath**: Excel 文件路径
- **sheetName**: 工作表名（可选）
- **返回**: List<T> 实体对象列表

### YellowJExcel.Write<T>

```csharp
void YellowJExcel.Write<T>(string filePath, List<T> data, ExcelConfig<T> config = null)
```
- **filePath**: 输出文件路径
- **data**: 数据列表
- **config**: 导出配置（可选）

### ExcelConfig<T> 配置项

| 属性名           | 类型                          | 说明                         |
|------------------|------------------------------|------------------------------|
| SheetName        | string                       | 工作表名称                   |
| ExcludedColumns  | HashSet<string>              | 不导出的列名                 |
| HiddenColumns    | HashSet<string>              | 隐藏的列名                   |
| ColumnOrder      | List<string>                 | 列顺序                       |
| ColumnColors     | Dictionary<string, string>   | 列背景色（十六进制）         |
| ConditionalRules | List<(Func<T, bool>,string)> | 条件样式规则（行级）         |
| MergeColumns     | HashSet<string>              | 自动合并重复单元格的列名     |

---
## 常用颜色十六进制代码表

| 颜色名称   | 代码      | 预览 | 颜色名称   | 代码      | 预览 |
|------------|-----------|------|------------|-----------|------|
| 黑色       | #000000   | ⬛   | 白色       | #FFFFFF   | ⬜   |
| 红色       | #FF0000   | 🟥   | 绿色       | #00FF00   | 🟩   |
| 蓝色       | #0000FF   | 🟦   | 黄色       | #FFFF00   | 🟨   |
| 橙色       | #FFA500   | 🟧   | 紫色       | #800080   | 🟪   |
| 粉色       | #FFC0CB   | 🌸   | 棕色       | #A52A2A   | 🟫   |
| 灰色       | #808080   | ▫️   | 银色       | #C0C0C0   | ◽   |
| 金色       | #FFD700   | ⭐   | 柠檬黄     | #FFFACD   | 🟨   |
| 天蓝色     | #87CEEB   | 🟦   | 薄荷绿     | #98FF98   | 🟩   |
| 淡紫色     | #E6E6FA   | 🟪   | 浅灰色     | #D3D3D3   | ◽   |
| 米白色     | #F5F5F5   | ◻️   | 珊瑚红     | #FF7F50   | 🟥   |
| 淡青色     | #E0FFFF   | 🟦   | 浅粉色     | #FFB6C1   | 🌸   |
| 深红色     | #8B0000   | 🟥   | 深绿色     | #006400   | 🟩   |
| 深蓝色     | #00008B   | 🟦   | 深紫色     | #483D8B   | 🟪   |
| 玫瑰红     | #FF69B4   | 🌸   | 青色       | #00FFFF   | 🟦   |
| 橄榄绿     | #808000   | 🟩   | 褐色       | #8B4513   | 🟫   |
| 深灰色     | #404040   | ▪️   | 浅棕色     | #DEB887   | 🟫   |
| 海军蓝     | #000080   | 🟦   | 水鸭青     | #008080   | 🟦   |
| 茶色       | #D2691E   | 🟫   | 暗橙色     | #FF8C00   | 🟧   |
| 深紫罗兰   | #9400D3   | 🟪   | 草绿色     | #90EE90   | 🟩   |
| 石灰绿     | #32CD32   | 🟩   | 靛青色     | #4B0082   | 🟪   |

> 说明：预览仅供参考，实际颜色以 Excel/前端渲染为准。可将上述任意十六进制代码（如 `#FFA500`）用于 ExcelConfig 的颜色配置。

---
## 最新版本说明
		主要优化内容：
		1.	添加默认边框：
		•	为表头添加了边框
		•	为有数据的单元格添加了边框
		2.	修复合并列Bug：
		•	重新设计了合并逻辑，确保最后一行也能正确合并
		•	增加了对最后一行的特殊处理，确保连续相同的值能正确合并
		3.	完善中文注释：
		•	为所有方法、属性和关键代码段添加了详细中文注释
		•	注释中说明了功能、参数含义和使用方法
		•	对复杂的逻辑部分增加了注释说明

## 贡献与反馈

欢迎提交 Issue 或 PR 参与改进！  
如有建议或问题请联系作者。

---

## License

本项目遵循 MIT 协议，MiniExcel/ClosedXML 依赖遵循各自协议。
开源地址：[YellowJExcel](https://gitee.com/xiaoyi1314/yellow-jexcel)

---

特别感谢 [MiniExcel](https://github.com/shps951023/MiniExcel) 和 [ClosedXML](https://github.com/ClosedXML/ClosedXML) 项目为 .NET 社区带来的卓越 Excel 处理能力！