Cette page peut contenir du texte traduit automatiquement.
Les 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à, la classe 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 placez 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 placer du texte ou une image dans un conteneur. À des fins d'alignement et de positionnement, vous pouvez placer un conteneur à l'intérieur d'un autre conteneur. Il existe des conteneurs qui offrent de la place pour plus d'un élément de contenu.
Les conteneurs sur une page sont représentés par des objets de la classe LayoutContainer. Utilisez cette classe pour définir la taille, la position, le contenu et le processus de rendu de vos conteneurs.
Cet article fait partie d'une série sur Layout API pour la génération de PDF. Si vous découvrez l'API, lisez d'abord la partie Getting Started with Layout API.
Comment fonctionnent les conteneurs
Vous commencez par obtenir un conteneur. Par exemple, en appelant la méthode PageLayout.Content. Cette méthode renvoie un conteneur qui n'occupe aucun espace et n'a ni contenu ni propriété définis. Utilisez les méthodes de la classe LayoutContainer pour configurer le conteneur.
Le point très important à comprendre est que toutes les méthodes de LayoutContainer placent du contenu dans le conteneur. Lorsque vous ajoutez du texte au conteneur, c'est attendu. Mais que devient le contenu lorsque vous définissez une indentation 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 inversement. 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 construire la mise en page résultante.
Le résultat du code suivant peut vous surprendre, mais prenez 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 d'un document ne se limite pas à l'agencement du texte et des images. Un document bien conçu produit non seulement une communication efficace, mais aussi visuellement attrayante.
Avec Layout API, vous pouvez appliquer une couleur d'arrière-plan à n'importe quel conteneur. Cela aide à établir une hiérarchie dans 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. En plus des lignes pleines, Layout API prend en charge les lignes qui utilisent des motifs de tirets.
Le résultat du code ci-dessus se trouve 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 abrégée simple 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 du segment.
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 segments avec des styles différents dans un même bloc de texte. La classe TextContainer fournit des méthodes pour insérer des images et d'autres éléments entre les segments 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
Layout API fournit des méthodes pour créer des objets Image à partir de données d'image dans un fichier ou un flux. N'importe quel 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 influencent l'apparence de l'image à l'intérieur du conteneur.
La bibliothèque peut charger uniquement des images dans des formats raster : 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 tout type à l'intérieur d'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 du contenu et des propriétés de l'élément.
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 composites 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 ligne est un conteneur. De ce fait, vous pouvez placer du contenu de différents types dans une ligne.
var rowItems = new[] { "three", "two", "one" };
PdfDocumentBuilder.Create().Generate("containers-row.pdf", doc => doc.Pages(page =>
{
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 composites contient des informations détaillées sur les conteneurs Row.
Table
Utilisez les conteneurs Table pour mettre en page vos données les plus complexes. Commencez par définir au moins une colonne, puis remplissez les colonnes et les lignes en appelant la méthode Cell plusieurs fois.
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 se trouve dans containers-table.pdf.
Lisez toutes les fonctionnalités du conteneur Table dans l'article Conteneur de tableau.
Inlined
Le type de conteneur InlineContainer fournit un moyen pratique de remplir une zone avec des éléments provenant d'une collection de conteneurs. Il suffit d'ajouter les éléments les uns après les autres, et la bibliothèque les place sur une ligne 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.
Vous trouverez plus d'informations sur les conteneurs InlineContainer dans l'article Conteneurs composites.
Layers
Dans certains cas, il est préférable de placer le contenu sur plusieurs couches. Le type de conteneur LayerContainer répond exactement à ce besoin. Vous devez définir exactement une couche principale et un nombre quelconque de couches non principales. Layout API composera les couches dans le même ordre que celui dans lequel vous les créez.
Lisez Conteneurs composites pour plus de détails sur le type LayerContainer.
Element
Il s'agit d'un type de contenu particulier. 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.