跳转至

3. 文件导航

本章介绍文件层面的操作:从哪打开、往哪保存、建新簿、查表名,外加工作表与文档属性的管理。

Warning

本库 不创建、不编辑 图表(Chart)与数据透视表(PivotTable)。 打开 xlsx / xlsm / xlsb 再保存时这些元素原样透传保留;xls / csv 无保留机制,打开再保存会丢失,覆盖源文件前请先另存副本。


3.1 格式 ExcelFormat

public enum ExcelFormat { Xlsx, Xlsm, Xlsb, Xls, Csv }

Excel.Open 按扩展名自动选后端。两种情况需要显式传 format:扩展名与内容不符,或从流读取(流没有扩展名)。

Excel.DetectFormat("report.xlsx")   // → ExcelFormat.Xlsx,按扩展名判断
wb.Format                           // 当前工作簿格式,保存时沿用

SaveAs(path, format) 要求路径扩展名与格式一致,否则抛 LiteExcelException。

3.2 打开工作簿

路径打开:扩展名对得上就不用管格式。

var wb = Excel.Open("report.xlsx");
var wb2 = Excel.Open("data.csv");              // 自动识别为 Csv
var wb3 = Excel.Open("legacy.xls");            // 自动识别为 Xls

扩展名和内容对不上时,显式指定格式:

var wb = Excel.Open("data.bin", ExcelFormat.Xlsx);

流打开:必须显式给格式。输入流不会被关闭,由调用方管理;不可定位的流(如网络流)会在内部复制到内存。

using var fs = File.OpenRead("report.xlsx");
var wb = Excel.Open(fs, ExcelFormat.Xlsx);
// 打开后 CurrentPath 为 null,需用 SaveAs 指定保存路径
wb.SaveAs("copy.xlsx");

输出:

已写入 copy.xlsx

读取选项:Open 的第二个参数。

var wb = Excel.Open("secured.xlsx", new ExcelReadOptions
{
    OpenPassword = "secret",
    ModifyPassword = "write",
    FillMergedCells = true,
    Separator = ';',
});
参数 类型 说明
OpenPassword string? 打开密码,解密带密码的 xlsx / xlsm / xlsb
ModifyPassword string? 修改密码(写保护),提供后获得编辑 / 保存权限
FillMergedCells bool 把合并区左上角的值展开到整个合并区域,默认 false
Separator char? 仅 CSV 生效,null 时自动探测
ReadStyles bool 是否读取样式,默认 true
LeaveOpen bool 读完后是否保持输入流打开,默认 false

3.3 新建工作簿

var wb1 = Excel.Create();                    // 空簿,默认 Sheet1
Console.WriteLine(wb1.Worksheets[0].Name);   // 打印验证:默认表名

var wb2 = Excel.Create("Data");              // 指定首个工作表名
var wb3 = Excel.Create(new[] { "Q1", "Q2", "Q3" });   // 批量建表
var wb4 = Excel.Create(ExcelFormat.Xlsm);    // 指定格式

一步建簿并写数据(List<T>、DataTable):

var people = new List<Person> { new() { Name = "A", Age = 1 } };
var wb5 = Excel.Create(people, "People");    // 首行为表头

var dt = new System.Data.DataTable("T");
dt.Columns.Add("X");
dt.Rows.Add("v");
var wb6 = Excel.Create(dt);                  // sheetName 为空时用 TableName

sheetName 缺省时取数据源的 TableName,再空则回落到 Sheet1;configure 是 List<T> 写出时的映射配置,见第 5 章。

输出:

Sheet1

3.4 工作表:查询与管理

只取表名:不必加载整个工作簿。

var names = Excel.GetSheetNames("report.xlsx");   // List<string>
using var stream = File.OpenRead("report.xlsx");
var names2 = Excel.GetSheetNames(stream);         // 仅 xlsx/xlsm

GetSheetNames(path) 对 xlsx / xlsm 直接读元数据;xlsb / xls / csv 会走 Excel.Open 解析。流重载只支持 xlsx / xlsm,取 xlsb 表名请用 Excel.Open(stream, ExcelFormat.Xlsb).Worksheets.Names。

增删、移动、访问都在 Workbook.Worksheets:

var wb = Excel.Create();
var ws = wb.Worksheets["Sheet1"];         // 按名称访问(不存在抛 LiteExcelException)
var first = wb.Worksheets[0];             // 按索引访问(0-based)
Console.WriteLine(wb.Worksheets.Count);   // 数量
Console.WriteLine(string.Join(", ", wb.Worksheets.Names));   // 所有表名
Console.WriteLine(wb.Worksheets.Contains("Sheet1"));         // true

