Chsword.Excel2Object 2.7.0

Excel2Object

Excel 与 .NET 对象互相转换 / Excel convert to .NET Object and vice versa.

English | 中文

• Top
  • 安装 NuGet
  • 发布说明和路线图
  • 示例代码
  • 文档
  • 开发和发布
  • 贡献者
  • 参考

平台支持

安装 NuGet

PM> Install-Package Chsword.Excel2Object

或使用 .NET CLI:

dotnet add package Chsword.Excel2Object

命令行工具 excel2obj

dotnet tool install -g Chsword.Excel2Object.Cli

excel2obj convert orders.xlsx --output orders.json --typed   # Excel -> JSON
excel2obj convert orders.json --output orders.xlsx           # JSON -> Excel
excel2obj generate-model orders.xlsx --class Order           # 由表头生成带 [ExcelTitle] 的 C# 模型类

详见 Chsword.Excel2Object.Cli/README.md。

发布说明和路线图

暂不支持的特性

• CLI 工具 ✅ v2.2.1 新增 - dotnet tool install -g Chsword.Excel2Object.Cli，查看 Chsword.Excel2Object.Cli/README.md
• 支持自动列宽 ✅ v2.0.4 新增
• 冻结首行与自动筛选 ✅ v2.5.0 新增
• 数据验证（下拉列表）✅ v2.5.0 新增
• 条件格式 ✅ v2.6.0 新增
• 样式表（CSS 风格）：背景色、边框、隔行底色、表头样式 ✅ v2.7.0 新增
• 支持 Excel 日期/日期时间/时间格式 ✅ v2.0.4 新增，导出为真正的日期单元格 ✅ v2.4.0 新增 - 查看 DateTimeFormats.md
• 公式列引用同一工作簿的其他 sheet ✅ v2.1.0 新增 - 查看 ExcelFunctions.md
• 公式内置函数库 ✅ v2.3.0 新增 - 334 个 Excel 函数，10 个类别 - 查看 ExcelFunctions.md

发布说明

• 2026.09.13 - v2.7.0

• ✨ 新增: 样式表 options.Styles：按作用范围写样式而不是抄在每个 [ExcelColumn] 上 —— Header / Cells / Column("标题") / OddRows / EvenRows，层叠顺序为 Cells → 奇偶行 → [ExcelColumn] → Column，只有显式设置的属性参与叠加
• ✨ 新增: 单元格背景色与边框（此前完全不支持）：Background("#4472C4")、Border("1px solid #D0D0D0")，以及 Wrap、VerticalAlign、FontSize 等
• ✨ 新增: 颜色支持十六进制（#RRGGBB / #RGB），不再局限于 56 色枚举。.xlsx 原样保存；.xls 按 CIELAB 感知距离挑调色板最近色（浅灰得到灰而非淡紫）；用 ExcelStyleColor 指定的颜色在两种格式下仍按索引写入
• ✨ 改进: 样式写在 Column("标题") 上时对任何列类型生效，包括给数字列设 Format("#,##0.00")（特性上的 Format 仍只作用于日期列，保持兼容）
• ✨ 改进: 外观相同的单元格共用一个 cell style，隔行底色等不会撑爆 .xls 的 4000 样式上限

• 2026.09.12 - v2.6.0

• ✨ 新增: 条件格式 options.ConditionalFormats：按列写规则（Operator + Value，Between 用 Value2，或直接给 Formula），命中时改字体颜色、加粗、倾斜、填充背景色；WholeRow = true 可整行高亮。规则由 Excel 求值，数据编辑后颜色跟着变，同一列可挂多条，.xls / .xlsx 都支持

• 2026.09.12 - v2.5.0

