Utilisation des feuilles

Article
01/21/2025

Cette rubrique décrit les classes , et DialogSheet du Kit de développement logiciel (SDK) Worksheet ChartsheetOpen XML, ainsi que leur relation avec le schéma SpreadsheetML du 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 de la spécification 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.

Classe de feuille de calcul du Kit de développement logiciel (SDK) Open XML

La classe du Kit de développement logiciel (SDK Worksheet ) Open XML représente l’élément worksheet (<worksheet/>) défini dans le schéma de format de fichier Open XML pour les documents SpreadsheetML. Utilisez la Worksheet classe pour manipuler des éléments individuels <worksheet/> dans un document SpreadsheetML.

Les informations suivantes de la spécification ISO/IEC 29500 introduisent 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.

Un fichier de tableur standard contient au moins une feuille de calcul. La feuille de calcul contient une table telle que la structure pour la définition des données, représentée par l’élément sheetData . Une feuille qui contient des données utilise l’élément worksheet comme élément racine pour définir 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 deuxième section contient les données, à l’aide de l’élément requis sheetData . 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 devez uniquement utiliser les worksheet éléments et sheetData . L’élément sheetData peut être vide.

Pour créer des 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 du sheetData est la première ligne de la feuille visible. À l’intérieur de la ligne, vous en créez un à cells l’aide de l’élément <c/> . Les valeurs des cellules peuvent être fournies en stockant un <v/> élément à l’intérieur de la cellule. En règle générale, l’élément <v/> contient la valeur actuelle de la cellule de 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 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 Worksheet classe .

Élément SpreadsheetML	Classe du Kit de développement logiciel (SDK) Open XML
`<sheetData/>`	SheetData
`<row/>`	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 de la spécification ISO/IEC 29500 introduisent l’élément sheet data (<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.

Classe Row

Les informations suivantes de la spécification ISO/IEC 29500 introduisent 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.

Classe Cell

Les informations suivantes de la spécification ISO/IEC 29500 introduisent 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.

Classe CellValue

Les informations suivantes de la spécification ISO/IEC 29500 introduisent l’élément cell value (<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 External Link comme contenu du nœud v de la cellule, vous voyez plutôt un index de base zéro dans la table de chaînes partagée où cette 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.

Exemple de code du Kit de développement logiciel (SDK) Open XML

L’exemple de code suivant crée un document de feuille de calcul avec le nom de fichier spécifié et instancie une Worksheet classe, puis ajoute une ligne et ajoute une cellule à la table de cellules à la position A1. Ensuite, il affecte la valeur numérique 100 à cette cellule.

C#
Visual Basic

static void CreateSpreadsheetWorkbook(string filepath)
{
    // Use 'using' block to ensure proper disposal of the document
    using (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(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 = 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);
    }
}

Sub CreateSpreadsheetWorkbook(filepath As String)
    ' Use 'Using' block to ensure proper disposal of the document
    Using spreadsheetDocument As SpreadsheetDocument = SpreadsheetDocument.Create(filepath, SpreadsheetDocumentType.Workbook)
        ' Add a WorkbookPart to the document.
        Dim workbookPart As WorkbookPart = spreadsheetDocument.AddWorkbookPart()
        workbookPart.Workbook = New Workbook()

        ' Add a WorksheetPart to the WorkbookPart.
        Dim worksheetPart As WorksheetPart = workbookPart.AddNewPart(Of WorksheetPart)()
        worksheetPart.Worksheet = New Worksheet(New SheetData())

        ' Add Sheets to the Workbook.
        Dim sheets As Sheets = workbookPart.Workbook.AppendChild(Of Sheets)(New Sheets())

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

        ' Get the sheetData cell table.
        Dim sheetData As SheetData = If(worksheetPart.Worksheet.GetFirstChild(Of SheetData)(), worksheetPart.Worksheet.AppendChild(Of SheetData)(New SheetData()))

        ' Add a row to the cell table.
        Dim row As Row = New Row() With {
            .RowIndex = 1
        }
        sheetData.Append(row)

        ' In the new row, find the column location to insert a cell in A1.  
        Dim refCell As Cell = Nothing

        For Each cell As Cell In row.Elements(Of Cell)()
            If String.Compare(cell.CellReference?.Value, "A1", True) > 0 Then
                refCell = cell
                Exit For
            End If
        Next

        ' Add the cell to the cell table at A1.
        Dim newCell As Cell = New Cell() With {
            .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(Of CellValues)(CellValues.Number)
    End Using
End Sub

SpreadsheetML généré

À l'exécution du code du Kit de développement logiciel (SDK) Open XML 2.5, le code XML suivant est écrit dans le document SpreadsheetML référencé dans le code. Pour afficher ce code XML, ouvrez le fichier sheet.xml dans le dossier worksheets du fichier .zip.

    <?xml version="1.0" encoding="utf-8"?>
    <x:worksheet xmlns:x="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
        <x:sheetData>
            <x:row r="1">
                <x:c r="A1" t="n">
                    <x:v>100</x:v>
                </x:c>
            </x:row>
        </x:sheetData>
    </x:worksheet>

Classe Chartsheet du Kit de développement logiciel (SDK) Open XML

Les informations suivantes de la spécification ISO/IEC 29500 présentent l’élément chartsheet (<chartsheet/>).

Une instance de ce type de composant représente un graphique stocké dans sa propre feuille.

Un package peut contenir plusieurs composants Chartsheet ou n’en comprendre aucun.

Exemple : sheet1.xml fait référence à un dessin qui est la cible d’une relation dans l’élément relation du composant Chartsheet :

<chartsheet xmlns:r="…" …>
    <sheetViews>
        <sheetView scale="64"/>
    </sheetViews\>
    <drawing r:id="rId1">
</chartsheet>

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 Chartsheet classe .

Élément SpreadsheetML	Classe du Kit de développement logiciel (SDK) Open XML
`<drawing/>`	Drawing

Classe Drawing

Les informations suivantes de la spécification ISO/IEC 29500 présentent l’élément drawings (<wsDr/>).

Une instance de ce type de composant contient les informations de présentation et de mise en page des éléments de dessin présents sur cette feuille de calcul.

Un package peut contenir un ou plusieurs composants Drawings, chacun étant cible d'une relation explicite depuis un composant Worksheet (§12.3.24) ou un composant Chartsheet (§12.3.2). Il ne peut y avoir qu'un composant Drawings par feuille de calcul ou feuille de graphique.

Classe Dialogsheet du KIT DE DÉVELOPPEMENT LOGICIEL (SDK) Open XML

Les informations suivantes de la spécification ISO/IEC 29500 présentent l’élément dialogsheet (<dialogsheet/>).

Une instance de ce type de composant contient les informations sur une boîte de dialogue personnalisée pour un formulaire utilisateur.

Un package peut contenir un ou plusieurs composants Dialogsheet.

Dialogsheet représente l’élément racine d’un composant de ce type de contenu.

Exemple : sheet1.xml contient les composants suivants :

<dialogsheet xmlns:r="…" …>
    <sheetPr>
        <pageSetUpPr/>
    </sheetPr>
    <sheetViews>
        …
    </sheetViews>
    …
    <legacyDrawing r:id="rId1"/>
</dialogsheet>

Partager via