跳转至

5. 数据类型与转换

本章讲单元格值的类型体系:五种 CellType、工厂方法、SetValue 自动类型转换、数字格式、读取时日期识别、公式,以及 List\<T> / DataTable 映射。


5.1 单元格类型 CellType

public enum CellType { Text, Number, Date, Boolean, Empty }

Cell.Type 决定哪个值字段有效:Text / Number / Date / Boolean。IsEmpty 表示空单元格。

5.2 工厂方法

方法 返回 说明
FromText(string?) Cell 文本单元格
FromNumber(double, string?) Cell 数字单元格,可带数字格式
FromDate(DateTime, string?) Cell 日期单元格,默认格式 yyyy-MM-dd
FromBoolean(bool) Cell 布尔单元格
FromFormula(string) Cell 公式单元格,仅写公式字符串,不计算结果
Empty Cell 空单元格占位
var t = Cell.FromText("hello");
var n = Cell.FromNumber(42, "#,##0.00");      // 可带数字格式
var d = Cell.FromDate(new DateTime(2024, 1, 1));  // 默认格式 yyyy-MM-dd
var b = Cell.FromBoolean(true);
var f = Cell.FromFormula("SUM(A1:A3)");        // 公式单元格
var e = Cell.Empty;
Console.WriteLine(d.GetString());   // 默认日期格式 yyyy-MM-dd

输出:

2024-01-01

5.3 自动类型转换

SetValue(object?) 按 CLR 类型自动映射:

CLR 类型 单元格类型
bool Boolean
DateTime Date(默认 yyyy-MM-dd)
sbyte/byte/short/ushort/int/uint/long/ulong/float/double/decimal Number
null / DBNull Empty
其他(含 string) Text
var ws = Excel.Create().Worksheets["Sheet1"];

ws.SetValue("A1", 3.14);        // Number
ws.SetValue("A2", true);        // Boolean
ws.SetValue("A3", DateTime.Now); // Date
ws.SetValue("A4", "text");      // Text
ws.SetValue("A5", null);        // Empty

Console.WriteLine(ws.Cell("A1").Type);   // Number
Console.WriteLine(ws.Cell("A2").Type);   // Boolean
Console.WriteLine(ws.Cell("A3").Type);   // Date
Console.WriteLine(ws.Cell("A4").Type);   // Text
Console.WriteLine(ws.Cell("A5").Type);   // Empty

输出:

Number
Boolean
Date
Text
Empty

5.4 可空类型

SetValue 接受 object?,可空值类型(int? / DateTime? 等)装箱后按底层值处理;null 写空单元格:

var ws = Excel.Create().Worksheets["Sheet1"];

int? maybe = null;
ws.SetValue("A1", maybe);        // 写空
maybe = 7;
ws.SetValue("A2", maybe);        // Number 7
Console.WriteLine(ws.Cell("A1").IsEmpty);     // True(null 写空)
Console.WriteLine(ws.Cell("A2").GetDouble()); // 7

输出:

True
7

5.5 数字格式速查

NumberFormat 使用 Excel 格式代码字符串,常见示例:

格式代码 效果
"0" 整数
"0.00" 两位小数
"#,##0.00" 千分位 + 两位小数
"0%" 百分比
"yyyy/m/d" / "yyyy-MM-dd" 日期
"hh:mm" 时间
"@" 文本
var ws = Excel.Create().Worksheets["Sheet1"];

ws.Cell("A1").SetValue(12345.678);
ws.Cell("A1").NumberFormat = "#,##0.00";   // 显示 12,345.68
Console.WriteLine(ws.Cell("A1").GetString());  // 按格式读回

输出:

12,345.68

5.6 读取时日期自动识别

读取 xlsx / xlsm / xlsb 时,单元格数字格式为 Excel 内置日期格式(ID 14-22、27-36、45-47、50-58 等)时,自动读为 CellType.Date:

var opened = Excel.Open("report.xlsx");
var cell = opened.Worksheets[0].Cell("A1");
if (cell.Type == CellType.Date)
    Console.WriteLine(cell.GetDateTime().ToString("yyyy-MM-dd"));

打开时捕获的 1904 日期系统标志会在保存时写回对应格式标志,保证日期序列值基准一致。

输出:

2024-01-01

5.7 公式

Cell.Formula 与缓存值字段分离,公式串不再占用 Text,避免覆盖文本公式的缓存结果值。旧代码把公式写进 Text 且设 IsFormula=true 的写法仍兼容:

var ws = Excel.Create().Worksheets["Sheet1"];

var cell = ws.Cell("C1");
cell.Formula = "SUM(A1:B1)";     // 仅写公式字符串,不计算结果
cell.IsFormula = true;           // 写出时按公式处理(兼容垫片)

// 或直接给单元格赋一个公式 Cell(SetValue 支持传 Cell,会复制其内容)
ws.Cell("C2").SetValue(Cell.FromFormula("A1*2"));
Console.WriteLine(cell.Formula);             // SUM(A1:B1)
Console.WriteLine(ws.Cell("C2").Formula);    // A1*2

输出:

SUM(A1:B1)
A1*2

List\<T> 映射中可用 [LiteColumn(IsFormula = true)] 把字符串属性当作公式列(见 5.9)。

公式写回(xls/xlsb):自 2.4.74 起,xls 与 xlsb 支持基础公式写回。Cell.FromFormula("SUM(A1:B1)") 会在写出时经内置 FormulaEncoder 将 A1 文本编码为 BIFF8/BIFF12 RPN。支持常量(数字/字符串/布尔)、单元格引用(含绝对 $A$1)、区域引用、基础运算符(+ - * / ^ & = < > <= >=)和内置函数。不支持的公式(数组、跨表引用、名称等)降级为缓存值写出,不影响文件读取。

