Conteneur Table

Utilisez les conteneurs Table pour présenter vos données les plus complexes. Les tableaux jouent un rôle crucial dans les documents PDF, améliorant leur clarté et leur efficacité.

Les tableaux fournissent un format structuré pour présenter vos données. Ils vous permettent de présenter des détails complexes de manière concise et visuellement attrayante. Au lieu de longs paragraphes, vous pouvez utiliser des tableaux pour présenter succinctement les faits, les chiffres et les tendances.

Un tableau bien conçu améliore la lisibilité. En alignant les colonnes et les lignes, vous créez une structure qui guide l'œil du lecteur. Vous pouvez utiliser des arrière-plans, des bordures et des styles de police pour mettre en valeur des cellules ou des titres spécifiques.

Obtenez un conteneur de table en appelant la méthode LayoutContainer.Table. Ensuite, vous devez définir au moins une colonne dans le conteneur. Dans le cas le plus simple, vous pouvez remplir toutes les colonnes et lignes en appelant plusieurs fois la méthode Cell.

Veuillez continuer votre lecture pour savoir comment définir des colonnes, ajouter un en-tête et/ou un pied de page à un tableau. Le texte décrit également toutes les autres fonctionnalités du conteneur Table.

Cet article fait partie d'une série sur l'API Layout pour la génération de PDF. Si vous débutez avec l'API, lisez d'abord la partie Mise en route avec l'API Layout.

Colonnes et lignes

Chaque table doit définir au moins une colonne. Utilisez la méthode Table.Columns pour définir les colonnes. La méthode accepte un délégué de type Action<TableColumnContainer>. Dans le code du délégué, ajoutez des colonnes à la table en appelant les méthodes de l'objet fourni.

La méthode ConstantColumn ajoute une colonne dont la largeur est égale à un nombre exact de points.

La méthode RelativeColumn ajoute une colonne avec une largeur relative. La méthode accepte le nombre de parties que la colonne doit occuper. Le nombre total de parties est la somme de tous les nombres de tous les appels RelativeColumn dans ce tableau. Généralement, cette méthode fonctionne de la même manière que le RelativeItem du conteneur Row. Veuillez lire le lien pour l'explication détaillée.

Il n'est pas nécessaire de définir explicitement les lignes. Le nombre de lignes dépend des propriétés des colonnes et des cellules. Le nombre de cellules peut également affecter le nombre de lignes. Le tableau peut avoir une hauteur supérieure à la somme de toutes ses hauteurs de lignes. Les lignes peuvent contenir moins de cellules que le nombre de colonnes. Et il est possible que les colonnes contiennent moins de cellules que le nombre de lignes.

PdfDocumentBuilder.Create().Generate("table-basic.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Size(300, 100);
        page.Content()
            .Padding(10)

            //.MinimalBox()

            .Border(b => b.Thickness(1).Color(new PdfRgbColor(250, 123, 5)))
            .Table(table =>
            {
                table.Columns(columns =>
                {
                    columns.ConstantColumn(100);
                    columns.RelativeColumn(1);
                    columns.RelativeColumn(3);
                });

                for (int i = 0; i < 10; i++)
                {
                    table.Cell()
                        .Border(b => b.Thickness(0.1))
                        .AlignCenter()
                        .Text($"Cell {i + 1}");
                }
            });
    });
});

Vous pouvez voir le résultat du code dans table-basic.pdf.

Dans le PDF résultant, le tableau occupe tout l'espace du conteneur parent. Même s’il n’y a pas assez de cellules pour couvrir la zone. Décommentez l'appel MinimalBox pour limiter la hauteur de la table à la somme de ses hauteurs de lignes.

Le code définit trois colonnes et ajoute 10 cellules au tableau. Le tableau place les cellules les unes après les autres, en ajoutant une nouvelle ligne si nécessaire. C'est parfaitement bien d'avoir une ligne avec une seule cellule.

Le tableau placera les cellules sur la page suivante si la page actuelle ne dispose pas de suffisamment d'espace. Vous pouvez observer cela en augmentant le nombre de cellules ajoutées.

Cellules

Laissez-moi vous expliquer ce que l'API Layout propose pour travailler avec les cellules d'un tableau.

Position

Il existe deux manières de créer une cellule de tableau :

• sans informations de position explicites
• avec position au moins partiellement spécifiée

J'ai utilisé la première méthode dans le code de la section précédente. Vous appelez la surcharge de méthode Cell qui n'accepte pas de paramètres. La méthode ajoute une nouvelle cellule à la colonne après la dernière cellule ajoutée. S'il n'y a pas d'espace à droite, la cellule passe à la ligne suivante. En mode RTL, la méthode vérifie l'espace à gauche de la dernière cellule ajoutée.

