Conteneurs et leur contenu

Un document est un ensemble de pages. Chaque page, à son tour, est un ensemble d’éléments de contenu. Comme vous le savez peut-être déjà, PageLayout fournit des conteneurs pour le contenu principal et supplémentaire. Mais que faire de ces conteneurs ?

Les conteneurs aident à organiser le contenu sur les pages. Tout ce que vous mettez sur une page doit aller dans un conteneur. Si le contenu est suffisamment volumineux, un conteneur peut occuper de l'espace sur plusieurs pages.

Vous pouvez mettre du texte ou une image dans un conteneur. À des fins d’alignement et de positionnement, vous pouvez placer un conteneur dans un autre conteneur. Il existe des conteneurs qui offrent de la place pour plusieurs éléments de contenu.

Les conteneurs sur une page sont représentés par des objets de la classe LayoutContainer. Utilisez cette classe pour configurer la taille, la position, le contenu et le processus de rendu de vos conteneurs.

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.

Comment fonctionnent les conteneurs

Vous commencez par vous procurer un conteneur. Par exemple, en appelant la méthode PageLayout.Content. Cette méthode renverra un conteneur qui n’occupe aucun espace et n’a aucun contenu ni propriétés définies. Utilisez les méthodes de la classe LayoutContainer pour configurer le conteneur.

La chose très importante à comprendre est que toutes les méthodes LayoutContainer placent le contenu dans le conteneur. Lorsque vous ajoutez du texte au conteneur, il est attendu. Mais que devient le contenu lorsque vous définissez un retrait ou une largeur ?

Lorsque vous définissez une propriété de conteneur, la bibliothèque crée un nouveau conteneur avec la propriété spécifiée. Le nouveau conteneur devient le contenu du conteneur d'origine. La bibliothèque renvoie le conteneur imbriqué comme résultat de la méthode.

Les propriétés des conteneurs imbriqués affectent les conteneurs parents et vice versa. Par exemple, la largeur d'un conteneur imbriqué affecte la taille des conteneurs parents. Le style de texte par défaut d'un conteneur parent affecte le texte des conteneurs imbriqués. Le module complémentaire Layout utilise la hiérarchie des conteneurs et leurs propriétés pour créer la mise en page résultante.

Le résultat du code suivant pourrait vous surprendre, mais veuillez prendre le temps de l'analyser. Le code illustre le fonctionnement des conteneurs imbriqués.

PdfDocumentBuilder.Create().Generate("containers-how.pdf", doc => doc.Pages(page =>
{
    page.Size(150, 150);
    page.Content()
        .Background(new PdfRgbColor(235, 64, 52)) // rouge

        .PaddingTop(50)
        .Background(new PdfRgbColor(187, 237, 237)) // bleu

        .PaddingRight(50)
        .Background(new PdfRgbColor(15, 130, 9)) // vert

        .PaddingBottom(50)
        .Background(new PdfRgbColor(250, 123, 5)) // orange

        .PaddingLeft(50)
        .Background(new PdfRgbColor(204, 204, 204)); // gris
}));

Décoration

La conception de documents implique bien plus que l’organisation du texte et des images. Un document correctement conçu crée non seulement une communication efficace mais également visuellement attrayante.

Avec l'API Layout, vous pouvez appliquer une couleur d'arrière-plan à n'importe quel conteneur. Cela aide à établir une hiérarchie au sein de votre contenu. Vous pouvez également définir des limites en appliquant des bordures. Utilisez des lignes verticales et horizontales pour séparer les éléments de contenu.

PdfDocumentBuilder.Create().Generate("containers-decor.pdf", doc => doc.Pages(page =>
{
    page.Size(150, 150);
    page.Content()
        .Background(new PdfRgbColor(250, 123, 5))
        .Border(b =>
        {
            b.Color(new PdfGrayColor(0), 50);
            b.Thickness(15);
        })
        .PaddingTop(74)
        .LineHorizontal(2)
            .Color(new PdfCmykColor(73, 45, 0, 4))
            .DashPattern(new PdfDashPattern(new double[] { 8, 2 }));
}));

L'API prend en charge les couleurs opaques et semi-translucides dans les espaces colorimétriques Gray, RGB et CMYK. Outre les lignes continues, l'API Layout prend en charge les lignes qui utilisent des modèles de tirets.

Le résultat du code ci-dessus est dans containers-decor.pdf.

Contenu

Voyons ce que la classe LayoutContainer fournit pour organiser le contenu.

Text

Pour ajouter du texte à un conteneur, utilisez l'une des méthodes Text.

Si tout le texte utilise le même style, utilisez la version simple et abrégée de la méthode. Cette version accepte une chaîne et renvoie un objet TextSpan. Vous pouvez utiliser cet objet pour définir le style de texte pour la durée.

Il existe une autre version de la méthode Text qui accepte un délégué de type Action<TextContainer>. Utilisez cette version pour avoir des étendues avec différents styles dans un bloc de texte. TextContainer fournit des méthodes pour insérer des images et d'autres éléments entre des étendues de texte. Il existe d'autres fonctionnalités avancées, comme la possibilité de définir une distance entre les paragraphes.

