Utilisation des feuilles
Cette rubrique décrit les classes Feuille de calcul, Feuille de graphique et DialogSheet du Kit de développement logiciel (SDK) Open XML, ainsi que leur relation avec le schéma SpreadsheetML au format de fichier Open XML. Pour plus d’informations sur la structure globale des composants et éléments qui composent un document SpreadsheetML, consultez Structure d’un document SpreadsheetML.
Feuilles dans un document SpreadsheetML
Les informations suivantes, extraites de la norme ISO/IEC 29500, présentent l’élément Sheet (<sheet>).
Les feuilles constituent la structure centrale d'un classeur, où les utilisateurs effectuent la plupart de leur travail de tableur. Le type de feuille le plus courant est la feuille de calcul, qui est représentée par une grille de cellules. Ces cellules peuvent contenir du texte, des nombres, des dates et des formules. Il est également possible de leur appliquer une mise en forme. Les classeurs contiennent généralement plusieurs feuilles. Pour aider à l'analyse des données et à la prise de décisions éclairées, les tableurs implémentent des fonctions et des objets qui permettent de calculer, trier, filtrer, organiser et afficher graphiquement les informations. Ces fonctions étant souvent connectées très étroitement à la grille du tableur, elles sont également incluses dans la définition des feuilles sur le disque.
Les feuilles de graphique et les feuilles de dialogue sont d'autres types de feuilles.
© ISO/IEC29500: 2008.
Classe de feuille de calcul du Kit de développement logiciel (SDK) Open XML
La classeFeuille de calcul du Kit de développement logiciel (SDK) Open XML représente l’élément worksheet (<feuille de calcul>) défini dans le schéma de format de fichier Open XML pour les documents SpreadsheetML. Utilisez la classe Worksheet pour manipuler des éléments <worksheet> distincts dans un document SpreadsheetML.
Les informations suivantes, extraite de la norme ISO/IEC 29500, présentent l’élément worksheet (<worksheet>).
Une instance de ce type de composant contient toutes les données, formules et caractéristiques associées à une feuille de calcul donnée.
Un package doit contenir exactement un composant Worksheet par feuille de calcul.
Spécifiquement, l'attribut Id de l'élément feuille doit référencer le composant feuille de calcul voulu.
L'élément racine d'un composant de ce type de contenu doit être une feuille de calcul.
Les informations suivantes issues des spécifications ISO/IEC 29500 introduisent le scénario de feuille de calcul minimum.
La feuille la plus petite possible (vierge) se présente comme suit :
<worksheet>
<sheetData/>
</worksheet>
La collection sheetData vide représente une grille vide ; cet élément est requis. Comme défini dans le schéma, certaines collections de propriétés de feuille facultatives peuvent apparaître avant sheetData, et d'autres après. Pour simplifier la logique d'insertion d'une nouvelle collection sheetData dans une feuille existante (mais vide), la collection sheetData est requise, même vide.
© ISO/IEC29500: 2008.
Un fichier de tableur standard contient au moins une feuille de calcul. La feuille de calcul contient une structure de type tableau pour la définition des données, représentée par l'élément sheetData. Une feuille contenant des données utilise l'élément worksheet comme racine de définition des feuilles de calcul. À l'intérieur d'une feuille de calcul, les données sont réparties en trois sections distinctes. La première section contient les propriétés de feuille facultatives. La seconde section contient les données, en utilisant l'élément sheetData requis. La troisième section contient des fonctionnalités de prise en charge facultatives comme la protection de feuille et les informations de filtre. Pour définir une feuille de calcul vide, vous utilisez uniquement les éléments worksheet et sheetData. L'élément sheetData peut être vide.
Pour créer de nouvelles valeurs pour la feuille de calcul, vous définissez des lignes à l'intérieur de l'élément sheetData. Ces lignes contiennent des cellules contenant des valeurs. L'élément row définit une nouvelle ligne. Normalement, la première ligne de l’élément sheetData est la première ligne de la feuille visible. À l’intérieur de la ligne, créez des cellules à l’aide de l’élément <c>. Les valeurs des cellules peuvent être générées en stockant un élément <v> à l’intérieur de la cellule. Généralement, l’élément <v> contient la valeur actuelle de la cellule de la feuille de calcul. Si la valeur est une valeur numérique, elle est stockée directement dans l’élément <v> du fichier XML. Si la valeur est une valeur de chaîne, elle est stockée dans un tableau de chaînes partagé. Pour plus d’informations sur l’utilisation de la table de chaînes partagée pour stocker des valeurs de chaîne, consultez Utilisation de la table de chaînes partagée.
Le tableau suivant répertorie les classes courantes du Kit de développement logiciel (SDK) Open XML utilisées lors de l’utilisation de la classe Worksheet .
| Élément SpreadsheetML | Classe du Kit de développement logiciel (SDK) Open XML |
|---|---|
| sheetData | SheetData |
| ligne | Row |
| c | Cell |
| v | CellValue |
Pour en savoir plus sur les éléments facultatifs de la feuille de calcul, tels que les propriétés et les fonctionnalités prises en charge, reportez-vous à la norme ISO/IEC 29500.
Classe SheetData
Les informations suivantes, extraites de la norme ISO/IEC 29500, présentent l’élément sheetdata (<sheetData>).
Le tableau de cellules est la structure centrale d'une feuille de calcul. Il comprend tous les textes, nombres et formules de la grille.
© ISO/IEC29500: 2008.
Classe Row
Les informations suivantes, extraites de la norme ISO/IEC 29500, présentent l’élément row (<row>).
Les cellules du tableau de cellules sont organisées en lignes. Chaque ligne a un index (attribut r) de sorte que les lignes vides n’ont pas besoin d’être écrites. Chaque ligne indique le nombre de cellules définies pour elle, ainsi que leur position relative dans la feuille. Dans cet exemple, la première ligne de données est la ligne 2.
© ISO/IEC29500: 2008.
Classe Cell
Les informations suivantes, extraites de la norme ISO/IEC 29500, présentent l’élément cell (<c>).
La cellule elle-même est exprimée par la collection c. Chaque cellule indique sa position dans la grille dans la notation de référence de style A1. Une cellule peut également indiquer un identificateur de style (attribut s) et un type de données (attribut t). Les cellules sont de type chaîne, numérique ou booléen. Pour optimiser les opérations de chargement et d'enregistrement, les valeurs par défaut des données ne sont pas écrites.
© ISO/IEC29500: 2008.
Classe CellValue
Les informations suivantes, extraites de la norme ISO/IEC 29500, présentent l’élément cellvalue (<v>).
Les cellules contiennent des valeurs, qui sont entrées directement (par ex., la cellule A2 dans notre exemple a la valeur Lien externe:) ou sont le résultat d'un calcul (par ex., la cellule B3 dans notre exemple contient la formule B2+1).
Les valeurs de type chaîne des cellules ne sont pas stockées dans le tableau de cellules, sauf si elles résultent d'un calcul. Par conséquent, au lieu de voir Lien externe: comme contenu du nœud v de cellule, vous voyez un index de base zéro dans le tableau de chaînes partagé où la chaîne est stockée de manière unique. Cela permet d'optimiser les performances de chargement et d'enregistrement et de limiter la duplication des informations. Pour déterminer si le 0 dans v est un nombre ou un index vers une chaîne, le type de données de la cellule doit être examiné. Lorsque le type de données indique chaîne, il s'agit d'un index et pas d'une valeur numérique.
© ISO/IEC29500: 2008.
Exemple de code Open XML SDK 2.0
L'exemple de code suivant crée un document de tableur ayant le nom de fichier spécifié, instancie une classe du Kit de développement logiciel (SDK) Open XML 2.5, Worksheet, ajoute une ligne, puis ajoute une cellule au tableau de cellules en position A1. Ensuite, il affecte la valeur numérique 100 à cette cellule.
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();
}