5.8 Byte[]

SetValue 遇到非数值类型一律按 Text 处理(value.ToString())。二进制数据请走图片 API(Worksheet.AddImage,见第 13 章)或自行编码为文本。库本身不把 byte[] 映射为二进制单元格类型。

var ws = Excel.Create().Worksheets["Sheet1"];

ws.SetValue("A1", Convert.ToBase64String(new byte[] { 1, 2, 3 }));  // 自行编码为文本
Console.WriteLine(ws.Cell("A1").GetString());                       // AQID

输出:

AQID

5.9 List\<T> 映射与 [LiteColumn]

[LiteColumn] 特性控制 List\<T> 映射时的列名 / 顺序 / 格式 / 忽略 / 公式:

public class Person
{
    [LiteColumn(Name = "姓名", Order = 0)]
    public string Name { get; set; } = "";

    [LiteColumn(Name = "年龄", Order = 1, Format = "0")]
    public int Age { get; set; }

    [LiteColumn(Name = "总额", Order = 2, Format = "#,##0.00", IsFormula = true)]
    public string Total { get; set; } = "";   // 值可带或不带前导 "="

    [LiteColumn(Ignore = true)]
    public string Secret { get; set; } = "";  // 不输出
}
var people = new List<Person> { new() { Name = "张三", Age = 30, Total = "=100*2", Secret = "隐藏" } };
var wb = Excel.Create(people, "People");   // 表头:姓名 | 年龄 | 总额;Secret 列忽略
wb.SaveAs("report.xlsx");

输出:

已写入 report.xlsx

List\<T> 映射自动转换的 CLR 类型:

CLR 类型 单元格类型 说明
int / long / short / byte Number 整数
double / float / decimal Number 小数
DateTime Date 日期时间
bool Boolean 布尔值
string Text 文本

以上类型均支持可空版本(int? / DateTime? 等),null 写为空单元格。

5.10 List\<T> Fluent 配置(WriteOptions\<T> / ReadOptions\<T>)

除了 [LiteColumn] 特性,还支持 Fluent API 与字典映射,适合临时调整列名 / 格式 / 忽略 / 公式:

var people = new List<Person> { new() { Name = "张三", Age = 30, Total = "=100*2" } };

// 写出时 Fluent 配置
Excel.Write("out.xlsx", people, "Employees", opt => opt
    .Column(p => p.Name, "姓名")                    // 指定列名
    .Column(p => p.Age, "年龄", format: "0")        // 指定列名 + 数字格式
    .Column(p => p.Total, "总额", isFormula: true)  // 公式列(值可带或不带前导 "=")
    .Ignore(p => p.Secret)                          // 忽略属性
);

输出:

已写入 out.xlsx
// 读取时 Fluent 配置
var list = Excel.Read<Person>("out.xlsx", "Employees", opt => opt
    .Column(p => p.Name, "姓名")                    // 指定表头名 -> 属性映射
    .Column(p => p.Age, "年龄")
);
// 字典映射(configure 用命名参数,sheetName 取默认 "Sheet1")
Excel.Write("out.xlsx", people, configure: opt => opt
    .Map(new Dictionary<string, string> { { "Name", "姓名" }, { "Age", "年龄" } })
);

5.11 DataTable 便利 API

DataTable 自带列结构,无需反射(不触发反射映射),AOT 安全。首行自动写为列名:

var dt = new DataTable("订单");
dt.Columns.Add("OrderID", typeof(int));
dt.Columns.Add("Customer", typeof(string));
dt.Columns.Add("Amount", typeof(decimal));
dt.Columns.Add("Date", typeof(DateTime));
dt.Rows.Add(1001, "Alice", 599.99m, new DateTime(2024, 6, 1));
dt.Rows.Add(1002, "Bob", 1299.50m, new DateTime(2024, 6, 15));

Excel.Write("out.xlsx", dt, "Orders");   // 一步写出

var back = Excel.ReadAsDataTable("out.xlsx", "Orders");   // 读回(首行为表头)
foreach (DataRow row in back.Rows)
    Console.WriteLine($"#{row["OrderID"]} | {row["Customer"]} | {row["Amount"]:0.00}");

var wb = Excel.Create(dt);        // 一步建簿;sheetName 缺省取 DataTable.TableName(再空则 Sheet1)
Console.WriteLine("sheet: " + wb.Worksheets[0].Name);
wb.SaveAs("report.xlsx");

var opened = Excel.Open("out.xlsx");
// 导入到已有工作表:清空现有内容后从 A1 重建;includeHeader=false 不写列名行
opened.Worksheets[0].ImportData(dt, includeHeader: false);
opened.SaveAs("report.xlsx");
Console.WriteLine("imported rows: " + Excel.ReadAsDataTable("report.xlsx", "Orders", firstRowIsHeader: false).Rows.Count);

重要参数:

API 参数 类型 说明
Excel.Write sheetName string 目标工作表名,默认 "Sheet1"
Excel.Write options ExcelWriteOptions? 写入选项(见 3.5)
Excel.Create sheetName string? 空则取 DataTable.TableName,再空则 "Sheet1"
Excel.ReadAsDataTable sheetName string? 目标工作表,null 读第一张表
Excel.ReadAsDataTable firstRowIsHeader bool 首行是否作为列名,默认 true
ImportData includeHeader bool 是否写列名行,默认 true;导入会清空整表后从 A1 重建

输出:

#1001 | Alice | 599.99
#1002 | Bob | 1299.50
sheet: 订单
imported rows: 2

⚠️ DataTable 路径不经过反射映射([LiteColumn] / Fluent 配置不适用);首行始终为列名(includeHeader=false 除外)。