PdfDocumentBuilder.Create().Generate("containers-text.pdf", doc => doc.Pages(page =>
{
    page.Header().Text("This is a simple text span");

    page.Content().Text(t =>
    {
        t.Span("This line contains ");
        t.Span("some underlined text").Style(TextStyle.Parent.Underline());
    });
}));

Vous pouvez voir le résultat du code dans containers-text.pdf.

Image

L'API Layout fournit des méthodes pour créer des objets Image à partir de données d'image dans un fichier ou un flux. Tout objet Image peut servir de contenu à un conteneur. Vous pouvez utiliser le même objet Image dans plusieurs conteneurs. Il existe différents modes de contenu qui affectent l'apparence de l'image à l'intérieur du conteneur.

La bibliothèque peut charger des images aux formats raster uniquement : PNG, JPEG, JPEG 2000, BMP, GIF et TIFF.

PdfDocumentBuilder.Create().Generate("containers-image.pdf", doc =>
{
    var imageFile = new FileInfo(@"path-to-image.jpg");
    var image = doc.Image(imageFile);

    doc.Pages(pages =>
    {
        pages.Size(image.Width, image.Height);
        pages.Content().Image(image, ImageContentMode.FitArea);
    });
});

Column

Les colonnes offrent de l'espace pour un nombre illimité d'éléments placés verticalement les uns après les autres. Vous pouvez utiliser des éléments de n’importe quel type dans une colonne. Par exemple, une colonne peut contenir des éléments d’image et de texte. La largeur de chaque élément est égale à la largeur de la colonne. La hauteur de chaque élément dépend de son contenu et de ses propriétés.

PdfDocumentBuilder.Create().Generate("containers-column.pdf", doc => doc.Pages(page =>
{
    page.Content().Column(c =>
    {
        for (int i = 0; i < 10; i++)
        {
            PdfColor color = i % 2 == 0
                ? new PdfRgbColor(187, 237, 237)
                : new PdfGrayColor(66);

            c.Item().Background(color).Height(10 + i * 3);
        }
    });
}));

Vous pouvez voir le résultat du code dans containers-column.pdf.

Lisez l'article Conteneurs composés pour des informations détaillées sur les fonctionnalités du conteneur Column.

Row

Les conteneurs Row aident à organiser un nombre illimité d'éléments horizontalement. Chaque élément d'une rangée est un conteneur. Pour cette raison, vous pouvez aligner du contenu de différents types.

PdfDocumentBuilder.Create().Generate("containers-row.pdf", doc => doc.Pages(page =>
{
    var rowItems = new[] { "three", "two", "one" };

    page.Content().Row(row =>
    {
        for (int index = 0; index < rowItems.Length; index++)
        {
            row.AutoItem().Text(rowItems[index]);

            if (index != rowItems.Length - 1)
                row.AutoItem().PaddingHorizontal(10).LineVertical(0.5);
        }
    });
}));

Vous pouvez voir le résultat du code dans containers-row.pdf.

L'article Conteneurs composés contient des informations détaillées sur les conteneurs Row.

Table

Utilisez les conteneurs Table pour présenter vos données les plus complexes. Commencez par définir au moins une colonne, puis remplissez les colonnes et les lignes en appelant plusieurs fois la méthode Cell.

Les tableaux peuvent avoir un en-tête et un pied de page. Les cellules d'un tableau peuvent s'étendre sur plusieurs colonnes et/ou lignes. Voici un code qui ajoute un tableau simple.

PdfDocumentBuilder.Create().Generate("containers-table.pdf", doc => doc.Pages(page =>
{
    page.Content().Table(t =>
    {
        t.Columns(c =>
        {
            for (int i = 0; i < 4; ++i)
                c.ConstantColumn(50);
        });

        for (int i = 0; i < 16; i++)
        {
            t.Cell()
                .Border(b => b.Thickness(0.5))
                .PaddingHorizontal(10)
                .Text($"{i + 1}");
        }
    });
}));

Le résultat du code est dans containers-table.pdf.

Découvrez toutes les fonctionnalités du conteneur Table dans l'article Conteneur Table.

Inlined

Le conteneur InlineContainer offre un moyen pratique de remplir une zone avec des éléments provenant d'une collection de conteneurs. Vous ajoutez simplement des éléments les uns après les autres et la bibliothèque les range les uns après les autres. S'il n'y a pas d'espace pour placer un élément, la bibliothèque commence une nouvelle ligne.

Plus d'informations sur les conteneurs InlineContainer se trouvent dans l'article Conteneurs composés.

Layers

Il existe des cas où il est préférable de placer le contenu sur plusieurs calques. Le conteneur LayerContainer remplit exactement cet objectif. Vous devez définir exactement une couche principale et un certain nombre de couches non principales. L'API Layout composera les calques dans le même ordre que vous les créez.

Lisez le Conteneurs composés pour plus de détails sur le type LayerContainer.

Element

Il s'agit d'un type particulier de contenu. Vous pouvez créer un élément dynamiquement et placer le résultat dans un conteneur.

Les éléments créés dynamiquement peuvent fournir une mise en page qui dépend du numéro de page, de la taille et d'autres propriétés.