Aspose.Cells FOSS
.NET
开发者指南
使用电子表格管理

使用电子表格管理

使用电子表格管理

Workbook 类是 Aspose.Cells FOSS for .NET 中所有电子表格操作的根对象。它提供对 WorksheetCollection、已定义名称以及保存/加载生命周期的访问。本指南涵盖容错加载、工作表组织、打印布局配置以及行/列/单元格布局控制。

加载工作簿并使用修复选项

将文件路径传递给 Workbook 构造函数以加载现有的 XLSX 文件。提供一个 LoadOptions 对象，并将 TryRepairPackage 和 TryRepairXml 设置为 true，以尝试恢复轻微结构损坏的文件。当文件无法恢复时，将抛出 WorkbookLoadException。

using Aspose.Cells_FOSS;

var options = new LoadOptions
{
    TryRepairPackage = true,
    TryRepairXml = true,
};

try
{
    var wb = new Workbook("data.xlsx", options);
    Console.WriteLine("Sheets: " + wb.Worksheets.Count);
    Console.WriteLine("Cell A1: " + wb.Worksheets[0].Cells["A1"].StringValue);
}
catch (WorkbookLoadException ex)
{
    Console.WriteLine("Unrecoverable: " + ex.Message);
}

添加和组织工作表

Workbook.Worksheets 返回一个 WorksheetCollection。调用 Add(name) 通过名称追加一个新工作表；该方法返回新工作表的索引。可以通过零基索引或名称访问工作表。设置 WorksheetCollection.ActiveSheetName 以控制文件打开时哪个标签页处于活动状态。

using Aspose.Cells_FOSS;

var wb = new Workbook();

// Rename the default sheet
wb.Worksheets[0].Name = "Summary";

// Add sheets
var dataIdx = wb.Worksheets.Add("Data");
var archiveIdx = wb.Worksheets.Add("Archive");

// Set active sheet
wb.Worksheets.ActiveSheetName = "Data";

// Write to sheets by name
wb.Worksheets["Summary"].Cells["A1"].PutValue("Overview total");
wb.Worksheets["Data"].Cells["A1"].PutValue("Raw rows start here");

wb.Save("organised.xlsx");

// Verify
var loaded = new Workbook("organised.xlsx");
Console.WriteLine("Active: " + loaded.Worksheets.ActiveSheetName);
Console.WriteLine("Sheet count: " + loaded.Worksheets.Count);

隐藏和显示工作表

将 Worksheet.VisibilityType 设置为 VisibilityType.Hidden 以隐藏工作表而不删除。隐藏的工作表会保存在 XLSX 文件中，可通过设置 VisibilityType.Visible 使其可见。标签颜色通过 Worksheet.TabColor 设置。

using Aspose.Cells_FOSS;

var wb = new Workbook();
wb.Worksheets[0].Name = "Visible";
var hiddenIdx = wb.Worksheets.Add("Internal");
var hiddenSheet = wb.Worksheets[hiddenIdx];

hiddenSheet.VisibilityType = VisibilityType.Hidden;
hiddenSheet.Cells["A1"].PutValue("Internal data");

wb.Worksheets["Visible"].TabColor = Color.FromArgb(255, 70, 130, 180);

wb.Save("hidden.xlsx");

配置页面设置

Worksheet.PageSetup 展示所有打印相关属性。使用 PageOrientationType 在纵向和横向之间切换。使用 PaperSizeType 选择纸张尺寸。使用 PrintArea 定义打印区域，使用 PrintTitleRows/PrintTitleColumns 设置重复的行/列，并使用 AddHorizontalPageBreak 和 AddVerticalPageBreak 添加手动分页符。

using Aspose.Cells_FOSS;

var wb = new Workbook();
var ws = wb.Worksheets[0];

// Sample data
for (var r = 0; r < 60; r++)
    ws.Cells[r, 0].PutValue("Row " + (r + 1));

var ps = ws.PageSetup;
ps.Orientation = PageOrientationType.Landscape;
ps.PaperSize = PaperSizeType.PaperA4;
ps.LeftMarginInch = 0.5d;
ps.RightMarginInch = 0.5d;
ps.TopMarginInch = 0.75d;
ps.BottomMarginInch = 0.75d;
ps.PrintArea = "$A$1:$H$60";
ps.PrintTitleRows = "$1:$1";
ps.CenterHeader = "Sales Report";
ps.LeftFooter = "Confidential";
ps.RightFooter = "Page &P of &N";
ps.PrintGridlines = true;
ps.CenterHorizontally = true;
ps.AddHorizontalPageBreak(30);

wb.Save("paged.xlsx");

var loaded = new Workbook("paged.xlsx");
Console.WriteLine("Orientation: " + loaded.Worksheets[0].PageSetup.Orientation);
Console.WriteLine("Print area: " + loaded.Worksheets[0].PageSetup.PrintArea);

行和列的大小调整

通过索引访问 Worksheet.Cells.Rows 以获取一个 Row 对象。设置 Row.Height（以点为单位）来控制行高。将 Row.IsHidden 设置为 true 以隐藏该行。通过索引访问 Worksheet.Cells.Columns 以获取一个 Column 对象。设置 Column.Width（以字符单位）和 Column.IsHidden。

using Aspose.Cells_FOSS;

var wb = new Workbook();
var ws = wb.Worksheets[0];

