mirror of
https://gitee.com/dotnetchina/MiniExcel.git
synced 2024-12-02 03:47:41 +08:00
1125 lines
31 KiB
Markdown
1125 lines
31 KiB
Markdown
<div align="center">
|
||
<p><a href="https://www.nuget.org/packages/MiniExcel"><img src="https://img.shields.io/nuget/v/MiniExcel.svg" alt="NuGet"></a> <a href="https://www.nuget.org/packages/MiniExcel"><img src="https://img.shields.io/nuget/dt/MiniExcel.svg" alt=""></a> <a href="https://ci.appveyor.com/project/shps951023/miniexcel/branch/master"><img src="https://ci.appveyor.com/api/projects/status/b2vustrwsuqx45f4/branch/master?svg=true" alt="Build status"></a></p>
|
||
</div>
|
||
|
||
<div align="center">
|
||
<p><strong><a href="README.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.zh-Hant.md">繁體中文</a></strong></p>
|
||
</div>
|
||
|
||
<div align="center">
|
||
<p>🙌 您的 <a href="https://github.com/shps951023/MiniExcel">Github Star</a> ，能帮助 MiniExcel 让更多人看到 🙌</p>
|
||
</div>
|
||
|
||
<div align="center">
|
||
<p><a href="https://qm.qq.com/cgi-bin/qm/qr?k=3OkxuL14sXhJsUimWK8wx_Hf28Wl49QE&jump_from=webapi">813100564(MiniExcel QQ交流群)</a> </p>
|
||
</div>
|
||
|
||
|
||
---
|
||
|
||
### 简介
|
||
|
||
MiniExcel简单、高效避免OOM的.NET处理Excel查、写、填充数据工具。
|
||
|
||
|
||
目前主流框架大多需要将数据全载入到内存方便操作，但这会导致内存消耗问题，MiniExcel 尝试以 Stream 角度写底层算法逻辑，能让原本1000多MB占用降低到几MB，避免内存不够情况。
|
||
|
||
|
||
|
||
### 特点
|
||
- 低内存耗用，避免OOM(out of memoery)、频繁 Full GC 情况
|
||
- 支持`即时`操作每行数据
|
||
|
||
- 兼具搭配 LINQ 延迟查询特性，能办到低消耗、快速分页等复杂查询
|
||
- 轻量，不需要安装 Microsoft Office、COM+、不依赖任何套件，DLL小于100KB
|
||
- 简便操作的 API 风格
|
||
|
||
|
||
|
||
### 快速开始
|
||
|
||
- [读 Excel](#getstart1)
|
||
- [写 Excel](#getstart2)
|
||
- [模板填充 Excel](#getstart3)
|
||
- [Excel Column Name/Index/Ignore Attribute](#getstart4)
|
||
- [例子](#getstart5)
|
||
|
||
### 安装
|
||
|
||
请查看 [NuGet](https://www.nuget.org/packages/MiniExcel)
|
||
|
||
### 更新日志
|
||
|
||
请查看 [Release Notes](docs)
|
||
|
||
### TODO
|
||
|
||
请查看 [TODO](https://github.com/shps951023/MiniExcel/projects/1?fullscreen=true)
|
||
|
||
### 性能测试
|
||
|
||
以 [**Test1,000,000x10.xlsx**](benchmarks/MiniExcel.Benchmarks/Test1%2C000%2C000x10.xlsx) 做基准与主流框架做性能测试，总共 1千万笔 "HelloWorld"，文件大小 23 MB
|
||
|
||
Benchmarks 逻辑可以在 [MiniExcel.Benchmarks](benchmarks/MiniExcel.Benchmarks/Program.cs) 查看或是提交 PR，运行指令
|
||
|
||
```
|
||
dotnet run -p .\benchmarks\MiniExcel.Benchmarks\ -c Release -f netcoreapp3.1 -- -f * --join
|
||
```
|
||
|
||
最后一次运行结果 :
|
||
|
||
```
|
||
BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042
|
||
Intel Core i7-7700 CPU 3.60GHz (Kaby Lake), 1 CPU, 8 logical and 4 physical cores
|
||
[Host] : .NET Framework 4.8 (4.8.4341.0), X64 RyuJIT
|
||
Job-ZYYABG : .NET Framework 4.8 (4.8.4341.0), X64 RyuJIT
|
||
IterationCount=3 LaunchCount=3 WarmupCount=3
|
||
```
|
||
|
||
| Method | 最大内存耗用 | 平均时间 | Gen 0 | Gen 1 | Gen 2 |
|
||
| ---------------------------- | -------------: | ---------------: | -----------: | ----------: | ---------: |
|
||
| 'MiniExcel QueryFirst' | 0.109 MB | 726.4 us | - | - | - |
|
||
| 'ExcelDataReader QueryFirst' | 15.24 MB | 10,664,238.2 us | 566000.0000 | 1000.0000 | - |
|
||
| 'MiniExcel Query' | 17.3 MB | 14,179,334.8 us | 367000.0000 | 96000.0000 | 7000.0000 |
|
||
| 'ExcelDataReader Query' | 17.3 MB | 22,565,088.7 us | 1210000.0000 | 2000.0000 | - |
|
||
| 'Epplus QueryFirst' | 1,452 MB | 18,198,015.4 us | 535000.0000 | 132000.0000 | 9000.0000 |
|
||
| 'Epplus Query' | 1,451 MB | 23,647,471.1 us | 1451000.0000 | 133000.0000 | 9000.0000 |
|
||
| 'OpenXmlSDK Query' | 1,412 MB | 52,003,270.1 us | 978000.0000 | 353000.0000 | 11000.0000 |
|
||
| 'OpenXmlSDK QueryFirst' | 1,413 MB | 52,348,659.1 us | 978000.0000 | 353000.0000 | 11000.0000 |
|
||
| 'ClosedXml QueryFirst' | 2,158 MB | 66,188,979.6 us | 2156000.0000 | 575000.0000 | 9000.0000 |
|
||
| 'ClosedXml Query' | 2,184 MB | 191,434,126.6 us | 2165000.0000 | 577000.0000 | 10000.0000 |
|
||
|
||
|
||
| Method | 最大内存耗用 | 平均时间 | Gen 0 | Gen 1 | Gen 2 |
|
||
| ------------------------ | -------------: | ---------------: | -----------: | -----------: | ---------: |
|
||
| 'MiniExcel Create Xlsx' | 15 MB | 11,531,819.8 us | 1020000.0000 | - | - |
|
||
| 'Epplus Create Xlsx' | 1,204 MB | 22,509,717.7 us | 1370000.0000 | 60000.0000 | 30000.0000 |
|
||
| 'OpenXmlSdk Create Xlsx' | 2,621 MB | 42,473,998.9 us | 1370000.0000 | 460000.0000 | 50000.0000 |
|
||
| 'ClosedXml Create Xlsx' | 7,141 MB | 140,939,928.6 us | 5520000.0000 | 1500000.0000 | 80000.0000 |
|
||
|
||
|
||
|
||
### 读 Excel <a name="getstart1"></a>
|
||
|
||
|
||
|
||
#### 1. Query 查询 Excel 返回`强型别` IEnumerable 数据 [[Try it]](https://dotnetfiddle.net/w5WD1J)
|
||
|
||
```csharp
|
||
public class UserAccount
|
||
{
|
||
public Guid ID { get; set; }
|
||
public string Name { get; set; }
|
||
public DateTime BoD { get; set; }
|
||
public int Age { get; set; }
|
||
public bool VIP { get; set; }
|
||
public decimal Points { get; set; }
|
||
}
|
||
|
||
var rows = MiniExcel.Query<UserAccount>(path);
|
||
|
||
// or
|
||
|
||
using (var stream = File.OpenRead(path))
|
||
var rows = stream.Query<UserAccount>();
|
||
```
|
||
|
||
|
||
|
||
|
||
#### 2. Query 查询 Excel 返回`Dynamic` IEnumerable 数据 [[Try it]](https://dotnetfiddle.net/w5WD1J)
|
||
|
||
* Key 系统预设为 `A,B,C,D...Z`
|
||
|
||
| MiniExcel | 1 |
|
||
| -------- | -------- |
|
||
| Github | 2 |
|
||
|
||
```csharp
|
||
|
||
var rows = MiniExcel.Query(path).ToList();
|
||
|
||
// or
|
||
using (var stream = File.OpenRead(path))
|
||
{
|
||
var rows = stream.Query().ToList();
|
||
|
||
Assert.Equal("MiniExcel", rows[0].A);
|
||
Assert.Equal(1, rows[0].B);
|
||
Assert.Equal("Github", rows[1].A);
|
||
Assert.Equal(2, rows[1].B);
|
||
}
|
||
```
|
||
|
||
#### 3. 查询数据以第一行数据当Key [[Try it]](https://dotnetfiddle.net/w5WD1J)
|
||
|
||
注意 : 同名以右边数据为准
|
||
|
||
Input Excel :
|
||
|
||
| Column1 | Column2 |
|
||
| -------- | -------- |
|
||
| MiniExcel | 1 |
|
||
| Github | 2 |
|
||
|
||
|
||
```csharp
|
||
|
||
var rows = MiniExcel.Query(useHeaderRow:true).ToList();
|
||
|
||
// or
|
||
|
||
using (var stream = File.OpenRead(path))
|
||
{
|
||
var rows = stream.Query(useHeaderRow:true).ToList();
|
||
|
||
Assert.Equal("MiniExcel", rows[0].Column1);
|
||
Assert.Equal(1, rows[0].Column2);
|
||
Assert.Equal("Github", rows[1].Column1);
|
||
Assert.Equal(2, rows[1].Column2);
|
||
}
|
||
```
|
||
|
||
#### 4. Query 查询支援延迟加载(Deferred Execution)，能配合LINQ First/Take/Skip办到低消耗、高效率复杂查询
|
||
|
||
举例 : 查询第一笔数据
|
||
|
||
```csharp
|
||
var row = MiniExcel.Query(path).First();
|
||
Assert.Equal("HelloWorld", row.A);
|
||
|
||
// or
|
||
|
||
using (var stream = File.OpenRead(path))
|
||
{
|
||
var row = stream.Query().First();
|
||
Assert.Equal("HelloWorld", row.A);
|
||
}
|
||
```
|
||
|
||
与其他框架效率比较 :
|
||
|
||
|
||
|
||
#### 5. 查询指定 Sheet 名称
|
||
|
||
```csharp
|
||
MiniExcel.Query(path, sheetName: "SheetName");
|
||
//or
|
||
stream.Query(sheetName: "SheetName");
|
||
```
|
||
|
||
#### 6. 查询所有 Sheet 名称跟数据
|
||
|
||
```csharp
|
||
var sheetNames = MiniExcel.GetSheetNames(path);
|
||
foreach (var sheetName in sheetNames)
|
||
{
|
||
var rows = MiniExcel.Query(path, sheetName: sheetName);
|
||
}
|
||
```
|
||
|
||
#### 7. 查询所有栏(列)
|
||
|
||
```csharp
|
||
var columns = MiniExcel.GetColumns(path); // e.g result : ["A","B"...]
|
||
|
||
var cnt = columns.Count; // get column count
|
||
```
|
||
|
||
#### 8. Dynamic Query 转成 `IDictionary<string,object>` 数据
|
||
|
||
```csharp
|
||
foreach(IDictionary<string,object> row in MiniExcel.Query(path))
|
||
{
|
||
//..
|
||
}
|
||
|
||
// or
|
||
var rows = MiniExcel.Query(path).Cast<IDictionary<string,object>>();
|
||
```
|
||
|
||
#### 9. Query 读 Excel 返回 DataTable
|
||
|
||
提醒 : 不建议使用，因为DataTable会将数据`全载入内存`，失去MiniExcel低内存消耗功能。
|
||
|
||
```C#
|
||
var table = MiniExcel.QueryAsDataTable(path, useHeaderRow: true);
|
||
```
|
||
|
||
|
||
|
||
#### 10. 指定单元格开始读取数据
|
||
|
||
```csharp
|
||
MiniExcel.Query(path,useHeaderRow:true,startCell:"B3")
|
||
```
|
||
|
||
|
||
|
||
#### 11. 合并的单元格填充
|
||
|
||
注意 : 效率相对于`没有使用合并填充`来说差
|
||
底层原因 : OpenXml 标准将 mergeCells 放在文件最下方，导致需要遍历两次 sheetxml
|
||
|
||
```csharp
|
||
var config = new OpenXmlConfiguration()
|
||
{
|
||
FillMergedCells = true
|
||
};
|
||
var rows = MiniExcel.Query(path, configuration: config);
|
||
```
|
||
|
||
|
||
|
||
|
||
支持不固定长宽多行列填充
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
### 写 Excel <a name="getstart2"></a>
|
||
|
||
1. 必须是非abstract 类别有公开无参数构造函数
|
||
2. MiniExcel SaveAs 支援 `IEnumerable参数延迟查询`，除非必要请不要使用 ToList 等方法读取全部数据到内存
|
||
|
||
图片 : 是否呼叫 ToList 的内存差别
|
||
|
||
#### 1. Anonymous or strongly type [[Try it]](https://dotnetfiddle.net/w5WD1J)
|
||
|
||
```csharp
|
||
var path = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid()}.xlsx");
|
||
MiniExcel.SaveAs(path, new[] {
|
||
new { Column1 = "MiniExcel", Column2 = 1 },
|
||
new { Column1 = "Github", Column2 = 2}
|
||
});
|
||
```
|
||
|
||
#### 2. Datatable
|
||
|
||
- 优先使用 Caption 当栏位名称
|
||
|
||
```csharp
|
||
var path = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid()}.xlsx");
|
||
var table = new DataTable();
|
||
{
|
||
table.Columns.Add("Column1", typeof(string));
|
||
table.Columns.Add("Column2", typeof(decimal));
|
||
table.Rows.Add("MiniExcel", 1);
|
||
table.Rows.Add("Github", 2);
|
||
}
|
||
|
||
MiniExcel.SaveAs(path, table);
|
||
```
|
||
|
||
#### 3. Dapper
|
||
|
||
```csharp
|
||
using (var connection = GetConnection(connectionString))
|
||
{
|
||
var rows = connection.Query(@"select 'MiniExcel' as Column1,1 as Column2 union all select 'Github',2");
|
||
MiniExcel.SaveAs(path, rows);
|
||
}
|
||
```
|
||
|
||
#### 4. `IEnumerable<IDictionary<string, object>>`
|
||
|
||
```csharp
|
||
var values = new List<Dictionary<string, object>>()
|
||
{
|
||
new Dictionary<string,object>{{ "Column1", "MiniExcel" }, { "Column2", 1 } },
|
||
new Dictionary<string,object>{{ "Column1", "Github" }, { "Column2", 2 } }
|
||
};
|
||
MiniExcel.SaveAs(path, values);
|
||
```
|
||
|
||
output :
|
||
|
||
| Column1 | Column2 |
|
||
| -------- | -------- |
|
||
| MiniExcel | 1 |
|
||
| Github | 2 |
|
||
|
||
#### 5. SaveAs 支持 Stream，生成文件不落地 [[Try it]](https://dotnetfiddle.net/JOen0e)
|
||
|
||
```csharp
|
||
using (var stream = new MemoryStream()) //支持 FileStream,MemoryStream..等
|
||
{
|
||
stream.SaveAs(values);
|
||
}
|
||
```
|
||
|
||
像是 API 导出 Excel
|
||
|
||
```csharp
|
||
public IActionResult DownloadExcel()
|
||
{
|
||
var values = new[] {
|
||
new { Column1 = "MiniExcel", Column2 = 1 },
|
||
new { Column1 = "Github", Column2 = 2}
|
||
};
|
||
|
||
var memoryStream = new MemoryStream();
|
||
memoryStream.SaveAs(values);
|
||
memoryStream.Seek(0, SeekOrigin.Begin);
|
||
return new FileStreamResult(memoryStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
|
||
{
|
||
FileDownloadName = "demo.xlsx"
|
||
};
|
||
}
|
||
```
|
||
|
||
|
||
|
||
#### 6. 支持 IDataReader 参数
|
||
|
||
```csharp
|
||
MiniExcel.SaveAs(path, reader);
|
||
```
|
||
|
||
|
||
|
||
#### 7. 创建多个工作表(Sheet)
|
||
|
||
```csharp
|
||
// 1. Dictionary<string,object>
|
||
var users = new[] { new { Name = "Jack", Age = 25 }, new { Name = "Mike", Age = 44 } };
|
||
var department = new[] { new { ID = "01", Name = "HR" }, new { ID = "02", Name = "IT" } };
|
||
var sheets = new Dictionary<string, object>
|
||
{
|
||
["users"] = users,
|
||
["department"] = department
|
||
};
|
||
MiniExcel.SaveAs(path, sheets);
|
||
|
||
// 2. DataSet
|
||
var sheets = new DataSet();
|
||
sheets.Add(UsersDataTable);
|
||
sheets.Add(DepartmentDataTable);
|
||
//..
|
||
MiniExcel.SaveAs(path, sheets);
|
||
```
|
||
|
||
|
||
|
||
#### 8. 表格样式选择
|
||
|
||
从v0.15.0版本开始预设样式改为
|
||
|
||
|
||
|
||
不需要样式
|
||
|
||
```csharp
|
||
var config = new OpenXmlConfiguration()
|
||
{
|
||
TableStyles = TableStyles.None
|
||
};
|
||
MiniExcel.SaveAs(path, value,configuration:config);
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
### 模板填充 Excel <a name="getstart3"></a>
|
||
|
||
- 宣告方式类似 Vue 模板 `{{变量名称}}`, 或是集合渲染 `{{集合名称.栏位名称}}`
|
||
- 集合渲染支持 IEnumerable/DataTable/DapperRow
|
||
|
||
#### 1. 基本填充
|
||
|
||
模板:
|
||
|
||
|
||
最终效果:
|
||
|
||
|
||
代码:
|
||
```csharp
|
||
// 1. By POCO
|
||
var value = new
|
||
{
|
||
Name = "Jack",
|
||
CreateDate = new DateTime(2021, 01, 01),
|
||
VIP = true,
|
||
Points = 123
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
|
||
|
||
// 2. By Dictionary
|
||
var value = new Dictionary<string, object>()
|
||
{
|
||
["Name"] = "Jack",
|
||
["CreateDate"] = new DateTime(2021, 01, 01),
|
||
["VIP"] = true,
|
||
["Points"] = 123
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
```
|
||
|
||
|
||
|
||
#### 2. IEnumerable 数据填充
|
||
|
||
> Note1: 同行从左往右以第一个 IEnumerableUse 当列表来源 (不支持同列多集合)
|
||
|
||
模板:
|
||
|
||
|
||
最终效果:
|
||
|
||
|
||
代码:
|
||
|
||
```csharp
|
||
//1. By POCO
|
||
var value = new
|
||
{
|
||
employees = new[] {
|
||
new {name="Jack",department="HR"},
|
||
new {name="Lisa",department="HR"},
|
||
new {name="John",department="HR"},
|
||
new {name="Mike",department="IT"},
|
||
new {name="Neo",department="IT"},
|
||
new {name="Loan",department="IT"}
|
||
}
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
|
||
//2. By Dictionary
|
||
var value = new Dictionary<string, object>()
|
||
{
|
||
["employees"] = new[] {
|
||
new {name="Jack",department="HR"},
|
||
new {name="Lisa",department="HR"},
|
||
new {name="John",department="HR"},
|
||
new {name="Mike",department="IT"},
|
||
new {name="Neo",department="IT"},
|
||
new {name="Loan",department="IT"}
|
||
}
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
```
|
||
|
||
|
||
|
||
#### 3. 复杂数据填充
|
||
|
||
> Note: 支持多 sheet 填充,并共用同一组参数
|
||
|
||
模板:
|
||
|
||
|
||
|
||
最终效果:
|
||
|
||
|
||
|
||
代码:
|
||
|
||
```csharp
|
||
// 1. By POCO
|
||
var value = new
|
||
{
|
||
title = "FooCompany",
|
||
managers = new[] {
|
||
new {name="Jack",department="HR"},
|
||
new {name="Loan",department="IT"}
|
||
},
|
||
employees = new[] {
|
||
new {name="Wade",department="HR"},
|
||
new {name="Felix",department="HR"},
|
||
new {name="Eric",department="IT"},
|
||
new {name="Keaton",department="IT"}
|
||
}
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
|
||
// 2. By Dictionary
|
||
var value = new Dictionary<string, object>()
|
||
{
|
||
["title"] = "FooCompany",
|
||
["managers"] = new[] {
|
||
new {name="Jack",department="HR"},
|
||
new {name="Loan",department="IT"}
|
||
},
|
||
["employees"] = new[] {
|
||
new {name="Wade",department="HR"},
|
||
new {name="Felix",department="HR"},
|
||
new {name="Eric",department="IT"},
|
||
new {name="Keaton",department="IT"}
|
||
}
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
```
|
||
|
||
#### 4. 大数据填充效率比较
|
||
|
||
> NOTE: 在 MiniExcel 使用 IEnumerable 延迟 ( 不ToList ) 可以节省内存使用
|
||
|
||
|
||
|
||
#### 5. Cell 值自动类别对应
|
||
|
||
模板
|
||
|
||
|
||
|
||
最终效果
|
||
|
||
|
||
|
||
类别
|
||
|
||
```csharp
|
||
public class Poco
|
||
{
|
||
public string @string { get; set; }
|
||
public int? @int { get; set; }
|
||
public decimal? @decimal { get; set; }
|
||
public double? @double { get; set; }
|
||
public DateTime? datetime { get; set; }
|
||
public bool? @bool { get; set; }
|
||
public Guid? Guid { get; set; }
|
||
}
|
||
```
|
||
|
||
代码
|
||
|
||
```csharp
|
||
var poco = new TestIEnumerableTypePoco { @string = "string", @int = 123, @decimal = decimal.Parse("123.45"), @double = (double)123.33, @datetime = new DateTime(2021, 4, 1), @bool = true, @Guid = Guid.NewGuid() };
|
||
var value = new
|
||
{
|
||
Ts = new[] {
|
||
poco,
|
||
new TestIEnumerableTypePoco{},
|
||
null,
|
||
poco
|
||
}
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
```
|
||
|
||
|
||
|
||
#### 6. Example : 列出 Github 专案
|
||
|
||
模板
|
||
|
||
|
||
|
||
|
||
最终效果
|
||
|
||
|
||
|
||
代码
|
||
|
||
```csharp
|
||
var projects = new[]
|
||
{
|
||
new {Name = "MiniExcel",Link="https://github.com/shps951023/MiniExcel",Star=146, CreateTime=new DateTime(2021,03,01)},
|
||
new {Name = "HtmlTableHelper",Link="https://github.com/shps951023/HtmlTableHelper",Star=16, CreateTime=new DateTime(2020,02,01)},
|
||
new {Name = "PocoClassGenerator",Link="https://github.com/shps951023/PocoClassGenerator",Star=16, CreateTime=new DateTime(2019,03,17)}
|
||
};
|
||
var value = new
|
||
{
|
||
User = "ITWeiHan",
|
||
Projects = projects,
|
||
TotalStar = projects.Sum(s => s.Star)
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
```
|
||
|
||
|
||
|
||
#### 7. DataTable 当参数
|
||
|
||
```csharp
|
||
var managers = new DataTable();
|
||
{
|
||
managers.Columns.Add("name");
|
||
managers.Columns.Add("department");
|
||
managers.Rows.Add("Jack", "HR");
|
||
managers.Rows.Add("Loan", "IT");
|
||
}
|
||
var value = new Dictionary<string, object>()
|
||
{
|
||
["title"] = "FooCompany",
|
||
["managers"] = managers,
|
||
};
|
||
MiniExcel.SaveAsByTemplate(path, templatePath, value);
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
### Excel 列属性 (Excel Column Attribute) <a name="getstart4"></a>
|
||
|
||
|
||
|
||
#### 1. 指定列名称、指定第几列、是否忽略该列
|
||
|
||
Excel例子
|
||
|
||
|
||
|
||
|
||
代码
|
||
```csharp
|
||
public class ExcelAttributeDemo
|
||
{
|
||
[ExcelColumnName("Column1")]
|
||
public string Test1 { get; set; }
|
||
[ExcelColumnName("Column2")]
|
||
public string Test2 { get; set; }
|
||
[ExcelIgnore]
|
||
public string Test3 { get; set; }
|
||
[ExcelColumnIndex("I")] // 系统会自动转换"I"为第8列
|
||
public string Test4 { get; set; }
|
||
public string Test5 { get; } //系统会忽略此列
|
||
public string Test6 { get; private set; } //set非公开,系统会忽略
|
||
[ExcelColumnIndex(3)] // 从0开始索引
|
||
public string Test7 { get; set; }
|
||
}
|
||
|
||
var rows = MiniExcel.Query<ExcelAttributeDemo>(path).ToList();
|
||
Assert.Equal("Column1", rows[0].Test1);
|
||
Assert.Equal("Column2", rows[0].Test2);
|
||
Assert.Null(rows[0].Test3);
|
||
Assert.Equal("Test7", rows[0].Test4);
|
||
Assert.Null(rows[0].Test5);
|
||
Assert.Null(rows[0].Test6);
|
||
Assert.Equal("Test4", rows[0].Test7);
|
||
```
|
||
|
||
#### 2. 自定义日期格式 (ExcelFormatAttribute)
|
||
|
||
类别
|
||
|
||
```csharp
|
||
public class Dto
|
||
{
|
||
public string Name { get; set; }
|
||
|
||
[ExcelFormat("MMMM dd, yyyy")]
|
||
public DateTime InDate { get; set; }
|
||
}
|
||
```
|
||
|
||
代码
|
||
|
||
```csharp
|
||
var value = new Dto[] {
|
||
new Issue241Dto{ Name="Jack",InDate=new DateTime(2021,01,04)},
|
||
new Issue241Dto{ Name="Henry",InDate=new DateTime(2020,04,05)},
|
||
};
|
||
MiniExcel.SaveAs(path, value);
|
||
```
|
||
|
||
效果
|
||
|
||
|
||
|
||
Query 支持自定义格式转换
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
### Excel 类别自动判断 <a name="getstart5"></a>
|
||
|
||
- MiniExcel 预设会根据`文件扩展名`判断是 xlsx 还是 csv，但会有失准时候，请自行指定。
|
||
- Stream 类别无法判断来源于哪种 excel 请自行指定
|
||
|
||
```csharp
|
||
stream.SaveAs(excelType:ExcelType.CSV);
|
||
//or
|
||
stream.SaveAs(excelType:ExcelType.XLSX);
|
||
//or
|
||
stream.Query(excelType:ExcelType.CSV);
|
||
//or
|
||
stream.Query(excelType:ExcelType.XLSX);
|
||
```
|
||
|
||
|
||
|
||
### 例子
|
||
|
||
#### 1. SQLite & Dapper 读取大数据新增到数据库
|
||
|
||
note : 请不要呼叫 call ToList/ToArray 等方法，这会将所有数据读到内存内
|
||
|
||
```csharp
|
||
using (var connection = new SQLiteConnection(connectionString))
|
||
{
|
||
connection.Open();
|
||
using (var transaction = connection.BeginTransaction())
|
||
using (var stream = File.OpenRead(path))
|
||
{
|
||
var rows = stream.Query();
|
||
foreach (var row in rows)
|
||
connection.Execute("insert into T (A,B) values (@A,@B)", new { row.A, row.B }, transaction: transaction);
|
||
transaction.Commit();
|
||
}
|
||
}
|
||
```
|
||
|
||
效能:
|
||
|
||
|
||
|
||
#### 2. ASP.NET Core 3.1 下载/上传 Excel Xlsx API Demo [Try it](tests/MiniExcel.Tests.AspNetCore)
|
||
|
||
```csharp
|
||
public class ApiController : Controller
|
||
{
|
||
public IActionResult Index()
|
||
{
|
||
return new ContentResult
|
||
{
|
||
ContentType = "text/html",
|
||
StatusCode = (int)HttpStatusCode.OK,
|
||
Content = @"<html><body>
|
||
<a href='api/DownloadExcel'>DownloadExcel</a><br>
|
||
<a href='api/DownloadExcelFromTemplatePath'>DownloadExcelFromTemplatePath</a><br>
|
||
<a href='api/DownloadExcelFromTemplateBytes'>DownloadExcelFromTemplateBytes</a><br>
|
||
<p>Upload Excel</p>
|
||
<form method='post' enctype='multipart/form-data' action='/api/uploadexcel'>
|
||
<input type='file' name='excel'> <br>
|
||
<input type='submit' >
|
||
</form>
|
||
</body></html>"
|
||
};
|
||
}
|
||
|
||
public IActionResult DownloadExcel()
|
||
{
|
||
var values = new[] {
|
||
new { Column1 = "MiniExcel", Column2 = 1 },
|
||
new { Column1 = "Github", Column2 = 2}
|
||
};
|
||
var memoryStream = new MemoryStream();
|
||
memoryStream.SaveAs(values);
|
||
memoryStream.Seek(0, SeekOrigin.Begin);
|
||
return new FileStreamResult(memoryStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
|
||
{
|
||
FileDownloadName = "demo.xlsx"
|
||
};
|
||
}
|
||
|
||
public IActionResult DownloadExcelFromTemplatePath()
|
||
{
|
||
string templatePath = "TestTemplateComplex.xlsx";
|
||
|
||
Dictionary<string, object> value = new Dictionary<string, object>()
|
||
{
|
||
["title"] = "FooCompany",
|
||
["managers"] = new[] {
|
||
new {name="Jack",department="HR"},
|
||
new {name="Loan",department="IT"}
|
||
},
|
||
["employees"] = new[] {
|
||
new {name="Wade",department="HR"},
|
||
new {name="Felix",department="HR"},
|
||
new {name="Eric",department="IT"},
|
||
new {name="Keaton",department="IT"}
|
||
}
|
||
};
|
||
|
||
MemoryStream memoryStream = new MemoryStream();
|
||
memoryStream.SaveAsByTemplate(templatePath, value);
|
||
memoryStream.Seek(0, SeekOrigin.Begin);
|
||
return new FileStreamResult(memoryStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
|
||
{
|
||
FileDownloadName = "demo.xlsx"
|
||
};
|
||
}
|
||
|
||
private static Dictionary<string, Byte[]> TemplateBytesCache = new Dictionary<string, byte[]>();
|
||
|
||
static ApiController()
|
||
{
|
||
string templatePath = "TestTemplateComplex.xlsx";
|
||
byte[] bytes = System.IO.File.ReadAllBytes(templatePath);
|
||
TemplateBytesCache.Add(templatePath, bytes);
|
||
}
|
||
|
||
public IActionResult DownloadExcelFromTemplateBytes()
|
||
{
|
||
byte[] bytes = TemplateBytesCache["TestTemplateComplex.xlsx"];
|
||
|
||
Dictionary<string, object> value = new Dictionary<string, object>()
|
||
{
|
||
["title"] = "FooCompany",
|
||
["managers"] = new[] {
|
||
new {name="Jack",department="HR"},
|
||
new {name="Loan",department="IT"}
|
||
},
|
||
["employees"] = new[] {
|
||
new {name="Wade",department="HR"},
|
||
new {name="Felix",department="HR"},
|
||
new {name="Eric",department="IT"},
|
||
new {name="Keaton",department="IT"}
|
||
}
|
||
};
|
||
|
||
MemoryStream memoryStream = new MemoryStream();
|
||
memoryStream.SaveAsByTemplate(bytes, value);
|
||
memoryStream.Seek(0, SeekOrigin.Begin);
|
||
return new FileStreamResult(memoryStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
|
||
{
|
||
FileDownloadName = "demo.xlsx"
|
||
};
|
||
}
|
||
|
||
public IActionResult UploadExcel(IFormFile excel)
|
||
{
|
||
var stream = new MemoryStream();
|
||
excel.CopyTo(stream);
|
||
|
||
foreach (var item in stream.Query(true))
|
||
{
|
||
// do your logic etc.
|
||
}
|
||
|
||
return Ok("File uploaded successfully");
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3. 分页查询
|
||
|
||
```csharp
|
||
void Main()
|
||
{
|
||
var rows = MiniExcel.Query(path);
|
||
|
||
Console.WriteLine("==== No.1 Page ====");
|
||
Console.WriteLine(Page(rows,pageSize:3,page:1));
|
||
Console.WriteLine("==== No.50 Page ====");
|
||
Console.WriteLine(Page(rows,pageSize:3,page:50));
|
||
Console.WriteLine("==== No.5000 Page ====");
|
||
Console.WriteLine(Page(rows,pageSize:3,page:5000));
|
||
}
|
||
|
||
public static IEnumerable<T> Page<T>(IEnumerable<T> en, int pageSize, int page)
|
||
{
|
||
return en.Skip(page * pageSize).Take(pageSize);
|
||
}
|
||
```
|
||
|
||
|
||
|
||
#### 4. WebForm不落地导出Excel
|
||
|
||
```csharp
|
||
var fileName = "Demo.xlsx";
|
||
var sheetName = "Sheet1";
|
||
HttpResponse response = HttpContext.Current.Response;
|
||
response.Clear();
|
||
response.ContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
|
||
response.AddHeader("Content-Disposition", $"attachment;filename=\"{fileName}\"");
|
||
var values = new[] {
|
||
new { Column1 = "MiniExcel", Column2 = 1 },
|
||
new { Column1 = "Github", Column2 = 2}
|
||
};
|
||
var memoryStream = new MemoryStream();
|
||
memoryStream.SaveAs(values, sheetName: sheetName);
|
||
memoryStream.Seek(0, SeekOrigin.Begin);
|
||
memoryStream.CopyTo(Response.OutputStream);
|
||
response.End();
|
||
```
|
||
|
||
|
||
|
||
#### 5. 动态 i18n 多国语言跟权限管理
|
||
|
||
像例子一样，建立一个方法处理 i18n 跟权限管理，并搭配 `yield return 返回 IEnumerable<Dictionary<string, object>>`，即可达到动态、低内存处理效果
|
||
|
||
```csharp
|
||
void Main()
|
||
{
|
||
var value = new Order[] {
|
||
new Order(){OrderNo = "SO01",CustomerID="C001",ProductID="P001",Qty=100,Amt=500},
|
||
new Order(){OrderNo = "SO02",CustomerID="C002",ProductID="P002",Qty=300,Amt=400},
|
||
};
|
||
|
||
Console.WriteLine("en-Us and Sales role");
|
||
{
|
||
var path = Path.GetTempPath() + Guid.NewGuid() + ".xlsx";
|
||
var lang = "en-US";
|
||
var role = "Sales";
|
||
MiniExcel.SaveAs(path, GetOrders(lang, role, value));
|
||
MiniExcel.Query(path, true).Dump();
|
||
}
|
||
|
||
Console.WriteLine("zh-CN and PMC role");
|
||
{
|
||
var path = Path.GetTempPath() + Guid.NewGuid() + ".xlsx";
|
||
var lang = "zh-CN";
|
||
var role = "PMC";
|
||
MiniExcel.SaveAs(path, GetOrders(lang, role, value));
|
||
MiniExcel.Query(path, true).Dump();
|
||
}
|
||
}
|
||
|
||
private IEnumerable<Dictionary<string, object>> GetOrders(string lang, string role, Order[] orders)
|
||
{
|
||
foreach (var order in orders)
|
||
{
|
||
var newOrder = new Dictionary<string, object>();
|
||
|
||
if (lang == "zh-CN")
|
||
{
|
||
newOrder.Add("客户编号", order.CustomerID);
|
||
newOrder.Add("订单编号", order.OrderNo);
|
||
newOrder.Add("产品编号", order.ProductID);
|
||
newOrder.Add("数量", order.Qty);
|
||
if (role == "Sales")
|
||
newOrder.Add("价格", order.Amt);
|
||
yield return newOrder;
|
||
}
|
||
else if (lang == "en-US")
|
||
{
|
||
newOrder.Add("Customer ID", order.CustomerID);
|
||
newOrder.Add("Order No", order.OrderNo);
|
||
newOrder.Add("Product ID", order.ProductID);
|
||
newOrder.Add("Quantity", order.Qty);
|
||
if (role == "Sales")
|
||
newOrder.Add("Amount", order.Amt);
|
||
yield return newOrder;
|
||
}
|
||
else
|
||
{
|
||
throw new InvalidDataException($"lang {lang} wrong");
|
||
}
|
||
}
|
||
}
|
||
|
||
public class Order
|
||
{
|
||
public string OrderNo { get; set; }
|
||
public string CustomerID { get; set; }
|
||
public decimal Qty { get; set; }
|
||
public string ProductID { get; set; }
|
||
public decimal Amt { get; set; }
|
||
}
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
### FAQ 常见问题
|
||
|
||
#### Q: Excel 表头标题名称跟 class 属性名称不一致，如何对应?
|
||
|
||
A. 请使用 ExcelColumnName 作 mapping
|
||
|
||
|
||
|
||
#### Q. 多工作表(sheet)如何导出/查询数据?
|
||
|
||
A. 使用 `GetSheetNames `方法搭配 Query 的 sheetName 参数
|
||
|
||
|
||
|
||
```csharp
|
||
var sheets = MiniExcel.GetSheetNames(path);
|
||
foreach (var sheet in sheets)
|
||
{
|
||
Console.WriteLine($"sheet name : {sheet} ");
|
||
var rows = MiniExcel.Query(path,useHeaderRow:true,sheetName:sheet);
|
||
Console.WriteLine(rows);
|
||
}
|
||
```
|
||
|
||
|
||
|
||
#### Q. 查询如何映射枚举(enum)?
|
||
|
||
A. 名称一样，系统会自动映射(注意:大小写不敏感)
|
||
|
||
|
||
|
||
|
||
|
||
#### Q. 是否使用 Count 会载入全部数据到内存
|
||
|
||
不会，图片测试一百万行*十列数据，简单测试，内存最大使用 < 60MB，花费13.65秒
|
||
|
||
|
||
|
||
|
||
|
||
#### Q. Query如何使用整数索引取值?
|
||
|
||
Query 预设索引为字串Key : A,B,C....，想要改为数字索引，请建立以下方法自行转换
|
||
|
||
```csharp
|
||
void Main()
|
||
{
|
||
var path = @"D:\git\MiniExcel\samples\xlsx\TestTypeMapping.xlsx";
|
||
var rows = MiniExcel.Query(path,true);
|
||
foreach (var r in ConvertToIntIndexRows(rows))
|
||
{
|
||
Console.Write($"column 0 : {r[0]} ,column 1 : {r[1]}");
|
||
Console.WriteLine();
|
||
}
|
||
}
|
||
|
||
private IEnumerable<Dictionary<int, object>> ConvertToIntIndexRows(IEnumerable<object> rows)
|
||
{
|
||
ICollection<string> keys = null;
|
||
var isFirst = true;
|
||
foreach (IDictionary<string,object> r in rows)
|
||
{
|
||
if(isFirst)
|
||
{
|
||
keys = r.Keys;
|
||
isFirst = false;
|
||
}
|
||
|
||
var dic = new Dictionary<int, object>();
|
||
var index = 0;
|
||
foreach (var key in keys)
|
||
dic[index++] = r[key];
|
||
yield return dic;
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
### 局限与警告
|
||
|
||
- 目前不支援 xls (97-2003) 或是加密文件
|
||
- xlsm 只支持查询
|
||
|
||
|
||
|
||
### 参考
|
||
- 读取逻辑 : [ExcelDataReader](https://github.com/ExcelDataReader/ExcelDataReader) / [ClosedXML](https://github.com/ClosedXML/ClosedXML)
|
||
- API 设计方式 : [StackExchange/Dapper](https://github.com/StackExchange/Dapper)
|
||
|
||
### Contributors
|
||
|
||
 |