• ✨ 新增: ExcelExporterOptions.FreezeHeader 冻结首行，滚动时表头常驻；ExcelExporterOptions.AutoFilter 给表头挂上筛选下拉，范围覆盖本次写入的数据行。两项默认关闭，.xls / .xlsx 都支持
• ✨ 新增: AppendObjectToExcelBytes 增加接受 options 的重载，追加 sheet 时也能设置冻结、筛选与下拉
• ✨ 新增: 数据验证（下拉列表）：固定取值写在 [ExcelColumn("状态", Dropdown = new[] {"启用", "停用"})]，运行时取值走 options.Dropdowns["列标题"] = values（优先于特性）。Excel 会拒绝列表之外的输入；列表总长超过 255 字符或取值含逗号/引号时自动改用隐藏 sheet 承载（此前这种列表在 .xls 上会直接抛异常），空导出也会在首行挂上下拉以便做填写模板

• 2026.09.11 - v2.4.0

• ✨ 新增: 导出时 DateTime / DateTime? 列写成真正的日期单元格（序列号 + 日期格式），Excel 可以排序、筛选、参与计算，null 写成空单元格；Dictionary<string, object> 与 DataTable 导出中的 DateTime 值同样处理 - 查看 DateTimeFormats.md
• ✨ 新增: [ExcelColumn(Format = ...)] 的 .NET 日期格式串自动翻译成对应的 Excel 数字格式（yyyy-MM-dd HH:mm:ss → yyyy-mm-dd hh:mm:ss，yyyy年MM月dd日 → yyyy"年"mm"月"dd"日"），未指定时为 yyyy-mm-dd hh:mm:ss；已经是 Excel 拼写的格式（m/d/yy、[$-409]d-mmm-yy、yyyy/m/d;@）原样使用
• ✨ 新增: ExcelExporterOptions.DateTimeAsText，恢复 v2.3 及之前把日期写成文本的导出方式；DataTable 导出新增接受 options 的重载 ObjectToExcelBytes(DataTable, Action<ExcelExporterOptions>)
• 🐛 修复公式列接管带自定义 Format 的 DateTime 列时公式被丢弃、改写成模型值文本的问题：现在保留公式并套用日期格式（公式若返回数字而非日期，用 FormulaResultType 声明）
• 🐛 修复日期单元格读进 string 属性或 Dictionary<string, object> 时得到 46276.6 这类序列号的问题：现按单元格格式渲染成 yyyy-MM-dd、HH:mm:ss 或两者，[h]:mm 这类经过时间仍按数字读；数值属性（double、decimal 等）始终取原始数字
• ⚠️ 行为变更: Excel 日历不覆盖 1900 年之前（1904 日期系统的工作簿为 1904 年之前），这类日期（尤其 default(DateTime)）仍按 Format 渲染成文本写入；hh 不带 tt 时显示 24 小时制，Excel 没有不带 AM/PM 标记的 12 小时制

• 2026.09.11 - v2.3.0

• ✨ 新增: 公式内置函数库从 34 个扩充到 334 个 Excel 函数，分 10 类：数学与三角（73）、统计（80）、逻辑（11）、查找与引用（33）、日期时间（25）、文本（39）、信息（20）、财务（21）、工程（20）、数据库（12）。信息 / 财务 / 工程 / 数据库为全新分类，入口为 ExcelFunctions.Information、.Financial、.Engineering、.Database - 查看 ExcelFunctions.md
• 🐛 修复 Excel 2007 之后新增的函数写入后打开显示 #NAME? 的问题：xlsx 格式要求这类函数存成 _xlfn.IFS、_xlfn.STDEV.P（SORT/FILTER 为 _xlfn._xlws.），现已自动加前缀；此前已有的 DAYS 即受此影响
• 🐛 修复公式中的数字按当前区域性格式化的问题：de-DE 等区域下 1.5 会写成 1,5 导致公式无法解析，现统一使用不变区域性
• 🐛 修复文本字面量中的双引号未按 Excel 规则转义（" 需写成 ""）的问题
• ✨ 新增: 公式中可直接书写更多普通 C#：%（MOD）、^（乘幂）、&& / || / !（AND / OR / NOT）、三元表达式（IF）、Math.*、string 成员（ToUpper、Substring、Length、Contains 等；语义与 Excel 不完全一致的 Math.Round、string.Trim 等不翻译，需显式调用对应的 ExcelFunctions 函数）、DateTime 成员与 AddDays / AddMonths / AddYears、可空属性的 .HasValue
• ✨ 新增: 公式中可引用 lambda 捕获的局部变量与 new DateTime(...) 等常量表达式，自动求值后写成字面量（此前会生成无效公式）
• ✨ 改进: 区间（c.Matrix(...)、c.Columns(...)）可隐式用于接受单值的参数位置，SUM 等函数可混合传入单元格与区间
• 🐛 修复 [ExcelColumn] 的单元格样式被静默忽略的问题：样式缓存键与分支判断不匹配，CellBold / CellFontColor / CellAlignment 等此前完全没有写进单元格；另修复一列声明 CellAlignment 会改到工作簿默认样式、导致其他列跟着变的外溢问题（#47）
• 🐛 修复 FormulaResultType = typeof(DateTime) 的公式列没有日期格式、在 Excel 里显示成 46282.6 这类序列号的问题（#47）
• ⚠️ 不兼容变更: IStatisticsFunction.Sum 由 params ColumnMatrix[] 改为 params ColumnValue[]，IMathFunction 多个方法的返回值由 int / double 统一为 ColumnValue。源码级兼容（现有公式无需修改即可编译），但二进制不兼容，升级后需重新编译