Si vous connaissez la position exacte de la nouvelle cellule, utilisez l'autre surcharge de la méthode Cell. Celui qui accepte un délégué de type Action<TableCell>. Dans le code du délégué, spécifiez la ligne et l'index de la cellule en appelant les méthodes RowIndex et ColumnIndex de l'objet fourni.

Il est possible de spécifier uniquement un index de ligne ou de colonne pour la nouvelle cellule. L'index de colonne est 0 lorsque vous spécifiez uniquement un index de ligne. Et vice versa.

Lors de la création de cellules, vous pouvez mélanger les appels aux deux surcharges Cell dans n'importe quel ordre.

J'utiliserai la méthode d'extension suivante dans les prochains exemples de code de cet article. Cela devrait rendre les exemples plus concis et plus faciles à lire.

static class LayoutHelpers
{
    public static TextSpan BoxWithText(this LayoutContainer cell, string caption)
        => cell.Border(b => b.Thickness(0.5))
            .Background(new PdfGrayColor(75))
            .ShowOnce()
            .MinWidth(50)
            .MinHeight(50)
            .Padding(10)
            .AlignCenter()
            .AlignMiddle()
            .Text(caption);
}

Voici un exemple qui crée un tableau avec des cellules placées explicitement et implicitement. J'ai utilisé la méthode d'extension pour appliquer du style et du texte aux cellules. Les nombres dans les cellules reflètent l'ordre de création des cellules.

PdfDocumentBuilder.Create().Generate("table-cells.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Size(300, 200);
        page.Content()
            .Padding(10)
            .MinimalBox()
            .Border(b => b.Thickness(0.1))
            .Table(table =>
            {
                table.Columns(columns =>
                {
                    for (int i = 0; i < 4; i++)
                        columns.RelativeColumn();
                });

                table.Cell().BoxWithText("1");
                table.Cell(c => c.RowIndex(1).ColumnIndex(1)).BoxWithText("2");
                table.Cell().BoxWithText("3");
                table.Cell(c => c.RowIndex(2).ColumnIndex(2)).BoxWithText("4");
                table.Cell(c => c.RowIndex(0).ColumnIndex(3)).BoxWithText("5");
            });
    });
});

Vous pouvez voir le résultat du code dans table-cells.pdf.

Étendues de lignes et de colonnes

Les cellules peuvent s'étendre sur plusieurs lignes et/ou plusieurs colonnes. Utilisez la surcharge Cell qui accepte un délégué pour spécifier le nombre de lignes et de colonnes couvertes par la cellule.

PdfDocumentBuilder.Create().Generate("table-cellspans.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Size(300, 150);
        page.Content()
            .Padding(10)
            .MinimalBox()
            .Border(b => b.Thickness(0.1))
            .Table(table =>
            {
                table.Columns(columns =>
                {
                    for (int i = 0; i < 4; i++)
                        columns.RelativeColumn();
                });

                table.Cell(c => c.RowSpan(2).ColumnSpan(2)).BoxWithText("1");
                table.Cell(c => c.ColumnSpan(2)).BoxWithText("2");
                table.Cell().BoxWithText("3");
                table.Cell().BoxWithText("4");
            });
    });
});

Vous pouvez voir le résultat du code dans table-cellspans.pdf.

Chevauchement

Il est possible que les cellules se recouvrent. Lorsque cela se produit, l’ordre de création définit quelle cellule se superposera à une autre.

Vous pouvez obtenir des cellules qui se chevauchent lorsque vos cellules s'étendent sur plusieurs colonnes ou lignes. Ou lorsque vous positionnez des cellules de manière explicite et implicite.

PdfDocumentBuilder.Create().Generate("table-overlapping.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Size(300, 300);
        page.Content()
            .Padding(10)
            .MinimalBox()
            .Border(b => b.Thickness(0.1))
            .Table(table =>
            {
                table.Columns(columns =>
                {
                    for (int i = 0; i < 4; i++)
                        columns.RelativeColumn();
                });

                for (int i = 0; i < 16; i++)
                    table.Cell().BoxWithText($"{i + 1}");

                table.Cell(c => c.RowIndex(2).ColumnIndex(1).ColumnSpan(3))
                    .Background(new PdfRgbColor(250, 123, 5), 50);
            });
    });
});

Vous pouvez voir le résultat du code dans table-overlapping.pdf.

S'étendre vers le bas

Si la disposition de votre tableau est complexe, le mécanisme de pagination peut provoquer un espace vide en bas de certaines de vos colonnes. Utilisez la méthode ExtendCellsToBottom si vous souhaitez vous débarrasser de l'espace vide. La méthode étend la dernière cellule de chaque colonne afin que les cellules se terminent au bas du tableau.

