VassasCo.Utility.ExcelMapper 2.0.0

VassasCo.Utility.ExcelMapper

原生对象到 Excel/CSV 的映射引擎（桌面端/服务端通用，无需 COM/VSTO）。
支持 侵入式特性 与 非侵入式 Fluent 两套并行配置方式，覆盖导出、导入、分页、异步、条件格式、大数据流式等场景。

目录

• 功能总览
• 目标框架与依赖
• 快速开始
• 侵入式：特性配置
• 非侵入式：Fluent 配置
• 嵌套对象与集合
• 分页
• 异步导出（取消 / 进度）
• 条件格式
• CSV 导出
• 字典导出
• Excel / CSV 导入
• 引擎选择
• 安全策略
• 配置参考
• API 速查
• 异常类型

功能总览

目标框架与依赖

DataAnnotations（[DisplayName]/[Display]/[DataType]）通过反射全名识别，无硬依赖，已有特性自动生效。

快速开始

using VassasCo.Utility;

// 一行导出（配置全部来自实体特性/约定）
ExcelMapper.SaveToFile(people, "report.xlsx");

// Fluent 配置导出
ExcelMapper.Build(people)
    .WithSheetName("员工表")
    .WithStyle(s => s.HeaderBackgroundColor = "#2E75B6")
    .ToFile("report.xlsx");

// 导入
var result = ExcelMapper.Import<Person>("report.xlsx");
foreach (var p in result.Items) Console.WriteLine(p.Name);
foreach (var err in result.Errors) Console.WriteLine(err);

侵入式：特性配置

在实体类上贴特性，调用方零配置：

[ExcelSheet(Name = "员工表", PageSize = 1000, AutoFilter = true)]
public class Person
{
    [ExcelColumn(Name = "编号", Order = 1, Width = 10)]
    public int Id { get; set; }

    [ExcelColumn(Name = "姓名", Order = 2, Width = 15)]
    public string Name { get; set; } = "";

    // 身份证号强制文本，防止科学计数法丢精度
    [ExcelColumn(Name = "身份证号", ForceText = true, Width = 22)]
    public string IdCard { get; set; } = "";

    [ExcelColumn(Name = "入职日期", Format = "yyyy-MM-dd")]
    public DateTime HireDate { get; set; }

    [ExcelColumn(Name = "绩效", Order = 3, Format = "N2")]
    [ConditionalFormat(ConditionOperator.GreaterThan, 90, FillColor = "#00B050", Bold = true)]
    [ConditionalFormat(ConditionOperator.LessThan, 60, FontColor = "#FF0000")]
    public double Score { get; set; }

    [ExcelIgnore]
    public string InternalNote { get; set; } = "";

    // byte[] 默认输出 Base64
    public byte[]? Avatar { get; set; }
}

// 导出
ExcelMapper.SaveToFile(people, "employees.xlsx");

可用特性

配置优先级

Fluent EntityMap > 本包特性 > DataAnnotations 约定 > 属性名

非侵入式：Fluent 配置

不修改业务类，在外部用 Lambda 声明映射：

var map = new EntityMap<Person>()
    .Property(p => p.Id).HasName("编号").Order(1).Width(10)
    .Property(p => p.Name).HasName("姓名").Order(2).Width(15)
    .Property(p => p.IdCard).HasName("身份证号").AsText().Width(22)
    .Property(p => p.HireDate).Format("yyyy-MM-dd")
    .Property(p => p.Score).HasName("绩效").Format("N2")
        .Rule(ConditionOperator.GreaterThan, 90, s => s.Fill("#00B050").Bold())
        .Rule(ConditionOperator.LessThan, 60, s => s.Font("#FF0000"))
    .Ignore(p => p.InternalNote);

ExcelMapper.Build(people)
    .WithMap(map)
    .ToFile("employees.xlsx");

支持嵌套属性路径：

.Property(p => p.Department.Manager.Name).HasName("部门经理")

注意：上面的写法只改了叶子 Name 的标题；中间节点 Department、Manager 作为分组表头，默认显示属性名。要自定义分组表头，需分别对中间节点命名（或用 [ExcelDisplay] 特性）：