• 2026.09.11 - v2.2.1

• 🔧 修复命令行工具包体超过 NuGet 250 MB 上限导致 2.2.0 未能发布的问题：CLI 仅保留 net8.0 并剔除原生 .pdb（库代码无变更）

• 2026.09.11 - v2.2.0

• ✨ 新增: 命令行工具 excel2obj（dotnet tool install -g Chsword.Excel2Object.Cli）：Excel ↔ JSON 转换、批量转换、由表头生成带 [ExcelTitle] 的模型类 - 查看 Chsword.Excel2Object.Cli/README.md（#9）
• ✨ 新增: 公式列可通过模型属性引用列：options.FormulaColumns.Add<Order>("Total", (c, m) => m.Price * m.Qty)，编译期检查属性名，引用未导出的属性会抛出异常 - 查看 ExcelFunctions.md（#22）
• ✨ 改进: 导出时数值列写成数字单元格、bool 列写成布尔单元格、null/DBNull 写成空白单元格（此前一律写成文本）；字符串列仍为文本，前导零不会丢失
• 🐛 修复公式中运算符优先级导致缺少括号的问题，如 c["A"] * (c["B"] + c["C"]) 此前生成 A2*B2+C2
• ✨ 改进: 公式中引用当前 sheet 不存在的列标题时抛出 Excel2ObjectException，不再静默回退

• 2026.09.08 - v2.1.0

• ✨ 新增: 公式列支持跨 sheet 引用：c.Sheet("Products")["Price", 2]、.Matrix(...)、.Columns(...)，可直接用于 VLOOKUP 等函数；另新增当前 sheet 的整列引用 c.Columns("A列", "D列") - 查看 ExcelFunctions.md
• ✨ 改进: 公式中引用不存在的列或 sheet 时抛出 Excel2ObjectException（附公式列名），不再生成无效公式
• ✨ 更新: NPOI 到 2.8.0（NPOI 2.8 起附带 OSMF EULA，本库已在 csproj 中声明接受；源代码仍为 Apache-2.0）
• 🔒 修复传递依赖 System.Security.Cryptography.Xml 的安全漏洞（钉到 8.0.4）
• 🧹 移除未使用的 SixLabors.ImageSharp 依赖；补全 FormulaColumnsCollection.CopyTo；ColumnValue.Equals/GetHashCode 不再抛异常
• 🔧 CI 与测试迁移到 .NET 10；修复发布流程中 GitHub Release 创建失败的问题

• 2025.10.11 - v2.0.5

• 🔧 release.ps1 支持自动递增补丁版本号与 -Help（库代码无变更）

• 2025.10.11 - v2.0.4