Dans l'exemple suivant, la première page affiche le comportement par défaut. La deuxième page montre comment l'appel ExtendCellsToBottom affecte les colonnes.

PdfDocumentBuilder.Create().Generate("table-extendcells.pdf", doc =>
{
    for (int take = 0; take < 2; take++)
    {
        doc.Pages(page =>
        {
            page.Size(300, 200);
            page.Content()
                .Padding(10)
                .MinimalBox()
                .Border(b => b.Thickness(0.1))
                .Table(table =>
                {
                    if (take != 0)
                        table.ExtendCellsToBottom();

                    table.Columns(columns =>
                    {
                        for (int i = 0; i < 4; i++)
                            columns.RelativeColumn();
                    });

                    table.Cell(c => c.RowIndex(0).ColumnIndex(0)).BoxWithText("1");
                    table.Cell(c => c.RowIndex(2).ColumnIndex(0)).BoxWithText("2");
                    table.Cell(c => c.RowIndex(1).ColumnIndex(1)).BoxWithText("3");
                    table.Cell(c => c.RowIndex(2).ColumnIndex(2)).BoxWithText("4");
                    table.Cell(c => c.RowIndex(1).ColumnIndex(3)).BoxWithText("5");
                });
        });
    }
});

Vous pouvez voir le résultat du code dans table-extendcells.pdf.

En-tête et pied de page

Les tableaux peuvent avoir un en-tête et un pied de page. Utilisez les méthodes Header et Footer pour accéder et configurer le TableCellContainer correspondant. Le conteneur fournit les méthodes Cell pour créer des cellules. Ces méthodes fonctionnent exactement de la même manière que les méthodes pour le contenu de la table principale.

Les cellules d’en-tête, de pied de page et du tableau principal utilisent la même définition de colonne. Mais les trois collections de cellules sont indépendantes et ne s’influencent pas mutuellement.

Lorsque le tableau ne tient pas sur une seule page, l'en-tête et le pied de page sont répétés sur chaque page occupée par le tableau.

J'ai utilisé la méthode d'extension BoxWithText dans les exemples précédents. J'utilise également la méthode d'extension WhiteBoxWithText pour le code suivant.

static class LayoutHelpers
{
    public static TextSpan WhiteBoxWithText(
        this LayoutContainer cell, string caption, bool center = true)
    {
        return cell.Border(b => b.Thickness(0.5))
            .ShowOnce()
            .MinWidth(50)
            .MinHeight(50)
            .Padding(10)
            .Container(l => center ? l.AlignCenter() : l)
            .AlignMiddle()
            .Text(caption);
    }
}

L'exemple suivant montre comment créer un tableau avec un en-tête. J'utilise un tableau avec cinq éléments chimiques essentiels. Il y a le nom et le point de fusion en degrés Celsius et Kelvin pour chaque élément.

var elements = new (string Name, double Celsius, double Kelvin)[] {
    ("Oxygen", -218.79, 54.36),
    ("Carbon", double.NaN, double.NaN),
    ("Hydrogen", -259.16, 13.99),
    ("Nitrogen", -209.86, 63.23),
    ("Sulfur", 115.21, 388.36),
};

static string formatDouble(double val)
{
    return double.IsNaN(val)
        ? string.Empty
        : val.ToString(CultureInfo.InvariantCulture);
}

PdfDocumentBuilder.Create().Generate("table-header.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Size(400, 500);
        page.Content()
            .Padding(10)
            .MinimalBox()
            .Border(b => b.Thickness(0.1))
            .Table(table =>
            {
                table.Columns(columns =>
                {
                    columns.RelativeColumn();
                    columns.ConstantColumn(100);
                    columns.ConstantColumn(100);
                });

                table.Header(header =>
                {
                    header.Cell(c => c.RowSpan(2)).BoxWithText("Chemical element");
                    header.Cell(c => c.ColumnSpan(2)).BoxWithText("Melting point");

                    header.Cell().BoxWithText("Celsius");
                    header.Cell().BoxWithText("Kelvin");
                });

                foreach (var (Name, Celsius, Kelvin) in elements)
                {
                    table.Cell().WhiteBoxWithText(Name, false);

                    table.Cell().WhiteBoxWithText(formatDouble(Celsius));
                    table.Cell().WhiteBoxWithText(formatDouble(Kelvin));
                }
            });
    });
});

Vous pouvez voir le résultat du code dans table-header.pdf.

Exemple de code

Veuillez prendre le temps de vérifier l'exemple Ajouter des tableaux aux documents PDF. Il montre également comment créer des tableaux avec des en-têtes, mais n'utilise aucune méthode d'extension. Et il existe également une version VB.NET.