// Populate data
for (var r = 0; r < 5; r++)
    for (var c = 0; c < 4; c++)
        ws.Cells[r, c].PutValue($"R{r + 1}C{c + 1}");

// Row height and visibility
ws.Cells.Rows[0].Height = 28d;   // Header taller
ws.Cells.Rows[3].IsHidden = true; // Hide row 4

// Column width and visibility
ws.Cells.Columns[0].Width = 22d;
ws.Cells.Columns[3].IsHidden = true;

wb.Save("layout.xlsx");

var loaded = new Workbook("layout.xlsx");
Console.WriteLine("Row 0 height: " + loaded.Worksheets[0].Cells.Rows[0].Height);
Console.WriteLine("Col 0 width: " + loaded.Worksheets[0].Cells.Columns[0].Width);

合并单元格

调用 Worksheet.Cells.Merge(firstRow, firstColumn, totalRows, totalColumns) 将相邻的矩形块合并为单个单元格。合并后的单元格继承左上角单元格的值。使用 Worksheet.Cells.MergedCells 读取已加载工作簿中的所有合并区域。

using Aspose.Cells_FOSS;

var wb = new Workbook();
var ws = wb.Worksheets[0];

// Title spanning A1:D1
ws.Cells["A1"].PutValue("Quarterly Sales Report");
ws.Cells.Merge(0, 0, 1, 4);

// Section header spanning A3:D3
ws.Cells["A3"].PutValue("Region: North");
ws.Cells.Merge(2, 0, 1, 4);

// Column headers
ws.Cells["A4"].PutValue("Product"); ws.Cells["B4"].PutValue("Q1");
ws.Cells["C4"].PutValue("Q2");      ws.Cells["D4"].PutValue("Q3");

wb.Save("report.xlsx");

var loaded = new Workbook("report.xlsx");
Console.WriteLine("Merged regions: " + loaded.Worksheets[0].Cells.MergedCells.Count);

技巧与最佳实践

  • 使用 WorksheetCollection.ActiveSheetName 以确保文件在 Excel 中打开时选中正确的标签页。
  • 将页面边距设置为英寸 (LeftMarginInch, TopMarginInch) —— 这些是浮点数值，而非整数。
  • 隐藏行/列 (IsHidden = true) 会保留其数据；删除行会永久移除数据。
  • 始终在批处理操作结束时调用一次 Workbook.Save()，而不是在每次更改后调用。
  • 在数据表中谨慎合并单元格——合并区域会导致排序和自动筛选在合并区域内无法正常工作。

常见问题

问题原因修复
加载时的 WorkbookLoadExceptionXLSX 中的 ZIP 或 XML 损坏设置 LoadOptions.TryRepairPackage = true 和 TryRepairXml = true
Add(name) 返回错误的索引使用工作表名称作为索引Add() 返回整数索引；使用该索引访问新工作表
行高未持久化高度设置为 0 或负值使用正的 double 值，例如 28d
合并单元格显示错误的值值写入了合并范围内非左上角的单元格在调用 Cells.Merge() 之前，将值写入左上角单元格
分页符未出现AddHorizontalPageBreak 在 Save() 之后被调用在调用 Save() 之前设置分页符

FAQ

我可以添加多少个工作表？

XLSX 格式每个工作簿最多支持 1024 张工作表。实际限制取决于可用内存和文件大小。

我可以在工作簿之间复制工作表吗？

当前的 API 接口未提供用于跨工作簿复制工作表的 CopyTo 方法。请加载两个文件并逐单元格传输数据。

我该如何重新排列工作表？

使用 WorksheetCollection 索引访问并重命名工作表以更改其逻辑顺序。直接的位移操作在当前的 API 接口中不可用。

PageSetup 使用什么单位来表示页边距？

所有页边距属性（LeftMarginInch、TopMarginInch 等）均以英寸为单位，作为 double 值。

Cells.Merge 会替换已有的单元格数据吗？

左上角单元格的值被保留；其他合并单元格中的值被清除。

API Reference 摘要

类 / 方法描述
Workbook根对象 — 创建、加载、保存工作簿
Workbook.Worksheets返回 WorksheetCollection
Workbook.Save(path)持久化工作簿为 XLSX
WorksheetCollection.Add(name)按名称追加新工作表
WorksheetCollection.ActiveSheetName打开文件时的活动标签页
Worksheet.VisibilityTypeVisibilityType.Hidden or Visible
Worksheet.TabColor标签颜色（Color）
Worksheet.PageSetup打印布局设置
PageSetup.OrientationPageOrientationType.Landscape or Portrait
PageSetup.PaperSizePaperSizeType.PaperA4, etc.
PageSetup.AddHorizontalPageBreak(row)插入水平分页符
Cells.Rows[index].Height行高（单位为点）
Cells.Rows[index].IsHidden隐藏/显示行
Cells.Columns[index].Width列宽（以字符为单位）
Cells.Columns[index].IsHidden隐藏/显示列
Cells.Merge(row, col, numRows, numCols)合并矩形块
Cells.MergedCells工作表中合并的区域列表
LoadOptions.TryRepairPackage在加载时尝试 ZIP 修复
LoadOptions.TryRepairXml在加载时尝试 XML 修复
WorkbookLoadException当文件不可恢复时抛出

另请参阅

 中文