• ℹ️ 自 2.0.0.211 之后首个发布到 NuGet 的 2.0.x 版本（v2.0.1–v2.0.3 未曾发布），包含以下全部改动：
• ✨ 新增: 基于内容的自动列宽调整
  • 自动计算最优列宽
  • 支持最小和最大宽度限制
  • 正确处理中文/Unicode 字符
  • 可通过 ExcelExporterOptions 配置
• ✨ 新增: 全面的日期/时间格式支持（56 种格式）- 查看 DateTimeFormats.md
  • ISO 8601 格式（支持时区和毫秒）
  • 多种日期分隔符（横线、斜线、点号）
  • 12 小时制和 24 小时制时间格式
  • 仅时间格式
  • 区域格式支持（美国、欧洲等）
  • 向后兼容现有的中文日期格式（年月日）
• ✨ 更新: NPOI 到 2.7.5
• ✨ 更新: SixLabors.ImageSharp 到 3.1.11（修复安全漏洞）
• 🔧 GitHub Actions CI 取代 AppVeyor；新增 tag 触发的自动发布流程与 release.ps1 一键发布脚本

• 2024.10.21

• 更新 SixLabors.ImageSharp 到 2.1.9
• 测试 .NET 8.0

• 2024.05.10

• 支持 .NET 8.0 / .NET 6.0 / .NET Standard 2.1 / .NET Standard 2.0 / .NET Framework 4.7.2
• 清理已弃用的库

• 2023.11.02

• 支持列标题映射 - Issue39DynamicMappingTitle.cs

• 2023.07.31

• 支持 DateTime 和 Nullable<DateTime> 格式，如 [ExcelColumn("Title",Format="yyyy-MM-dd HH:mm:ss")]

• 2023.03.26

• 支持列标题中的特殊符号 #37 - Issue37SpecialCharTest.cs

• 2023.02.20

• 支持平台：.NET Standard 2.0/2.1、.NET 6.0、.NET Framework 4.7.2

• 2022.03.19

• 支持 ExcelImporterOptions，跳过行 - Issue32SkipLineImport.cs
• 修复超类属性 bug - Issue31SuperClass.cs

• 2021.11.4

• 多 sheet 支持 - Pr28MultipleSheetTest.cs

• 2021.10.23

• 修复 Nullable DateTime bug @SunBrook

• 2021.10.22

• 支持 Nullable 类型 - Pr24NullableTest.cs @SunBrook

• 2021.5.28

• 支持表头和单元格样式，新增列的 [ExcelColumnAttribute]
• 支持公式 - ExcelFunctions.md

var list = new List<Pr20Model>
{
        new Pr20Model
        {
            Fullname = "AAA", Mobile = "123456798123"
        },
        new Pr20Model
        {
            Fullname = "BBB", Mobile = "234"
        }
};
var bytes = ExcelHelper.ObjectToExcelBytes(list, ExcelType.Xlsx);
// model
[ExcelTitle("SheetX")]
public class Pr20Model
{
    [ExcelColumn("Full name", CellFontColor = ExcelStyleColor.Red)]
    public string Fullname { get; set; }

    [ExcelColumn("Phone Number",
        HeaderFontFamily = "Normal",
        HeaderBold = true,
        HeaderFontHeight = 30,
        HeaderItalic = true,
        HeaderFontColor = ExcelStyleColor.Blue,
        HeaderUnderline = true,
        HeaderAlignment = HorizontalAlignment.Right,
        //cell
        CellAlignment = HorizontalAlignment.Justify
    )]
    public string Mobile { get; set; }
}

• v2.0.0.113

convert project to netstandard2.0 and .net452
fixbug #12 #13

• v1.0.0.80

• support simple formula
• support standard excel model
  • excel & JSON convert
  • excel & Dictionary<string,object> convert

Support Uri to a hyperlink cell
And also support text cell to Uri Type

• v1.0.0.43

Support xlsx [thanks Soar360]
Support complex Boolean type

• v1.0.0.36

Add ExcelToObject<T>(bytes)

示例代码

定义模型