.Property(p => p.Department).HasName("部门")                // 分组表头
.Property(p => p.Department.Manager).HasName("经理")        // 分组表头
.Property(p => p.Department.Manager.Name).HasName("部门经理"); // 叶子

生成表头：部门 → 经理 → 部门经理。同理 .Ignore(p => p.Department) 会忽略整个子树。

PropertyMapping 链式方法

行级规则

var map = new EntityMap<Order>()
    .WhenRow(o => o.IsOverdue, s => s.Font("#FF0000").Bold())
    .WhenRow(o => o.Amount > 10000, s => s.Fill("#FFF2CC"));

行级规则始终服务端求值，写为静态样式。

嵌套对象与集合

嵌套对象自动递归展开，生成多层合并表头：

public class Person
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public Department? Department { get; set; }   // 嵌套 → 合并表头
    public List<Address> Addresses { get; set; }   // 集合
}

public class Department
{
    public string DeptName { get; set; } = "";
    public Person? Manager { get; set; }  // 循环引用 → 自动标记"(循环引用)"
}

生成的表头：

| Id | Name | Department         | Addresses           |
|    |      | DeptName | Manager | (→ 子 Sheet "Addresses") |

集合渲染模式（ArrayRender）

Json 模式把整个集合写进单个单元格，不产生子 Sheet/多行，适合 List<string>/List<int> 等简单集合或需要整行紧凑展示的场景；复杂对象集合的 JSON 可能超过单元格 32767 字符上限而被截断。

分页

// 方式一：选项配置
ExcelMapper.Build(people)
    .WithOptions(o =>
    {
        o.PageSize = 5000;               // 每页 5000 行
        o.PageMode = PageMode.MultipleSheets; // 多 Sheet（默认）
    })
    .ToFile("report.xlsx");
// → Sheet: Person, Person_2, Person_3 ...

// 方式二：特性配置
[ExcelSheet(PageSize = 5000)]

// 多文件分页
ExcelMapper.Build(people)
    .WithOptions(o =>
    {
        o.PageSize = 5000;
        o.PageMode = PageMode.MultipleFiles; // 每页一个文件
    })
    .ToFile("report.xlsx");
// → report_1.xlsx, report_2.xlsx, report_3.xlsx ...

异步导出（取消 / 进度）

面向桌面端，不阻塞 UI：

using var cts = new CancellationTokenSource();
var progress = new Progress<int>(rows => {
    Dispatcher.Invoke(() => ProgressBar.Value = rows);
});

await ExcelMapper.SaveToFileAsync(people, "report.xlsx", cts.Token, progress);

// 取消
cts.Cancel();

所有导出方法均有异步重载：SaveToFileAsync / SaveToStreamAsync / WriteCsvAsync / DictionaryToFileAsync。

导出诊断信息

所有 Excel 导出方法返回 ExportResult，桌面端可据此展示结果：

var result = ExcelMapper.SaveToFile(people, "report.xlsx");

Console.WriteLine($"导出 {result.RowCount} 条记录，共 {result.SheetCount} 个工作表");
Console.WriteLine($"引擎：{result.Engine}，耗时 {result.Elapsed.TotalSeconds:F2} 秒");
Console.WriteLine($"文件数：{result.FileCount}");

条件格式

侵入式

[ConditionalFormat(ConditionOperator.GreaterThan, 90, FillColor = "#00B050", Bold = true)]
[ConditionalFormat(ConditionOperator.Between, 60, 90, FontColor = "#FFC000")]
[ConditionalFormat(ConditionOperator.LessThan, 60, FontColor = "#FF0000")]
public double Score { get; set; }

非侵入式

.Property(p => p.Score)
    .Rule(ConditionOperator.GreaterThan, 90, s => s.Fill("#00B050").Bold())
    .Rule(ConditionOperator.LessThan, 60, s => s.Font("#FF0000"))

运算符

GreaterThan / GreaterOrEqual / LessThan / LessOrEqual / Equal / NotEqual / Contains / Between

