使用工作表

  • 项目

本主题讨论 Open XML SDK Worksheet、 Chartsheet 和 DialogSheet 类，以及它们与 Open XML 文件格式 SpreadsheetML 架构的关系。 有关构成 SpreadsheetML 文档的部件和元素的整体结构的详细信息，请参阅 SpreadsheetML 文档的结构。

SpreadsheetML 中的工作表

来自 ISO/IEC 29500 规范的以下信息介绍了 sheet (<sheet>) 元素。

工作表是工作簿内的核心结构，用户在工作表中执行大多数电子表格任务。 最常见的工作表类型是由单元格网格表示的工作表。 工作表单元格可以包含文本、数字、日期和公式。 用户还可以设置单元格的格式。 工作簿通常包含多个工作表。 为了帮助分析数据和做出明智的决策，电子表格应用程序通常实现可帮助计算、排序、筛选、组织和以图形方式显示信息的功能和对象。 因为这些功能通常与电子表格网格紧密关联，所以这些功能也包含在磁盘上的工作表定义中。

其他类型的工作表包括图表工作表和对话框工作表。

© ISO/IEC29500: 2008.

Open XML SDK 工作表类

Open XML SDKWorksheet 类表示在 SpreadsheetML 文档的< Open XML 文件格式架构中定义的工作表 (工作表>) 元素。 使用 Worksheet 类以操作 SpreadsheetML 文档中的各个 <worksheet> 元素。

来自 ISO/IEC 29500 规范的以下信息介绍了 worksheet (<worksheet>) 元素。

此部分类型实例包含与给定工作表相关联的所有数据、公式和特性。

对于每个工作表，包应该正好包含一个 Worksheet 部件

具体地说，sheet 元素的 ID 属性应该引用所需的工作表部件。

此内容类型的部件的根元素应该为 worksheet。

来自 ISO/IEC 29500 规范的以下信息介绍了最小工作表方案。

可能的最小（空白）工作表如下所示：

<worksheet>
    <sheetData/>
</worksheet>

空 sheetData 集合表示一个空网格；此元素是必需的。 根据架构中的定义，一些可选的工作表属性集合可以出现在 sheetData 之前，一些可以出现在 sheetData 之后。 为了简化在现有工作表（但却是空表）中插入新 sheetData 集合所需的逻辑，sheetData 集合是必需的，即使对于空表也是如此。

© ISO/IEC29500: 2008.

典型的电子表格至少包含一个工作表。 工作表包含一个类似于数据定义结构的表格，由 sheetData 元素表示。 包含数据的工作表使用 worksheet 元素作为根元素来定义工作表。 在工作表中，数据分为三个不同的部分。 第一部分包含可选的表属性。 第二部分包含数据，它使用必需的 sheetData 元素。 第三部分包含可选的支持功能，如工作表保护和筛选信息。 您只需使用 worksheet 和 sheetData 元素即可定义空工作表。 sheetData 元素可以为空。

若要为工作表创建新值，需要在 sheetData 元素中定义行。 这些行包含具有值的单元格。 row 元素定义新行。 通常 sheetData 中的第一行是可见工作表中的第一行。 在该行内使用 <c> 元素创建新单元格。 单元格的值可通过在单元格内存储 <v> 元素提供。 通常 <v> 元素包含工作表单元格的当前值。 如果值为数值，它将直接存储在 XML 文件的 <v> 元素中。 如果值为字符串值，它将存储在共享字符串表中。 有关使用共享字符串表存储字符串值的详细信息，请参阅 使用共享字符串表。

下表列出了使用 Worksheet 类时使用的常见 Open XML SDK 类。

SpreadsheetML 元素 Open XML SDK 类
sheetData SheetData
row Row
c Cell
v CellValue

有关可选 spreadsheet 元素（如表属性和支持工作表功能）的详细信息，请参阅 ISO/IEC 29500 规范。

SheetData 类

来自 ISO/IEC 29500 规范的以下信息介绍了 sheet data (<sheetData>) 元素。

单元格表格是工作表的核心结构。 它包含网格中的所有文本、数字和公式。

© ISO/IEC29500: 2008.

Row 类