public class ReportModel
{
    [Excel("My Title", Order=1)]
    public string Title { get; set; }
    
    [Excel("User Name", Order=2)]
    public string Name { get; set; }
}

创建模型列表

var models = new List<ReportModel>
{
    new ReportModel{Name="a", Title="b"},
    new ReportModel{Name="c", Title="d"},
    new ReportModel{Name="f", Title="e"}
};

对象转 Excel 文件

var exporter = new ExcelExporter();
var bytes = exporter.ObjectToExcelBytes(models);
File.WriteAllBytes("C:\\demo.xls", bytes);

Excel 文件转对象

var importer = new ExcelImporter();
IEnumerable<ReportModel> result = importer.ExcelToObject<ReportModel>("c:\\demo.xls");

// 也可以直接使用字节数组
// IEnumerable<ReportModel> result = importer.ExcelToObject<ReportModel>(bytes);

自动列宽（新特性）

// 启用自动列宽调整
var bytes = ExcelHelper.ObjectToExcelBytes(models, options =>
{
    options.ExcelType = ExcelType.Xlsx;
    options.AutoColumnWidth = true;        // 启用自动宽度
    options.MinColumnWidth = 8;            // 最小宽度（字符）
    options.MaxColumnWidth = 50;           // 最大宽度（字符）
    options.DefaultColumnWidth = 16;       // 禁用自动时的默认宽度
});

冻结首行与自动筛选

var bytes = ExcelHelper.ObjectToExcelBytes(models, options =>
{
    options.ExcelType = ExcelType.Xlsx;
    options.FreezeHeader = true;           // 滚动时表头始终可见
    options.AutoFilter = true;             // 表头带上筛选下拉
});

两个选项默认关闭，.xls 与 .xlsx 都支持。筛选范围覆盖表头及本次写入的数据行；AppendObjectToExcelBytes 追加的 sheet 各自独立，不影响已有 sheet。

数据验证（下拉列表）

public class OrderModel
{
    [ExcelTitle("订单号")] public string No { get; set; }

    // 固定取值写在特性上
    [ExcelColumn("状态", Dropdown = new[] {"启用", "停用", "待审"})]
    public string Status { get; set; }

    [ExcelTitle("城市")] public string City { get; set; }
}

var bytes = ExcelHelper.ObjectToExcelBytes(models, options =>
{
    // 运行时才知道的取值走 options，优先于特性
    options.Dropdowns["城市"] = cities.Select(c => c.Name).ToArray();
});

Excel 会把取值显示为下拉，并拒绝其他输入。追加导出用 ExcelHelper.AppendObjectToExcelBytes(bytes, models, options => ...) 同样可以设置这些选项。列表总长超过 255 字符、或取值里含逗号/引号时（Excel 行内列表放不下），自动改写到一张隐藏 sheet 上、由一个定义名称指向该区域，下拉再引用这个名称（.xls 无法让数据验证直接跨 sheet 引用），用法不变；.xls 与 .xlsx 都支持。导出空列表时下拉仍会挂在第一行，方便做填写模板。

样式表（CSS 风格）

样式不必再抄在每个 [ExcelColumn] 上，可以按"作用于谁"来写：

var bytes = ExcelHelper.ObjectToExcelBytes(models, options =>
{
    options.Styles
        .Header(s => s.Bold().Background("#4472C4").Color("#FFF").Center())
        .Cells(s => s.Border("1px solid #D0D0D0"))
        .EvenRows(s => s.Background("#F2F2F2"))              // 隔行底色
        .Column("金额", s => s.Format("#,##0.00").Right())
        .Column("备注", s => s.Wrap().VerticalAlign(ExcelVerticalAlignment.Middle));
});

可写的属性：Color / Background（#RRGGBB、#RGB 或 ExcelStyleColor）、Bold / Italic / Underline / Strikeout、FontFamily / FontSize、Left / Center / Right / Align / VerticalAlign、Wrap、Format、Border 及 BorderTop / BorderRight / BorderBottom / BorderLeft（写法同 CSS：1px solid #D0D0D0、2px dashed red、none；颜色可用十六进制或 red、gray、navy 等 CSS 基本色名）。

