EPPlus 7.1 新特性：运行时动态设置列格式

EPPlus 7.1 新特性：运行时动态设置列格式

概述

EPPlus 7.1 版本引入了一项重要的新功能：在调用 LoadFromCollection 方法时，可以在运行时动态设置列的格式。这一功能特别适用于需要根据不同文化或业务规则动态调整数据格式的场景。

核心功能

新版本通过引入 IExcelNumberFormatProvider 接口实现了这一功能。该接口定义了一个简单但强大的方法，允许开发者在运行时根据自定义逻辑返回不同的数字格式字符串。

接口定义

public interface IExcelNumberFormatProvider
{
    string GetFormat(int numberFormatId);
}

使用方式

基本实现示例

开发者可以创建一个实现 IExcelNumberFormatProvider 接口的类，定义自己的格式逻辑：

public class MyNumberFormatProvider : IExcelNumberFormatProvider
{
    public const int CurrencyFormat = 1;

    public string GetFormat(int numberFormatId)
    {
        return numberFormatId switch
        {
            CurrencyFormat => "#,##0.00\\ \"kr\"",
            _ => string.Empty
        };
    }
}

通过特性使用

如果实现类有无参构造函数，可以通过 EpplusTable 和 EpplusTableColumn 特性直接使用：

[EpplusTable(NumberFormatProviderType = typeof(MyNumberFormatProvider))]
public class EmployeeData
{
    [EpplusTableColumn(Header = "姓名")]
    public string Name { get; set; }

    [EpplusTableColumn(Header = "薪资", NumberFormatId = MyNumberFormatProvider.CurrencyFormat)]
    public decimal Salary { get; set; }
}

通过代码配置使用

对于需要构造函数参数的场景，可以直接在代码中配置：

_sheet.Cells["A1"].LoadFromCollection(items, options =>
{
    options.PrintHeaders = true;
    options.SetNumberFormatProvider(new MyNumberFormatProvider(arg1, arg2));
});

技术实现细节

1. 格式解析流程：

   • 当设置 NumberFormatId 属性时，EPPlus 会调用注册的 IExcelNumberFormatProvider
   • 获取返回的格式字符串
   • 将该格式应用到整个数据列

2. 默认行为：

   • 如果没有设置 NumberFormatId，则保持原有格式不变
   • 如果 GetFormat 返回空字符串，则不会应用任何格式

应用场景

这一功能特别适用于以下场景：

1. 多语言/多地区支持：根据不同地区文化显示不同的货币符号、日期格式等
2. 动态业务规则：根据业务规则动态调整数据显示格式
3. 用户自定义格式：允许最终用户自定义数据显示格式

最佳实践

1. 格式ID管理：建议使用常量或枚举来管理各种格式ID，避免魔法数字
2. 性能考虑：对于大量数据的处理，确保格式提供逻辑高效
3. 错误处理：在自定义格式提供器中加入适当的错误处理逻辑

总结

EPPlus 7.1 引入的动态列格式设置功能为开发者提供了更大的灵活性，使得数据展示可以根据运行时条件动态调整。这一改进特别适合需要国际化支持或复杂业务规则的应用场景，进一步增强了 EPPlus 作为 .NET 平台下优秀 Excel 处理库的能力。