简单规则（除 Contains 外）默认翻译为 Excel 原生条件格式（PreferNativeConditionalFormat=true），可在应用端动态变色。流式引擎或关闭此选项时改为服务端求值写入静态样式。

CSV 导出

// 快速导出
ExcelMapper.WriteCsv(people, "report.csv");

// 配置选项
ExcelMapper.BuildCsv(people)
    .Configure(o =>
    {
        o.Delimiter = ';';              // 欧洲格式
        o.UseUtf8Bom = true;            // Excel 打开中文不乱码
        o.FormulaInjectionGuard = true; // 公式注入防护
        o.QuoteAllFields = false;       // 仅必要时加引号
    })
    .ToFile("report.csv");

// 异步
await ExcelMapper.WriteCsvAsync(people, "report.csv", cts.Token, progress);

CSV 导出复用侵入式特性 / 非侵入式 EntityMap<T> 的列配置。集合属性在 CSV 中无法表达，对应列输出空字符串。

字典导出

动态 IDictionary 无需实体类：

var dict = new Dictionary<string, object>
{
    ["报告标题"] = "2024年销售统计",
    ["生成时间"] = DateTime.Now,
    ["总金额"] = 123456.78
};

// 键 ≤16 → 宽表（键作列头，单行值）
ExcelMapper.DictionaryToFile(dict, "summary.xlsx");

// 键 >16 → 竖表（Key/Value 两列）

Excel / CSV 导入

// 按扩展名自动选择
var result = ExcelMapper.Import<Person>("data.xlsx");

// 指定 Sheet
var r2 = ExcelMapper.ImportFromExcel<Person>("data.xlsx", sheetName: "员工表");

// CSV 导入（可指定分隔符）
var r3 = ExcelMapper.ImportFromCsv<Person>("data.csv", delimiter: ',');

// 从流导入
var r4 = ExcelMapper.ImportFromExcel<Person>(stream);

// 使用非侵入式映射绑定列名
var map = new EntityMap<Person>()
    .Property(p => p.Name).HasName("姓名");
var r5 = ExcelMapper.Import("data.xlsx", map);

导入结果

public class ImportResult<T>
{
    public List<T> Items { get; }      // 成功导入的实体
    public List<ImportError> Errors { get; }  // 逐字段错误
    public bool HasErrors { get; }
}

// 错误不阻断整批导入，便于桌面端展示给用户修正
foreach (var err in result.Errors)
    Console.WriteLine(err); // "第 5 行 [Score]：无法转为 Double（原始值：N/A）"

支持的转换

string / char / bool（1/true/yes/是）/ 枚举（数值/名称/Description）/ DateTime（11 种格式）/ DateTimeOffset / TimeSpan / Guid / byte[]（Base64）/ 各数值类型（不丢精度）/ 可空类型 / 集合（JSON 反序列化，与 ArrayRender.Json 往返）。

引擎选择

// 自动选择（默认）：行数 ≥ StreamingThreshold 时切换流式
ExcelMapper.Build(people)
    .WithOptions(o => o.StreamingThreshold = 100000)
    .ToFile("large.xlsx");

// 强制流式
ExcelMapper.Build(people)
    .WithOptions(o => o.Engine = ExportEngineKind.OpenXmlStreaming)
    .ToFile("large.xlsx");

安全策略

配置参考

ExcelStyle（视觉）

ExcelExportOptions（行为）

CsvExportOptions

API 速查

ExcelMapper（静态门面）

ExcelMapperBuilder<T>

异常类型

try
{
    ExcelMapper.SaveToFile(people, "report.xlsx");
}
catch (ExcelPlanValidationException ex)
{
    foreach (var err in ex.Errors)
        Console.WriteLine(err);
}
catch (ExcelFileAccessException ex)
{
    Console.WriteLine($"文件访问失败：{ex.Message}");
}

测试

cd VassasCo.Utility
dotnet test

40 个单元测试覆盖：敏感字段文本、长数字精度、布尔/枚举/byte[] 渲染、嵌套表头、集合子 Sheet、循环引用、分页（多 Sheet / 多文件 / 空数据）、条件格式、异步进度、CSV 安全、导入类型转换与错误收集等场景。

许可证

MIT