层叠顺序（从宽到窄，只有显式设置的属性参与，所以各层是叠加而不是互相覆盖）：

Cells → OddRows / EvenRows → [ExcelColumn] 特性 → Column("标题")

Header(...) 位于特性的 Header* 属性之下，规则相同；写了表头样式后，整行表头字号一致，不再受"带 [ExcelColumn] 的表头默认 10pt"这条历史行为影响。

写在 Cells / 奇偶行这类大范围上的 Format 只作用于它说得上话的列：#,##0.00 不会落到日期列上把日期变成 46278.00，日期列只接受日期格式。

颜色：.xlsx 原样保存十六进制颜色；.xls 只有 56 色调色板，会按人眼感知（CIELAB）挑最接近的一个——所以浅灰得到的是灰而不是淡紫，但非常浅的颜色（如 #F2F2F2）会落到白色，.xls 下想要隔行效果建议用深一点的灰（如 #C0C0C0）。用 ExcelStyleColor 指定的颜色在两种格式下都仍按调色板索引写入。

外观相同的单元格共用同一个 cell style（.xls 上限 4000 个），隔行底色不会因为行数多而撑爆样式表。

条件格式

var bytes = ExcelHelper.ObjectToExcelBytes(models, options =>
{
    // 金额大于 1 万的单元格标红加粗
    options.ConditionalFormats.Add(new ConditionalFormat("金额")
    {
        Operator = ConditionalOperator.GreaterThan,
        Value = 10000,
        FontColor = ExcelStyleColor.Red,
        Bold = true
    });

    // 整行高亮：状态为"急件"时整行黄底
    options.ConditionalFormats.Add(new ConditionalFormat("状态")
    {
        Operator = ConditionalOperator.Equal,
        Value = "急件",
        WholeRow = true,
        BackgroundColor = ExcelStyleColor.Yellow
    });

    // 也可以直接写 Excel 条件，按第一行数据（第 2 行）书写，列用 $ 锁定
    options.ConditionalFormats.Add(new ConditionalFormat("金额")
    {
        Formula = "$B2>$C2",
        BackgroundColor = ExcelStyleColor.LightGreen
    });
});

规则由 Excel 自己求值，数据被编辑后颜色会跟着变。Value 按类型写成 Excel 字面量（数字原样、字符串加引号、DateTime 写成 DATE(y,m,d)），Between / NotBetween 用 Value2 给出另一端。同一列可以挂多条规则，.xls 与 .xlsx 都支持。

在 ASP.NET MVC 中使用

在 ASP.NET MVC 模型中，DisplayAttribute 可以像 ExcelTitleAttribute 一样被支持。

文档

• ExcelFunctions.md - 公式列：内置函数、按列标题/模型属性引用、跨 sheet 引用
• DateTimeFormats.md - 支持的日期时间格式与解析规则
• Chsword.Excel2Object.Cli/README.md - 命令行工具 excel2obj 用法
• ROADMAP.md - 路线图

更多信息请访问：http://www.cnblogs.com/chsword/p/excel2object.html

开发和发布

• 自动化发布脚本 release.ps1 - 一键完成版本更新、提交和 Tag 创建的 PowerShell 脚本
• 自动化发布系统说明 - 包含 Copilot 指令、版本管理和自动发布流程的完整说明
• 版本管理规范 - 语义化版本规范和版本号递增规则
• 发布流程指南 - 详细的发布步骤和故障排查指南
• Copilot 使用说明 - GitHub Copilot 开发指导和项目规范

快速发布新版本

使用自动化脚本一键发布：

# Windows：不带参数则自动递增修订号，也可用 -Version 2.3.0 指定
.\release.ps1

# Linux/macOS (需要 PowerShell Core)
pwsh ./release.ps1

详细说明请参阅 RELEASE_AUTOMATION.md。

贡献者

参考

• https://github.com/tonyqus/npoi
• https://github.com/chsword/ctrc

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。