5. 数据类型与转换¶
本章讲单元格值的类型体系:五种 CellType、工厂方法、SetValue 自动类型转换、数字格式、读取时日期识别、公式,以及 List\<T> / DataTable 映射。
5.1 单元格类型 CellType¶
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
输出:
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
输出:
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
输出:
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()); // 按格式读回
输出:
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 日期系统标志会在保存时写回对应格式标志,保证日期序列值基准一致。
输出:
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
输出:
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
输出:
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");
输出:
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) // 忽略属性
);
输出:
// 读取时 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 重建 |
输出:
⚠️ DataTable 路径不经过反射映射(
[LiteColumn]/ Fluent 配置不适用);首行始终为列名(includeHeader=false除外)。