3. 文件导航¶
本章介绍文件层面的操作:从哪打开、往哪保存、建新簿、查表名,外加工作表与文档属性的管理。
Warning
本库 不创建、不编辑 图表(Chart)与数据透视表(PivotTable)。 打开 xlsx / xlsm / xlsb 再保存时这些元素原样透传保留;xls / csv 无保留机制,打开再保存会丢失,覆盖源文件前请先另存副本。
3.1 格式 ExcelFormat¶
Excel.Open 按扩展名自动选后端。两种情况需要显式传 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
扩展名和内容对不上时,显式指定格式:
流打开:必须显式给格式。输入流不会被关闭,由调用方管理;不可定位的流(如网络流)会在内部复制到内存。
using var fs = File.OpenRead("report.xlsx");
var wb = Excel.Open(fs, ExcelFormat.Xlsx);
// 打开后 CurrentPath 为 null,需用 SaveAs 指定保存路径
wb.SaveAs("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 章。
输出:
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); // 按索引删除
遍历工作表:
输出:
⚠️ 表名校验规则见第 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); // 存到流
输出:
静态方法:工作簿是临时构建、不需要回写原路径时用。
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 |
输出:
文件级密码(打开 / 修改)仅支持 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); // 季度报告
输出: