使用工作表
本主题讨论 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();
}