wb.Worksheets.Add("Data");                // 新增空表
wb.Worksheets.Add("People", peopleList);  // 新增表并写 List<T>(首行表头)
wb.Worksheets.Add("T", dataTable);        // 新增表并写 DataTable(首行列名)
wb.Worksheets.Move(0, 2);                 // 移动顺序(0-based)
wb.Worksheets.Remove("Data");             // 按名称删除(存在返回 true)
wb.Worksheets.RemoveAt(0);                // 按索引删除

遍历工作表:

foreach (var sheet in wb.Worksheets)
    Console.WriteLine(sheet.Name);

输出:

1
Sheet1
True
Sheet1
T

⚠️ 表名校验规则见第 24 章:含 \ / ? * [ ] : 或超 31 字符的表名,保存时抛 InvalidSheetNameException。

3.5 保存与写出

实例方法:Save 存到 CurrentPath,SaveAs 指定新路径。

wb.Save();                    // 保存到 CurrentPath
wb.SaveAs("out.xlsx");        // 另存,沿用当前格式
wb.SaveAs("out.xlsm", ExcelFormat.Xlsm);   // 另存并转格式
wb.Save(new FileStream("s.xlsx", FileMode.Create), ExcelFormat.Xlsx);  // 存到流

输出:

已写入 out.xlsx / out.xlsm / s.xlsx

静态方法:工作簿是临时构建、不需要回写原路径时用。

Excel.Write("out.xlsx", wb);
Excel.Write("out.xlsx", wb, new ExcelWriteOptions { AutoFitColumns = true });
wb.Save(stream, ExcelFormat.Xlsx);          // 写到一个流

写入选项:

Excel.Write("out.xlsx", wb, new ExcelWriteOptions
{
    Overwrite = true,
    AutoFitColumns = true,
    FreezeHeader = true,
    Properties = new WorkbookProperties { Creator = "Me" },
    OnDegradation = info => Console.WriteLine(info.Capability),
    Separator = ';',
});
参数 类型 说明
Overwrite bool 目标已存在时是否覆盖,默认 true
AutoFitColumns bool 写出前自动估算列宽,默认 false
FreezeHeader bool 写出时冻结表头,默认 false
Properties WorkbookProperties? 覆盖文档属性,见 3.6
OnDegradation Action<DegradationInfo>? 能力降级回调,写出到不支持某能力的格式时逐项上报
Separator char? 仅 CSV 生效,null 时默认逗号
LeaveOpen bool 写完后是否保持输出流打开,默认 false

输出:

已写入 out.xlsx

文件级密码(打开 / 修改)仅支持 xlsx / xlsm / xlsb,存为 csv / xls 时若带密码会报错。这类「目标格式不支持某能力」的情况都会经 OnDegradation 逐项上报,挂个回调就能拿到清单。

Warning

含 VBA 宏的工作簿不允许存为 xlsx / xls(不支持宏的格式),会提前报错。覆盖源文件前请先另存副本。

3.6 文档属性 WorkbookProperties

Warning

仅支持 xlsx / xlsm / xlsb。写出 xls 时属性静默丢失,经 OnDegradation 上报。

Workbook.Properties 对应 xlsx 包内的 docProps/core.xml 与 docProps/app.xml:

var wb = Excel.Create();
wb.Properties.Creator = "JackZ";
wb.Properties.LastModifiedBy = "Me";
wb.Properties.Created = DateTime.Now;
wb.Properties.Modified = DateTime.Now;
wb.Properties.Title = "季度报告";
wb.Properties.Subject = "财务";
wb.Properties.Application = "LiteExcel";
wb.SaveAs("props.xlsx");

Creator(作者,dc:creator)、LastModifiedBy(最后保存者)、Created / Modified(创建与最后修改时间)、Title / Subject(标题与主题)、Application(应用程序名,null 时写出取宿主程序集名)。

写出时覆盖属性:

Excel.Write("out.xlsx", wb, new ExcelWriteOptions
{
    Properties = new WorkbookProperties { Creator = "Bot", Title = "Auto" },
});

读回文档属性:

var opened = Excel.Open("props.xlsx");
Console.WriteLine(opened.Properties.Creator);    // JackZ
Console.WriteLine(opened.Properties.Title);      // 季度报告

输出:

JackZ
季度报告