Cette page peut contenir du texte traduit automatiquement.
Comment mettre en page des pages PDF
La méthode PdfDocumentBuilder.Generate fournit un objet du type Document à sa délégation. Utilisez la méthode Pages de cet objet pour construire les pages de votre document. Vous devez fournir à la méthode une délégation qui accepte un paramètre de type PageLayout.
Un seul appel à la méthode suffit si toutes les pages de votre document PDF ont la même mise en page. Si votre document contient des mises en page différentes, utilisez plus d’un appel à la méthode Pages. Par exemple, vous pouvez appeler la méthode une fois pour mettre en page une page de couverture. Puis appelez de nouveau la méthode pour décrire le corps du rapport.
Chaque appel à Pages crée au moins une page. La page créée peut être vide s’il n’y a aucun contenu fourni pour elle.
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 Premiers pas avec Layout API.
Emplacements de contenu
Pour décrire la mise en page des pages, utilisez des conteneurs prédéfinis. Je les appelle aussi emplacements de contenu. Vous pouvez accéder à ces conteneurs en appelant des méthodes d’un objet PageLayout.
Il y a trois emplacements principaux : Content, Header et Footer. Et deux emplacements pour du contenu supplémentaire : Background et Foreground. Par défaut, les cinq conteneurs sont vides et n’occupent aucun espace sur la page. Vous répartissez le contenu de votre page entre les emplacements selon vos besoins.
Lisez l’article Les conteneurs et leur contenu pour savoir comment mettre en page vos pages à l’aide de conteneurs.
En-tête et pied de page
Vous ne serez pas surpris d’apprendre que le contenu de l’en-tête et du pied de page va dans les emplacements Header et Footer, respectivement. L’API répète ces emplacements au-dessus et au-dessous du contenu principal sur chaque page générée. Layout API ne répartit jamais le contenu de l’en-tête ou du pied de page entre plusieurs pages. Vous obtiendrez une LayoutException si un en-tête ou un pied de page ne tient pas sur une page.
Contenu principal
Le contenu principal de la page, comme les images, les tableaux et le texte, va dans l’emplacement Content. Layout API répartit automatiquement ce contenu sur plusieurs pages.
Le code suivant affecte un contenu textuel simple à tous les emplacements de contenu principal. Le code définit également des couleurs d’arrière-plan pour les emplacements.
PdfDocumentBuilder.Create().Generate("pages-main-slots.pdf", doc => doc.Pages(pages => {
pages.Header()
.Text("This text goes to the header")
.BackgroundColor(new PdfRgbColor(66, 135, 245));
pages.Content()
.Text("The main content goes in this slot")
.BackgroundColor(new PdfRgbColor(242, 233, 206));
pages.Footer()
.Text("This is the footer contents")
.BackgroundColor(new PdfRgbColor(194, 192, 188));
}));
Consultez le résultat du code dans pages-main-slots.pdf.
Comme vous pouvez le voir, chaque emplacement n’occupe qu’une partie de la page. La zone exacte dépend du contenu à l’intérieur de l’emplacement. L’emplacement Header est collé en haut de la page. L’emplacement Content commence immédiatement après Header. L’emplacement Footer est collé en bas.
Contenu supplémentaire
Les conteneurs Background et Foreground fournissent des conteneurs utilisables pour les filigranes, les superpositions et les arrière-plans. Tout le contenu de l’emplacement Background passe sous l’en-tête, le pied de page et le contenu principal d’une page. Le contenu de l’emplacement Foreground recouvre tout ce qui est ajouté à la page.
Ces conteneurs occupent toute la page. C’est la particularité de ces conteneurs. L’API répète leur contenu sur chaque page générée. Exactement comme elle le fait pour les conteneurs d’en-tête et de pied de page.
J’ai ajouté quelques lignes au code ci-dessus pour montrer comment utiliser les conteneurs Foreground et Background.
PdfDocumentBuilder.Create().Generate("pages-all-slots.pdf", doc => doc.Pages(pages => {
// ...
pages.Background()
.Background(new PdfRgbColor(208, 227, 204));
pages.Foreground()
.Rotate(45)
.Text(new string(' ', 30) + "Your watermark could go here, in the foreground");
}));
Pour le conteneur Background, je ne fournis aucun texte ni autre contenu. Je spécifie seulement la couleur d’arrière-plan. Tout ce qui se trouve sous l’en-tête, le contenu principal et le pied de page affichera cette nuance de vert.
Je fais pivoter le contenu du conteneur Foreground et j’y ajoute du texte. En raison des espaces initiaux, le texte ne recouvre pas le contenu de l’en-tête ou du pied de page. Le contenu de tous les conteneurs est visible sur la page.
Vous pouvez voir le résultat du code dans pages-all-slots.pdf.
Paramètres
Jusqu’à présent, tous les extraits de code se concentraient sur les conteneurs qui composent les pages. Il est temps de voir comment personnaliser les pages elles-mêmes, plutôt que leurs emplacements de contenu.
Pour configurer les pages, utilisez les méthodes de la classe PageLayout. Rappelez-vous qu’un objet PageLayout peut décrire plus d’une page. Les appels de méthode affecteront toutes les pages que vous décrivez.
Taille
Probablement, le paramètre le plus fondamental est la taille de la page. Vous pouvez utiliser la méthode Size pour spécifier l’une des tailles prédéfinies pour vos pages. Il existe toutes les tailles usuelles comme A4, Ledger ou Monarch Envelope.
En option, vous pouvez spécifier une orientation pour les pages. Il est possible de définir une taille personnalisée de page en fournissant sa largeur et sa hauteur en points.
Marges
Les marges de page peuvent contribuer à la lisibilité, à l’esthétique et à la composition globale de vos pages.
Définissez toutes les marges à la même valeur en points à l’aide de la méthode Margin. Utilisez les méthodes MarginVertical et MarginHorizontal pour définir uniquement les marges verticales ou horizontales. Utilisez les méthodes MarginLeft/Top/Right/Bottom pour spécifier chaque marge indépendamment.
Style du texte
Layout API fournit la classe TextStyle pour créer des styles de texte. Vous créez et appliquez des styles au texte pour obtenir l’apparence souhaitée.
Dans certains cas, une grande partie du texte de vos pages utilise le même style. Vous pouvez définir ce style comme style de texte par défaut pour les pages. Le style par défaut affecte tout le texte dans les emplacements de contenu principal. Mais vous pouvez remplacer le style par défaut pour certains éléments. Il suffit d’appliquer un autre style aux morceaux de texte qui doivent apparaître différemment.
PdfDocumentBuilder.Create().Generate("pages-text-styles.pdf", doc =>
{
var defaultStyle = TextStyle.Parent.FontSize(30);
var tightSpacing = TextStyle.Parent.LetterSpacing(-0.1);
doc.Pages(pages =>
{
pages.TextStyle(defaultStyle);
pages.Content().Text(t =>
{
t.Line("This line uses the default text style.");
t.Line("This line uses a tight letter spacing.").Style(tightSpacing);
t.Line("This line uses the default text style, again.");
});
});
});
Vous pouvez voir le résultat du code dans pages-text-styles.pdf.
Veuillez noter que vous pouvez configurer des styles de texte à l’échelle du document à l’aide de la méthode Document.Typography. Chaque propriété de la classe Typography définit un style pour un cas d’usage. Ces styles remplacent le style spécifié par la méthode PageLayout.TextStyle. Par exemple, la propriété Typography.Body remplace le style par défaut pour le texte dans les conteneurs Content.
Direction du contenu
Certaines langues s’écrivent de droite à gauche. Layout API gère sans problème le texte dans ces langues. Mais vous devrez spécifier explicitement la direction du texte.
Si la majeure partie du texte de vos pages est dans une langue RTL, vous pouvez définir la direction de contenu de droite à gauche comme direction par défaut pour les pages. Vous pourrez spécifier une direction différente pour n’importe quel conteneur de vos pages.
PdfDocumentBuilder.Create().Generate("pages-content-direction.pdf", doc =>
{
var defaultTextStyle = doc.TextStyleWithFont(SystemFont.Family("Calibri"));
doc.Pages(pages =>
{
pages.Size(PdfPaperSize.A6).TextStyle(defaultTextStyle);
pages.ContentFromRightToLeft();
pages.Content().Column(column =>
{
column.Item()
.ContentFromLeftToRight()
.Text("There are languages written from right to left.");
column.Item()
.Text("هناك لغات تكتب من اليمين إلى اليسار.");
column.Item()
.Text("יש שפות שנכתבות מימין לשמאל.");
});
});
});
Dans le code ci-dessus, j’ai défini la direction de contenu de droite à gauche comme direction par défaut. Pour le conteneur avec la version anglaise de la phrase, je change la direction en de gauche à droite. Vous pouvez voir le résultat du code dans pages-content-direction.pdf.
Numéros de page
Lors de la génération d’un PDF, Layout API calcule automatiquement le numéro de page courant. Elle calcule aussi le nombre total de pages du document. Vous pouvez obtenir ces nombres en appelant les méthodes CurrentPageNumber et PageCount de n’importe quel conteneur de texte. Peu importe que le conteneur se trouve dans l’en-tête, le pied de page ou l’emplacement de contenu principal.
PdfDocumentBuilder.Create().Generate("pages-page-numbers.pdf", doc => doc.Pages(pages =>
{
pages.Content().Text(t =>
{
t.Span("This line is on page ");
t.CurrentPageNumber();
t.Line();
t.Line("Check the footer.");
});
pages.Footer().Row(r =>
{
r.AutoItem().Text("Created with Docotic.Pdf Layout API");
r.RelativeItem(2).Text(t =>
{
t.AlignRight();
t.Span("Page ");
t.CurrentPageNumber();
t.Span(" of ");
t.PageCount();
});
});
}));
Le résultat du code se trouve dans pages-page-numbers.pdf.
Les deux méthodes renvoient une instance TextPageNumber que vous pouvez utiliser pour formater les nombres.
Ajouter un en-tête et un pied de page aux documents PDF montre comment appliquer un formatage personnalisé aux numéros de page.
Exemple de code
Nous avons quelques applications d’exemple qui couvrent les fonctionnalités mentionnées plus haut plus en détail. Prenez le temps de les examiner.