Comment mettre en page des pages PDF

La méthode PdfDocumentBuilder.Generate fournit un objet de type Document à son délégué. Utilisez la méthode Pages de cet objet pour construire les pages de votre document. Vous devez fournir un délégué qui accepte un paramètre de type PageLayout à la méthode.

Un seul appel à la méthode suffit si toutes les pages de votre document PDF ont la même mise en page. Si vous avez des mises en page différentes dans votre document, utilisez plusieurs appels à la méthode Pages. Par exemple, vous pouvez appeler la méthode une fois pour mettre en page une page de garde. Appelez ensuite à 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 si aucun contenu n'est fourni pour elle.

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.

Emplacements de contenu

Pour décrire la disposition des pages, utilisez des conteneurs prédéfinis. Je les appelle aussi des emplacements de contenu. Vous pouvez accéder à ces conteneurs en appelant les 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 de page. Vous répartissez le contenu de votre page entre les emplacements en fonction de vos besoins.

Lisez l'article 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 de savoir que le contenu de l'en-tête et du pied de page est respectivement placé dans les emplacements Header et Footer. L'API répète ces emplacements au-dessus et en dessous du contenu principal de chaque page générée. L'API Layout ne divise jamais le contenu de l'en-tête ou du pied de page entre les 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 de la page principale, comme les images, les tableaux et le texte, va dans l'emplacement Content. L'API de mise en page divise automatiquement ce contenu en pages.

Le code suivant attribue du contenu textuel simple à tous les emplacements de contenu principaux. Le code définit également les couleurs d'arrière-plan des 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));
}));

Vérifiez le résultat du code dans pages-main-slots.pdf.

Comme vous pouvez le constater, chaque emplacement n'occupe qu'une partie de la page. La zone exacte dépend du contenu à l’intérieur de la fente. L'emplacement Header reste en haut de la page. L'emplacement Content commence immédiatement après Header. L'emplacement Footer reste en bas.

Contenu additionnel

Background et Foreground fournissent des conteneurs utilisables pour les filigranes, les superpositions et les arrière-plans. Tout le contenu de l'emplacement Background se situe sous l'en-tête, le pied de page et le contenu principal d'une page. Le contenu de l'emplacement Foreground couvre 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 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 ou autre. Je précise uniquement 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 dans le conteneur Foreground et j'y ajoute du texte. En raison des espaces de début, le texte ne couvre 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. N'oubliez pas qu'un objet PageLayout peut décrire plusieurs pages. Les appels de méthodes affecteront toutes les pages que vous décrivez.

Taille

Le paramètre le plus élémentaire est probablement 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 tous les formats habituels comme A4, Ledger ou Monarch Envelope.

Vous pouvez éventuellement spécifier une orientation pour les pages. Il est possible de définir une taille de page personnalisée 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 sur la même valeur en points en utilisant 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 de texte

L'API Layout 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.

Il existe des cas où une grande partie d'un texte sur 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 des principaux emplacements de contenu. Mais vous pouvez remplacer le style par défaut pour certains éléments. Appliquez simplement un autre style aux morceaux de texte qui devraient avoir un aspect différent.

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 en utilisant la méthode Document.Typography. Chaque propriété de la classe Typography définit un style pour un cas d'utilisation. 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 du texte dans les conteneurs Content.

Orientation du contenu

Il existe des langues qui s'écrivent de droite à gauche. L'API Layout gère très bien le texte dans ces langues. Mais vous devrez spécifier explicitement la direction du texte.

Si la plupart du texte de vos pages est dans une langue RTL, vous pouvez définir la direction de droite à gauche comme direction de contenu par défaut pour les pages. Vous pourrez spécifier une direction différente pour n'importe quel conteneur dans 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 du contenu par défaut de droite à gauche. Pour le conteneur contenant la version anglaise de la phrase, je change la direction 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, l'API Layout calcule automatiquement le numéro de page actuel. Il calcule également le nombre total de pages du document. Vous pouvez obtenir les numéros en appelant les méthodes CurrentPageNumber et PageCount de n'importe quel conteneur de texte. Peu importe si 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 est dans pages-page-numbers.pdf.

Les deux méthodes renvoient TextPageNumber que vous pouvez utiliser pour formater les nombres.

L'exemple Ajouter un en-tête et un pied de page aux documents PDF montre comment appliquer une mise en forme personnalisée aux numéros de page.

Exemple de code

Nous avons quelques exemples d'applications qui couvrent plus en détail les fonctionnalités susmentionnées. Veuillez prendre le temps de les vérifier.

• Mise en page dans les documents PDF
• Ajouter un en-tête et un pied de page aux documents PDF
• Style du texte