跳转至

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 内置渲染,文件仅保存样式名:

var table = ws.AddTable("A1:B3", "Products", TableStyleStyle.Medium2);

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}");

输出:

Products A1:B2 Medium2 行条纹=True 筛选=True

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:

bool removed = ws.RemoveTable("Products");   // 存在则删除并返回 true

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}");
}

输出:

Products A1:B3 样式=TableStyleMedium2
  Product fmt=
  Price fmt=#,##0.00

超级表与筛选效果

上图由本章示例代码写出,在 Excel 中打开的效果:条纹样式、表头筛选下拉与货币格式。