16. 超级表¶
本章介绍超级表(Table / ListObject)的创建、样式、列格式、删除与读回。
Warning
超级表支持 xlsx / xlsm / xlsb 读写。写出到其他格式时超级表被丢弃,经 OnDegradation 上报(见第 22 章)。
16.1 创建超级表¶
覆盖区首行作为表头列名,至少需要表头 + 1 行数据:
var ws = Excel.Create().Worksheets["Sheet1"];
// 先写表头 + 数据
ws.SetValue("A1", "Product");
ws.SetValue("B1", "Price");
ws.SetValue("A2", "Apple");
ws.SetValue("B2", 3.5);
ws.SetValue("A3", "Banana");
ws.SetValue("B3", 2.0);
var table = ws.AddTable("A1:B3", "Products"); // 默认 Medium9 样式
| 参数 | 类型 | 说明 |
|---|---|---|
refAddress |
string |
表覆盖区域(A1 风格,首行恒为表头) |
name |
string |
表名(全簿唯一;允许中文,不能以数字开头、不能含空格、不能撞单元格地址) |
style |
TableStyleStyle? |
内置样式枚举;缺省默认 Medium9(另有 string styleName 重载,见 16.3) |
返回 XlTable,可直接对其设置列格式等属性。
16.2 样式枚举 TableStyleStyle¶
TableStyleStyle 枚举内置 60 个条纹名(Light 1-21 / Medium 1-28 / Dark 1-11)+ None;样式外观由 Excel 内置渲染,文件仅保存样式名:
16.3 任意样式名 CustomStyleName¶
string 重载 AddTable(ref, name, styleName) 可传任意样式名字符串(含 Excel 未来新增样式名):
var table = ws.AddTable("A1:B3", "Products", "TableStyleMedium9");
// 不在 60 个内置名内时 Excel 打开退化为无样式(经 OnDegradation 上报)
⚠️ 样式名不在 60 个内置名内时,Excel 打开会静默退化为无样式,经
OnDegradation回调上报(见第 22 章)。
16.4 表属性¶
XlTable 成员:Name(全簿唯一,允许中文,不能以数字开头、不能含空格、不能撞单元格地址)、Ref、Style、CustomStyleName、ShowRowStripes(默认 true)、ShowFirstColumn、ShowLastColumn、ShowColumnStripes、AutoFilter(默认 true)、TotalsRowShown(读回保留)、HeaderStyle、Columns。返回的 XlTable 可直接读取这些属性:
var ws = Excel.Create().Worksheets["Sheet1"];
ws.SetValue("A1", "Product");
ws.SetValue("B1", "Price");
ws.SetValue("A2", "Apple");
ws.SetValue("B2", 3.5);
var table = ws.AddTable("A1:B2", "Products", TableStyleStyle.Medium2);
Console.WriteLine($"{table.Name} {table.Ref} {table.Style} 行条纹={table.ShowRowStripes} 筛选={table.AutoFilter}");
输出:
16.5 列格式¶
table.Column(name) 按列名取列(大小写不敏感),设置 Style(font/fill/border → dxf)与 NumberFormat:
var table = ws.AddTable("A1:B3", "Products");
table.Column("Price").NumberFormat = "#,##0.00";
table.Column("Price").Style = new CellStyle { Bold = true };
| 参数 | 类型 | 说明 |
|---|---|---|
Column(name) 的 name |
string |
列名(= 表头单元格文本,大小写不敏感;不存在抛 LiteExcelException) |
NumberFormat |
string? |
该列数字格式(如 "#,##0.00") |
Style |
CellStyle? |
该列样式(字体 / 填充 / 边框,写出映射到 dxf) |
16.6 删除超级表¶
RemoveTable(name) 按表名(大小写不敏感)删除超级表,存在则返回 true,否则 false:
16.7 读回超级表¶
打开含超级表的文件后,Worksheet.Tables 自动回填(含样式、列格式),遍历即可打印:
var opened = Excel.Open("tables.xlsx");
foreach (var t in opened.Worksheets[0].Tables)
{
Console.WriteLine($"{t.Name} {t.Ref} 样式={t.CustomStyleName ?? t.Style.ToString()}");
foreach (var col in t.Columns)
Console.WriteLine($" {col.Name} fmt={col.NumberFormat}");
}
输出:
