Trabajar con hojas
En este tema se describen las clases Worksheet, Chartsheet y DialogSheet del SDK de Open XML y cómo se relacionan con el esquema SpreadsheetML de formato de archivo Open XML. Para obtener más información sobre la estructura general de los elementos y elementos que componen un documento SpreadsheetML, vea Estructura de un documento SpreadsheetML.
Sheets en SpreadsheetML
La siguiente información de la especificación ISO/IEC 29500 presenta el elemento sheet (<sheet>).
Las hojas son las estructuras centrales de un libro y en ellas el usuario realiza la mayor parte de su trabajo de hoja de cálculo. El tipo de hoja más común es la hoja de cálculo, que se representa como una cuadrícula de celdas. Las celdas de la hoja de cálculo pueden contener texto, números, fechas y fórmulas. A las celdas también se les puede aplicar formato. Normalmente, los libros contienen más de una hoja. Para facilitar el análisis de datos y tomar decisiones informadas, las aplicaciones de hoja de cálculo suelen implementar características y objetos que ayudan a calcular, ordenar, filtrar, organizar y mostrar gráficamente la información. Dado que estas características suelen estar conectadas muy estrechamente con la cuadrícula de la hoja de cálculo, también se incluyen en la definición de la hoja en el disco.
Entre otros tipos de hojas se incluyen las hojas de gráfico y las hojas de diálogo.
© ISO/IEC29500: 2008.
Clase worksheet del SDK de Open XML
La clase Worksheet del SDKde Open XML representa el elemento worksheet (<worksheet>) definido en el esquema Open XML File Format para documentos SpreadsheetML. Use la clase Worksheet para manipular elementos individuales <worksheet> en un documento de SpreadsheetML.
La siguiente información de la especificación ISO/IEC 29500 presenta el elemento worksheet (<worksheet>).
Una instancia de este tipo de parte contiene todos los datos, las fórmulas y las características asociada a una hoja de cálculo dada.
Un paquete debe incluir exactamente una parte de hoja de cálculo por cada hoja de cálculo.
En concreto, el atributo de identificación del elemento sheet debe hacer referencia a la parte de hoja de cálculo deseado.
El elemento raíz de una parte de este tipo de contenido debe ser worksheet.
La siguiente información de la especificación ISO/IEC 29500 presenta el escenario de hoja de cálculo mínima.
La hoja (en blanco) más pequeña posible contiene lo siguiente:
<worksheet>
<sheetData/>
</worksheet>
La colección sheetData vacía representa una cuadrícula vacía; este elemento es obligatorio. Como se define en el esquema, algunas colecciones de propiedades de hoja opcionales pueden aparecer antes de sheetData y otras pueden aparecer después. Para simplificar la lógica necesaria para insertar una nueva colección sheetData en una hoja existente (pero vacía), se requiere la colección sheetData, aunque esté vacía.
© ISO/IEC29500: 2008.
Una hoja de cálculo típica tiene al menos una hoja de cálculo. La hoja de cálculo contiene una tabla como estructura para definir los datos, representada por el elemento sheetData. Una hoja que contiene datos usa el elemento worksheet como elemento raíz para definir las hojas de cálculo. Dentro de una hoja de cálculo, los datos se dividen en tres secciones distintas. La primera sección contiene propiedades de hoja opcionales. La segunda sección contiene los datos, mediante el elemento sheetData necesario. La tercera sección contiene características auxiliares opcionales como la protección de hoja y la información de filtro. Para definir una hoja de cálculo vacía, solo se deben usar los elementos worksheet y sheetData. El elemento sheetData puede estar vacío.
Para crear nuevos valores para la hoja de cálculo, se deben definir filas dentro del elemento sheetData. Estas filas contienen celdas que incluyen valores. El elemento row define una fila nueva. Normalmente la primera fila en sheetData es la primera fila en la hoja visible. Dentro de la fila, cree nuevas celdas con el elemento <c>. Los valores para las celdas pueden proporcionarse almacenando un elemento <v> dentro de la celda. Normalmente el elemento <v> contiene el valor actual de la celda de la hoja de cálculo. Si el valor es un valor numérico, se almacena directamente en el elemento <v> en el archivo XML. Si el valor es un valor de cadena, se almacena en una tabla de cadenas compartida. Para obtener más información sobre el uso de la tabla de cadenas compartidas para almacenar valores de cadena, vea Trabajar con la tabla de cadenas compartidas.
En la tabla siguiente se enumeran las clases comunes del SDK de Open XML que se usan al trabajar con la clase Worksheet .
| Elemento de SpreadsheetML | Open XML SDK (clase) |
|---|---|
| sheetData | SheetData |
| row | Row |
| c | Cell |
| v | CellValue |
Para obtener más información sobre los elementos de hoja de cálculo opcionales, como las propiedades de la hoja y la compatibilidad de características de la hoja, vea la especificación ISO/IEC 29500
Clase SheetData
La siguiente información de la especificación ISO/IEC 29500 presenta el elemento sheet data (<sheetData>).
La tabla de celdas es la estructura principal de una hoja de cálculo. Se compone de todo el texto, los números y las fórmulas de la cuadrícula.
© ISO/IEC29500: 2008.
Clase Row
La siguiente información de la especificación ISO/IEC 29500 presenta el elemento row (<row>).
Las celdas de la tabla de celdas se organizan por filas. Cada fila tiene un índice (atributo r) para que no sea necesario escribir filas vacías. Cada fila indica el número de celdas definidas para ella, así como su posición relativa en la hoja. En este ejemplo, la primera fila de datos es la fila 2.
© ISO/IEC29500: 2008.
Clase Cell
La siguiente información de la especificación ISO/IEC 29500 presenta el elemento cell (<c>).
La celda propiamente dicha se expresa mediante la colección c. Cada celda indica su ubicación en la cuadrícula mediante la notación de referencia de estilo A1. Una celda también puede indicar un identificador de estilo (atributo s) y un tipo de datos (atributo t). Entre los tipos de celda se incluyen string, number y Boolean. A fin de optimizar las operaciones de cargar y guardar, los valores de datos predeterminados no se escriben.
© ISO/IEC29500: 2008.
Clase CellValue
La siguiente información de la especificación ISO/IEC 29500 presenta el elemento cell value (<v>).
Las celdas contienen valores, independientemente de si los valores se introdujeron directamente (por ejemplo, la celda A2 del ejemplo tiene el valor External Link:) o son el resultado de un cálculo (por ejemplo, la celda B3 del ejemplo tiene la fórmula B2+1).
Los valores de cadena de una celda no se almacenan en la tabla de celdas a menos que sean el resultado de un cálculo. Por lo tanto, en lugar de ver External Link: como contenido del nodo v de la celda, verá un índice basado en cero en la tabla de cadenas compartidas donde se almacena exclusivamente esa cadena. Esto se realiza para optimizar el rendimiento de cargar y guardar y para reducir la duplicación de información. Para determinar si el 0 en v es un número o un índice de una cadena, se debe examinar el tipo de datos de la celda. Cuando el tipo de datos indica una cadena, será un índice y no un valor numérico.
© ISO/IEC29500: 2008.
Ejemplo de código de Open XML SDK 2.0
Mediante el siguiente ejemplo de código se crea un documento de hoja de cálculo con el nombre de archivo especificado, se crea una instancia de una clase Worksheet de SDK de Open XML 2.5 y, a continuación, se agregan una fila y una celda a la tabla de celdas en la posición A1. Posteriormente, el valor de la celda en A1 se establece igual al valor numérico 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();
}