来自 ISO/IEC 29500 规范的以下信息介绍了 row (<row>) 元素。

单元格表格中的单元格按行排列。 每行都有一个索引 (属性 r) ，因此不需要写出空行。每行指示为其定义的单元格数，以及它们在工作表中的相对位置。 在此示例中，第一个数据行是第 2 行。

© ISO/IEC29500: 2008.

Cell 类

来自 ISO/IEC 29500 规范的以下信息介绍了 cell (<c>) 元素。

单元格本身由 c 集合表示。 每个单元格都使用 A1 样式的引用表示法指明它在网格中的位置。 单元格还可以指明样式标识符（属性 s）和数据类型（属性 t）。 单元格类型包括 string、number 和 Boolean。 为了优化加载/保存操作，不写出默认数据值。

© ISO/IEC29500: 2008.

CellValue 类

来自 ISO/IEC 29500 规范的以下信息介绍了 cell value (<v>) 元素。

单元格包含值，无论值是直接输入的值（例如，示例中的单元格 A2 包含值 External Link:）还是计算结果（例如，示例中的单元格 B3 包含公式 B2+1）。

单元格中的字符串值不存储在单元格表格中，除非它们是计算结果。 因此，您不会看到 External Link: 显示为单元格 v 节点的内容，而是看到共享字符串表格（它是存储该字符串的唯一位置）中从 0 开始的索引。 这样做是为了优化加载/保存性能和减少信息重复。 若要确定 v 中的 0 是数字还是字符串索引，必须检查单元格的数据类型。 当数据类型指示字符串时，则它是索引而不是数字值。

© ISO/IEC29500: 2008.

Open XML SDK 代码示例

以下代码示例创建具有指定文件名的电子表格文档，并将 Open XML SDK 2.5 Worksheet 类实例化，然后添加一行并在单元格表格的 A1 位置添加一个单元格。 然后，设置 A1 中的单元格值，使它等于数字值 100。

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Spreadsheet;

CreateSpreadsheetWorkbook(args[0]);

static void CreateSpreadsheetWorkbook(string filepath)
{
    // Create a spreadsheet document by supplying the filepath.
    // By default, AutoSave = true, Editable = true, and Type = xlsx.
    SpreadsheetDocument spreadsheetDocument = SpreadsheetDocument.Create(filepath, SpreadsheetDocumentType.Workbook);

    // Add a WorkbookPart to the document.
    WorkbookPart workbookPart = spreadsheetDocument.AddWorkbookPart();
    workbookPart.Workbook = new Workbook();

    // Add a WorksheetPart to the WorkbookPart.
    WorksheetPart worksheetPart = workbookPart.AddNewPart<WorksheetPart>();
    worksheetPart.Worksheet = new Worksheet(new SheetData());

    // Add Sheets to the Workbook.
    Sheets sheets = workbookPart.Workbook.AppendChild<Sheets>(new Sheets());

    // Append a new worksheet and associate it with the workbook.
    Sheet sheet = new Sheet() { Id = workbookPart.GetIdOfPart(worksheetPart), SheetId = 1, Name = "mySheet" };
    sheets.Append(sheet);

    // Get the sheetData cell table.
    SheetData sheetData = worksheetPart.Worksheet.GetFirstChild<SheetData>() ?? worksheetPart.Worksheet.AppendChild(new SheetData());

    // Add a row to the cell table.
    Row row;
    row = new Row() { RowIndex = 1 };
    sheetData.Append(row);

    // In the new row, find the column location to insert a cell in A1.  
    Cell? refCell = null;

    foreach (Cell cell in row.Elements<Cell>())
    {
        if (string.Compare(cell.CellReference?.Value, "A1", true) > 0)
        {
            refCell = cell;
            break;
        }
    }

    // Add the cell to the cell table at A1.
    Cell newCell = new Cell() { CellReference = "A1" };
    row.InsertBefore(newCell, refCell);

    // Set the cell value to be a numeric value of 100.
    newCell.CellValue = new CellValue("100");
    newCell.DataType = new EnumValue<CellValues>(CellValues.Number);

    // Dispose the document.
    spreadsheetDocument.Dispose();
}