Générateur de PDF .NET

Traduit par Bit Miracle. Article original de Sergey Bobrovsky

Mis à jour le 28 avril 2026

Grâce à Docotic.Pdf, vous pouvez générer des documents PDF en les composant à partir d'éléments structurels tels que des pages, des conteneurs, des blocs de texte, des images, des liens, des en-têtes, des pieds de page, des tableaux, des listes, etc. Ces éléments sont accessibles via l'API Layout de haut niveau, fournie par l'extension gratuite Layout pour Docotic.Pdf. L'API prend également en charge les composants personnalisés réutilisables.

L'API Layout permet de définir des documents entièrement en C# ou VB.NET grâce à une approche fluide. Ainsi, le générateur PDF fourni par l'extension peut produire des documents aux mises en page d'une complexité arbitraire, allant de simples pages à des rapports PDF très structurés.

Principes de base de la génération de PDF

Pour générer des documents PDF à l'aide de l'API Layout, vous avez besoin de l'extension gratuite Layout. Une clé de licence est également requise pour utiliser la bibliothèque principale et les extensions. Vous pouvez utiliser une clé d'essai gratuite ou une clé payante.

Installez le module complémentaire

La méthode recommandée consiste à installer le module complémentaire depuis NuGet.

Install-Package BitMiracle.Docotic.Pdf.Layout

Le gestionnaire de paquets gérera automatiquement les dépendances.

Si vous préférez installer l'extension manuellement, commencez par télécharger l'archive ZIP contenant les fichiers binaires Docotic.Pdf. Décompressez l'archive et ajoutez les références aux DLL suivantes :

• BitMiracle.Docotic.Pdf.dll
• BitMiracle.Docotic.Pdf.Layout.dll (située dans le sous-dossier Layout add-on).

Obtenir une clé de licence

Pour essayer la bibliothèque, demandez une clé de licence gratuite à durée limitée en remplissant le formulaire sur la page de téléchargement de Docotic.Pdf. Si vous avez déjà acheté une licence, utilisez le code qui vous a été fourni après l'achat.

L'extension Layout est gratuite et ne nécessite pas de licence supplémentaire. Vous pouvez utiliser l'API Layout avec votre licence Docotic.Pdf actuelle.

Bonjour le monde ! avec l'API Layout

Voici un exemple de code qui utilise l'API pour générer un PDF contenant la phrase classique « Hello, world!» :

BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

PdfDocumentBuilder.Create().Generate("hello.pdf", doc => doc.Pages(pages =>
{
    pages.Content().Text("Hello, world!");
}));

Ce code génère un PDF d'une seule page avec le texte dans le coin supérieur gauche.

Comprendre l'exemple de code

L'exemple commence par l'ajout d'une clé de licence. Sans licence, la bibliothèque Docotic.Pdf ne générera aucun fichier. Le code de génération du PDF commence à la ligne suivante.

Le code crée une instance du générateur de documents en appelant la méthode statique PdfDocumentBuilder.Create(). L'appel à la méthode Generate lance le processus de génération du PDF. Cette méthode accepte deux paramètres : le nom du fichier à produire et un délégué de type Action<Document>. L'extension génère hello.pdf suite à l'appel à Generate.

Pour déterminer la mise en page du PDF, le générateur de documents appelle le délégué avec une instance de Document. Le code du délégué compose le contenu du document. Dans cet exemple, le délégué utilise la méthode Pages pour fournir au générateur un autre délégué qui définit la mise en page du document.

Le générateur appelle le délégué fourni à la méthode Pages avec une instance de PageLayout. Cette instance représente une ou plusieurs pages du document. Le nombre exact de pages dépend du contenu qui y est ajouté.

Le délégué de page appelle la méthode Content pour accéder au conteneur de mise en page du contenu principal de la ou des pages. Un appel enchaîné à la méthode Text du conteneur ajoute l'exemple de texte à la page. Consultez le guide sur les conteneurs de mise en page pour une explication détaillée de leur fonctionnement.

Le générateur de documents répartit automatiquement le contenu sur plusieurs pages, créant ainsi autant de pages que nécessaire pour contenir toutes les données ajoutées au conteneur de mise en page du contenu principal. Dans cet exemple, une seule page suffit ; le document de sortie contient donc exactement une page.

Tâches courantes au-delà de l'échantillon de base

L'exemple de code crée d'abord une instance de PdfDocumentBuilder, puis appelle la méthode Generate pour générer un PDF. Vous pouvez configurer le générateur avant le début de la génération du PDF.

Par exemple, vous pouvez générer un PDF chiffré en fournissant un gestionnaire de chiffrement au générateur. Vous pouvez également spécifier des métadonnées à inclure dans le document généré. Pour plus de détails sur la personnalisation du générateur, consultez l'article dédié.

L'exemple de code utilise uniquement le conteneur de mise en page de l'emplacement de contenu principal, mais d'autres emplacements de contenu sont également disponibles. Voici la liste complète des méthodes PageLayout permettant d'accéder aux emplacements de contenu :

• Background() : renvoie le calque d'arrière-plan, qui est recouvert par d'autres contenus.
• Header() : renvoie l'en-tête commun à toutes les pages.
• Content() : renvoie l'emplacement de contenu principal de la page.
• Footer() : renvoie le pied de page commun à toutes les pages.
• Foreground() : renvoie le calque de premier plan, qui apparaît au-dessus des autres contenus.

Seul le contenu de l'emplacement principal influe sur le nombre de pages du PDF généré. Le générateur de documents répète tous les emplacements, à l'exception de celui fourni par Content(), sur chaque page. Pour plus d'informations sur les emplacements de contenu, consultez l'article sur la mise en page.

De nombreux documents utilisent des mises en page différentes selon les pages. Par exemple, la première page peut avoir une mise en page de type couverture, tandis que les pages suivantes utilisent une mise en page plus simple. Certains documents incluent des pages spécifiques pour les tableaux ou appliquent des arrière-plans différents selon la section. Pour générer de tels documents avec Docotic.Pdf et l'extension Layout, appelez la méthode Document.Pages plusieurs fois. Vous trouverez un exemple fonctionnel dans notre dépôt d'exemples.

Organisation du code

Pour un code court, comme dans l'exemple, il est tout à fait acceptable d'enchaîner les appels et d'utiliser des lambdas imbriquées. Cependant, pour un code plus complexe, il peut être plus judicieux de le diviser en méthodes distinctes. Cela facilite la lecture et la maintenance du code.

Voici à quoi ressemble l'exemple « Hello, world!» lorsque son code est divisé en méthodes.

public void GeneratePdf()
{
    BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

    PdfDocumentBuilder.Create().Generate("hello.pdf", BuildDocument);
}

private void BuildDocument(Document doc)
{
    doc.Pages(BuildPages);
}

private void BuildPages(PageLayout pages)
{
    pages.Content().Text("Hello, world!");
}

Pourquoi générer des PDF avec l'API Docotic.Pdf Layout

L'API Layout est une solution moderne et conviviale pour les développeurs permettant de générer des PDF à partir de blocs de construction composables, sans nécessiter de connaissances approfondies du format PDF. Elle assure une mise en page performante et un comportement déterministe et prévisible. Cette API est idéale pour la génération de documents en grande quantité.

L'API est disponible avec Docotic.Pdf et l'extension Layout gratuite. Docotic.Pdf et l'extension Layout sont des DLL entièrement managées, sans aucun bloc de code non sécurisé. L'API Layout est implémentée sans aucune dépendance externe tierce, comme un navigateur ou les binaires Skia, ce qui en fait une solution légère, peu gourmande en ressources, facile à déployer et à maintenir.

Présentation de l'API

L'API Layout est une API fluide et agréable à utiliser. Vous décrivez la mise en page de votre document entièrement en code, à l'aide d'éléments de mise en page flexibles. Le générateur organise ensuite votre contenu, le pagine automatiquement et génère le PDF.

L'extension Layout utilise un système de mise en page déclaratif basé sur les flux. Ses éléments incluent des listes, des colonnes, des lignes, des tableaux, des images, des blocs de texte, des en-têtes et pieds de page, des conteneurs, et bien plus encore. Au lieu de placer manuellement les éléments à des coordonnées exactes, vous décrivez leur comportement. Le générateur de documents calcule alors la mise en page finale et crée le PDF.

Ce système de mise en page basé sur les flux garantit une adaptation de la mise en page à la taille de la page et au contenu. Grâce à ce système, l'extension excelle dans la création de mises en page complexes, structurées et basées sur des règles. Vous pouvez imbriquer différents types de conteneurs et construire des structures sophistiquées sans nuire à la lisibilité.

Lorsque vous utilisez l'API Layout, vous pouvez chaîner la plupart des appels. Cela permet d'obtenir un code plus compact et expressif qu'avec les API traditionnelles. L'ordre des appels dans une chaîne est important. Tout est fortement typé, garantissant la sécurité à la compilation et facilitant la refactorisation du code. Vous pouvez également effectuer des tests unitaires sur le code utilisant l'API Layout.

Pour une implémentation encore plus concise de votre mise en page, vous pouvez étendre l'API avec vos propres méthodes et créer un DSL clair et expressif.

Pour plus d'informations sur le positionnement et la création de DSL, consultez l'article expliquant comment contrôler la taille, la position, l'alignement et le comportement de rendu des conteneurs.

Versions .NET et prise en charge de la plateforme

Vous pouvez utiliser l'API Layout dans les projets ciblant .NET Standard 2.1 et les frameworks plus récents. Autrement dit, l'extension Layout est compatible avec .NET 5 à .NET 10. De plus, .NET Core 3.0 et versions ultérieures sont pris en charge.

Vous pouvez générer des PDF avec l'API Layout dans les applications ASP.NET Core, MAUI, Unity, Xamarin et les applications console. Docotic.Pdf, avec l'extension Layout, permet de générer des PDF sous Windows, macOS et Linux.

Plateformes cloud et images Docker

Docotic.Pdf, avec son extension Layout, est compatible avec les environnements cloud Azure et AWS, y compris les configurations sans serveur. La bibliothèque et l'extension prennent entièrement en charge les changements de matériel dynamiques, la mise à l'échelle automatique et d'autres fonctionnalités d'exécution natives du cloud.

Dans la plupart des scénarios cloud, une licence illimitée est requise. La FAQ sur les licences explique comment choisir la licence appropriée pour les applications cloud.

L'API Layout fonctionne directement dans les conteneurs Docker. Aucune configuration particulière n'est nécessaire pour générer des PDF lorsque la bibliothèque et l'extension Layout sont exécutées dans un conteneur.

Ajout de texte aux fichiers PDF

Le texte est un élément fondamental de tout document PDF. Vous pouvez utiliser les méthodes Text de la classe LayoutContainer pour ajouter du texte à un emplacement de contenu.

Texte s'étend

Dans l'exemple « Hello, world », j'ai utilisé la surcharge LayoutContainer.Text(string) pour ajouter du texte au contenu principal de la page. Voyons maintenant une autre surcharge de la méthode Text.

public static void GenerateTextPdf()
{
    PdfDocumentBuilder.Create().Generate("text-spans.pdf", doc => doc.Pages(pages =>
    {
        pages.Content().Text(AddTextSpans);
    }));
}

private static void AddTextSpans(TextContainer text)
{
    text.Line("About VB.NET")
        .Style(t => t.Strong);

    text.Span("VB.NET is a multi-paradigm, object-oriented language ");
    text.Span("that runs on .NET, Mono, and the ");
    text.Hyperlink(
        ".NET Framework",
        new Uri("https://dotnet.microsoft.com/download/dotnet-framework"));
    text.Line(".");

    text.Span("Released by Microsoft in 2002, ");
    text.Line("it continues the lineage of the original Visual Basic language.");
}

Ce code utilise les méthodes Span et Line de la classe TextContainer pour ajouter du texte à la ligne courante. La méthode Line complète également cette ligne. L'exemple utilise aussi la méthode Hyperlink pour associer un lien vers une ressource externe à un élément de texte spécifique.

Remarquez comment l'exemple applique une mise en forme stricte à la première ligne grâce à la méthode Style. Explorons plus en détail le concept des styles de texte.

Styles de texte

Les styles de texte permettent de personnaliser l'apparence du texte. La classe TextStyle propose des méthodes pour modifier la taille de la police, l'espacement des lettres, les couleurs et d'autres propriétés du texte. Les objets TextStyle sont immuables ; chaque appel de méthode crée donc une nouvelle instance de style. Vous pouvez appliquer des styles de texte à différents niveaux de mise en page.

PdfDocumentBuilder.Create().Generate("text-styles.pdf", doc =>
{
    doc.Pages(pages =>
    {
        pages.TextStyle(TextStyle.Parent.FontSize(30));

        pages.Content()
            .TextStyle(TextStyle.Parent.FontColor(new PdfRgbColor(0, 0, 255)))
            .Text(text =>
            {
                text.Span("Hello,");

                text.Span("World!")
                    .Style(TextStyle.Parent.Underline());
            });
    });
});

La propriété TextStyle.Parent renvoie un style spécial dans lequel toutes les propriétés de texte sont indéfinies. Dans l'exemple ci-dessus, le code affiche « Hello, World!» en bleu, le deuxième mot étant souligné, avec une police de 30 points.

Ceci est possible car le code :

• définit la taille de la police à 30 points au niveau de la page,
• puis définit la couleur du texte en bleu pour l'emplacement de contenu principal,
• enfin applique le style de soulignement à la dernière zone de texte.

Chaque style suivant hérite des précédents via la propriété TextStyle.Parent.

À l'aide des méthodes de la classe TextStyle, vous pouvez, entre autres, modifier le sens d'écriture du texte (de droite à gauche). Consultez un autre exemple d'utilisation de l'héritage de styles de texte dans notre dépôt d'exemples.

Typographie

La classe TextStyle permet de personnaliser toutes les propriétés du texte, à l'exception de la police associée. Pour modifier la police par défaut, utilisez les méthodes Document.TextStyleWithFont afin de créer un style de texte basé sur une police spécifique. Vous pouvez utiliser une police installée sur le système d'exploitation ou en charger une depuis un fichier ou un flux.

Après avoir créé un style basé sur une police, vous pouvez lui appliquer des propriétés optionnelles supplémentaires, puis utiliser le style obtenu sur une zone de texte. Cet exemple C# illustre l'utilisation d'une police système.

PdfDocumentBuilder.Create().Generate("text-style-with-font.pdf", doc =>
{
    var font = SystemFont.Family("Calibri");
    var style = doc.TextStyleWithFont(font).FontSize(30);

    doc.Pages(pages =>
    {
        pages.Content().Text(text =>
        {
            text.Span("Hello,");

            text.Span("World!")
                .Style(style);
        });
    });
});

La méthode TextStyleWithFont inclut un paramètre optionnel qui spécifie comment la police doit être incorporée dans le document généré. Par défaut, la bibliothèque :

• incorpore les glyphes utilisés pour les polices TrueType/OpenType,
• incorpore tous les glyphes pour les polices Type1 et CFF,
• n'incorpore pas les glyphes des polices PDF intégrées (polices Base14).

En raison de ces paramètres par défaut, les documents utilisant des polices TrueType et OpenType peuvent rester de petite taille même avec des polices de grande taille. Vous pouvez également spécifier un chargeur de polices personnalisé, des polices de secours et un gestionnaire pour les glyphes manquants. Consultez l'exemple de code dans notre dépôt d'exemples pour plus de détails sur la gestion des polices dans les documents PDF.

L'API Layout fournit une collection de styles prédéfinis, accessibles et modifiables via la classe Typography.

PdfDocumentBuilder.Create().Generate("typography.pdf", doc =>
{
    doc.Typography(t =>
    {
        var fontsPath = Environment.GetFolderPath(Environment.SpecialFolder.Fonts);
        var arialFont = new FileInfo(Path.Combine(fontsPath, "arial.ttf"));

        t.Document = doc.TextStyleWithFont(arialFont);
        t.Header = t.Parent.FontSize(20).FontColor(new PdfGrayColor(20));
        t.Footer = t.Footnote;
    });

    doc.Pages(pages =>
    {
        pages.Header().AlignCenter().Text("Header");

        pages.Content().Text(t =>
        {
            t.Line("Title").Style(t => t.Title);
            t.Line("Heading 1").Style(t => t.Heading1);
            t.Line("Regular");
        });

        pages.Footer()
            .Height(20)
            .AlignCenter()
            .Text(t => t.CurrentPageNumber());
    });
});

Je recommande de remplacer les styles prédéfinis en configurant la typographie pour l'ensemble du document, bien que cela ne soit pas obligatoire et que vous puissiez toujours appliquer des styles de texte au niveau de l'élément text-span.

Avec la classe Typography, il n'est pas nécessaire de stocker les références de style de texte dans des variables. Vous enregistrez plutôt les styles requis à l'aide des méthodes Document.Typography et vous y accédez ensuite via les propriétés de l'objet Typography. Consultez l'exemple de typographie pour découvrir comment utiliser des styles de texte prédéfinis et personnalisés lors de la génération de documents PDF.

Utilisation des en-têtes et des pieds de page

De nombreux documents PDF courants, tels que des rapports ou des factures, comportent des en-têtes et des pieds de page. Cette section explique comment les ajouter à un PDF.

public static void GeneratePdfWithHeaderAndFooter()
{
    PdfDocumentBuilder.Create()
        .Generate("header-footer.pdf", doc => doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6).Margin(10);

        BuildPagesHeader(pages.Header());
        BuildPagesFooter(pages.Footer());

        pages.Content().Text("Hello, world!");
    }));
}

public static void BuildPagesHeader(LayoutContainer header)
{
    header.TextStyle(TextStyle.Parent.FontSize(8))
        .AlignRight()
        .Text(t =>
        {
            t.Line($"Created by: {Environment.UserName}");
            t.Line($"Date: {DateTime.Now}");
        });
}

public static void BuildPagesFooter(LayoutContainer footer)
{
    footer.AlignRight().Text(text =>
    {
        text.Style(t => t.Parent.FontColor(new PdfRgbColor(255, 0, 0)));

        text.CurrentPageNumber();
        text.Span(" / ");
        text.PageCount();
    });
}

La méthode BuildPagesHeader définit une taille de police plus petite pour le texte d'en-tête. Elle utilise deux lignes pour le contenu de l'en-tête : l'une avec le nom de l'utilisateur actuel et l'autre avec la date du jour. Le texte est aligné à droite.

Notez que le code ne spécifie aucune taille explicite pour l'en-tête. Il occupe toute la largeur de la page, marges gauche et droite déduites, et sa hauteur dépend de la hauteur des lignes de texte.

La méthode BuildPagesFooter montre comment insérer le numéro de la page actuelle dans le pied de page du PDF. La bibliothèque calcule automatiquement le numéro de la page actuelle et le nombre total de pages. Vous pouvez accéder à ces valeurs à l'aide des méthodes CurrentPageNumber et PageCount d'un objet TextContainer.

L'API Layout permet également de formater les numéros de page. Par exemple, vous pouvez afficher des numéros de page hexadécimaux comme ceci :

text.CurrentPageNumber().Format(p => "0x" + p?.ToString("x2"));

Notre dépôt d'exemples contient un autre exemple d'ajout d'un en-tête et d'un pied de page à un PDF. Cet exemple formate les numéros de page en chiffres romains.

Insertion d'images

Comme le dit l'adage, une image vaut mille mots. Dans les devis ou les reçus, vous incluez souvent le logo de votre entreprise ou une autre image importante. Pour cet exemple, j'utiliserai une image simple et esthétique.

Pour utiliser une image, vous devez d'abord l'ajouter au document. La bibliothèque peut charger des images à partir d'un fichier ou d'un flux. Seuls les formats raster sont pris en charge : PNG, JPEG, JPEG 2000, BMP, GIF et TIFF.

Une fois que vous disposez d'un objet Image, vous pouvez l'utiliser comme contenu d'un ou plusieurs conteneurs de mise en page en appelant la méthode Image du conteneur. Vous pouvez redimensionner, faire pivoter, ajouter un espacement et positionner l'image comme n'importe quel autre contenu.

PdfDocumentBuilder.Create().Generate("image-with-text.pdf", doc =>
{
    var imageFile = new FileInfo("red-flowers-at-butterfly-world.jpg");
    var image = doc.Image(imageFile);

    doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6);
        pages.Content().Column(c =>
        {
            c.Spacing(20);

            c.Item()
                .AlignCenter()
                .Text("Hello, world!")
                .FontSize(20);

            c.Item()
                .AlignCenter()
                .MaxWidth(200)
                .Image(image);
        });
    });
});

L'exemple de code utilise à la fois du texte et une image dans l'emplacement de contenu principal. Cependant, un conteneur de mise en page ne peut contenir que du texte ou qu'une image. Pour inclure les deux dans l'emplacement de contenu principal de la page, vous avez besoin d'un conteneur composé.

J'utilise un conteneur Column pour placer le texte et l'image verticalement, l'un après l'autre. La méthode Item du conteneur Column fournit un sous-conteneur. Un appel à Item crée un conteneur pour le texte, et un autre crée un conteneur pour l'image. Le conteneur composé, avec tous ses sous-conteneurs, devient le contenu principal.

Pour exécuter l'exemple de code, téléchargez l'image de fleur depuis notre dépôt d'exemples et placez-la dans le répertoire de travail de votre application.

Images en ligne

Si vous ne disposez que d'une URL d'image et non d'un fichier, téléchargez l'image dans un flux mémoire et créez un objet Image à partir de ce flux. L'exemple suivant illustre l'utilisation d'images en ligne avec l'API Layout.

public static async Task AddImageWithTextFromUrl()
{
    using var http = new HttpClient();
    using var stream = await http.GetStreamAsync("url/to/image");

    var memoryStream = new MemoryStream();
    await stream.CopyToAsync(memoryStream);
    memoryStream.Position = 0;

    PdfDocumentBuilder.Create().Generate("online-image-with-text.pdf", doc =>
    {
        var image = doc.Image(memoryStream);

        doc.Pages(pages =>
        {
            pages.Size(PdfPaperSize.A6);
            pages.Content().Column(c =>
            {
                c.Spacing(20);

                c.Item()
                    .AlignCenter()
                    .Text("Hello, world!")
                    .FontSize(20);

                c.Item()
                    .AlignCenter()
                    .MaxWidth(200)
                    .Image(image);
            });
        });
    });
}

Cette méthode effectuant un traitement asynchrone (téléchargement d'une image depuis une URL), elle est déclarée comme async Task et non comme void. Les appelants doivent attendre sa fin pour garantir la génération correcte du PDF. Dans votre code, une méthode similaire peut également renvoyer une valeur ; dans ce cas, elle serait déclarée comme async Task<TResult>.

Création de listes

Qu'est-ce qu'une liste ? On peut la considérer comme un ensemble d'éléments numérotés, écrits les uns en dessous des autres. L'API Layout ne propose pas de type de conteneur spécifique pour les listes, mais il est facile d'en implémenter une à l'aide d'autres conteneurs composés.

var dayNames = DateTimeFormatInfo.InvariantInfo.DayNames;
var dayNamesSpain = DateTimeFormatInfo.GetInstance(new CultureInfo("es-ES")).DayNames;

PdfDocumentBuilder.Create().Generate("list.pdf", doc => doc.Pages(pages =>
{
    pages.Size(PdfPaperSize.A6);
    pages.Content().Column(column =>
    {
        for (int i = 0; i < dayNames.Length; i++)
        {
            column.Item().Row(row =>
            {
                row.Spacing(5);
                row.AutoItem().Text($"{i + 1}.");
                row.RelativeItem().Text(t =>
                {
                    t.Line(dayNames[i]);
                    t.Line($"In Spain they call it {dayNamesSpain[i]}");
                });
            });
        }
    });
}));

L'exemple de code crée la liste sous forme de colonnes de lignes. Chaque ligne contient deux éléments : le premier (à gauche) affiche le numéro de l'élément, et le second (à droite) son texte. L'espacement entre les éléments de chaque ligne est défini explicitement.

Pour agencer les éléments, le conteneur Row doit soit spécifier explicitement la taille de chaque élément, soit la calculer. Dans cet exemple, les méthodes AutoItem et RelativeItem sont utilisées. Ainsi, le conteneur calcule la largeur nécessaire pour le premier élément, puis utilise la largeur restante pour le second.

Grâce à cette approche et en ajustant l'apparence des lignes selon vos besoins, vous pouvez créer une liste parfaitement adaptée à la mise en page et au style de votre document.

Tables de construction

De nombreux documents PDF contiennent des tableaux, ce qui n'est pas surprenant car les tableaux améliorent la clarté et l'organisation des données. Cette section explique comment créer un tableau dans un PDF à l'aide de l'API Layout.

public static void AddTable()
{
    PdfDocumentBuilder.Create().Generate("table.pdf", doc => doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6);

        var color = new PdfGrayColor(75);
        pages.Content().Padding(20).Table(t =>
        {
            t.Columns(c =>
            {
                c.RelativeColumn(4);
                c.RelativeColumn(1);
                c.RelativeColumn(4);
            });

            t.Header(h =>
            {
                h.Cell().Background(color).Text("Month");
                h.Cell().Background(color).Text("Days");
                h.Cell().Background(color).Text("First Day");
            });

            var year = DateTime.Now.Year;
            for (int yearDiff = 0; yearDiff < 4; yearDiff++)
            {
                for (int i = 11; i >= 0; i--)
                {
                    var stats = GetMonthStats(year - yearDiff, i);

                    t.Cell().Text(stats.Item1);
                    t.Cell().Text(stats.Item2);
                    t.Cell().Text(stats.Item3);
                }
            }
        });
    }));
}

private static (string, string, string) GetMonthStats(int year, int monthIndex)
{
    return (
        $"{DateTimeFormatInfo.InvariantInfo.MonthNames[monthIndex]} {year}",
        DateTime.DaysInMonth(year, monthIndex + 1).ToString(),
        new DateTime(year, monthIndex + 1, 1).DayOfWeek.ToString()
    );
}

L'exemple de code crée un tableau simple affichant des informations de base sur les mois de l'année en cours et des trois années précédentes. Il définit trois colonnes de largeurs relatives : les colonnes de gauche et de droite sont quatre fois plus larges que la colonne centrale.

Le code définit également l'en-tête du tableau en ajoutant des cellules d'en-tête et en spécifiant la couleur du texte et de fond de chaque cellule. Si le tableau ne tient pas sur une seule page, l'en-tête est répété sur chaque page où il se trouve. Ce comportement est visible dans le PDF généré par l'exemple de code.

Deux boucles simples sont utilisées pour construire les lignes. La boucle externe parcourt les années, et la boucle interne parcourt les mois en ordre inverse. La boucle interne récupère les informations de chaque mois, puis ajoute trois cellules pour former une ligne.

Pour plus de détails, vous pouvez consulter l'article qui explique en détail les fonctionnalités du conteneur Tableau.

Création de liens PDF internes

Les documents PDF prennent en charge les liens internes, permettant ainsi aux lecteurs d'accéder à d'autres sections du même fichier. Dans un lecteur PDF, ces liens apparaissent sous forme d'éléments texte ou image cliquables. Ils fonctionnent comme des hyperliens, mais au lieu de pointer vers un site web externe, ils permettent de naviguer au sein même du document.

De nombreux documents PDF utilisent des liens internes pour les signets ou la table des matières, permettant ainsi aux lecteurs de naviguer rapidement entre les sections. Voici comment ajouter un lien vers une section de document à l'aide de l'API Layout :

PdfDocumentBuilder.Create().Generate("link.pdf", doc =>
{
    doc.Pages(pages =>
    {
        pages.Content().Column(c =>
        {
            const string SectionName = "Chapter 1";
            c.Item().SectionLink(SectionName).Text("Link");

            c.Item().PageBreak();

            c.Item().Section(SectionName).Text("Target");
        });
    });
});

L'exemple de code transforme le texte de la première page en lien vers la section portant le nom spécifié. Pour ce faire, il appelle la méthode SectionLink sur le conteneur de mise en page contenant le texte. La section peut ne pas encore exister à ce stade. Le texte devient cliquable dans un visualiseur PDF.

Le code marque ensuite le texte de la deuxième page comme le début de la section du même nom. Son apparence et son comportement restent inchangés, mais il devient la cible du lien de la première page. Ceci est réalisé en appelant la méthode Section sur le conteneur de mise en page correspondant.

Dans cet exemple, le lien et sa cible sont des éléments de texte (span), mais vous pouvez créer des sections et des liens sur n'importe quel conteneur de mise en page : un conteneur d'image, un conteneur de tableau ou un conteneur que vous créez vous-même.

Consultez un exemple de création d'une table des matières PDF dans notre dépôt d'exemples.

Conception de mises en page PDF complexes

L'API Layout propose divers conteneurs de mise en page que vous pouvez combiner pour créer des documents PDF d'une complexité arbitraire. Vous pouvez également étendre l'API avec vos propres composants personnalisés.

Les exemples de cette page sont volontairement simples, conçus pour créer des documents clairs et vous permettre de vous concentrer sur l'essentiel sans vous perdre dans les détails. Si vous souhaitez découvrir comment combiner différents conteneurs pour générer un PDF plus complexe, consultez l'exemple correspondant dans notre dépôt d'exemples sur GitHub.

Outre l'utilisation des conteneurs intégrés, vous pouvez définir et utiliser des composants de mise en page personnalisés. Ces composants sont particulièrement utiles lorsque vous souhaitez qu'une seule classe encapsule à la fois les données et la logique de mise en page. En centralisant toutes les informations, le composant est plus facile à comprendre, à modifier et à réutiliser, tout en vous offrant une grande flexibilité pour gérer des mises en page complexes.

Pour créer un composant de mise en page personnalisé, implémentez l'interface ILayoutComponent dans votre classe. Lors de la génération d'un PDF, la bibliothèque appelle la méthode Compose de l'interface et fournit un objet LayoutContext. Votre code peut utiliser cet objet pour créer des éléments de mise en page et accéder aux informations relatives au document généré.

Pour ajouter un composant de mise en page personnalisé, appelez la méthode Component de la classe LayoutContainer. En termes de dimensionnement et de positionnement, un composant personnalisé se comporte comme du texte ou des images.

Pour un exemple d'implémentation d'un composant personnalisé avec l'interface ILayoutComponent, consultez l'exemple Composants de mise en page.

Autres façons de créer un PDF

Docotic.Pdf propose plusieurs méthodes de création de PDF, chacune adaptée à des cas de figure spécifiques. Cette section explique quand privilégier l'API Layout et quand d'autres approches peuvent s'avérer plus pertinentes.

Quand privilégier l'API Layout

L'API Docotic.Pdf Layout est un outil puissant pour générer des PDF à partir de mises en page structurées. Elle permet de créer des documents en composant du texte, des images, des conteneurs et des tableaux selon des structures imbriquées d'une complexité arbitraire. Le processus de génération est rapide, consomme une quantité raisonnable de mémoire et se comporte de manière prévisible.

Docotic.Pdf et son extension Layout forment un ensemble léger et entièrement autonome. L'API ne nécessite aucune bibliothèque externe ni navigateur pour générer des PDF. Elle constitue ainsi un choix judicieux pour les microservices .NET, les applications cloud (notamment les applications sans serveur) et tout autre environnement où l'encombrement est un facteur important.

Comme la mise en page du document est définie dans le code, vous pouvez tester unitairement chaque partie du document. La logique de mise en page est réutilisable comme n'importe quel autre code, et vous pouvez encapsuler les données et le comportement de mise en page dans des composants personnalisés.

Alternatives à l'API de mise en page

Un article dédié propose une comparaison détaillée de toutes les méthodes de création de PDF avec Docotic.Pdf. Vous trouverez ci-dessous quelques-unes des alternatives les plus couramment utilisées.

• Conversion HTML vers PDF
  Réutilise les modèles HTML/CSS existants. Choisissez l'approche HTML vers PDF si votre équipe produit déjà des documents en HTML/CSS et que vous avez besoin de versions PDF de ces documents.

• Génération de PDF de bas niveau
  Offre un contrôle maximal sur la structure et le contenu des fichiers PDF, tel que défini dans la bibliothèque. Choisissez cette option pour un positionnement au pixel près ou pour des graphiques vectoriels complexes. Cette approche est recommandée pour les applications critiques en termes de performances ou lorsque l'encombrement minimal est requis.

• Génération de PDF à partir de modèles
  Offre une méthode rapide et fiable pour remplir des documents sans avoir à concevoir ni à agencer leurs éléments. Choisissez cette option si vous disposez d'une structure PDF prédéfinie, comme des modèles approuvés ou soumis à un contrôle de conformité, et que vous souhaitez uniquement modifier les champs de texte, remplacer les espaces réservés, joindre des documents associés et effectuer des tâches similaires.

• Fusion et composition de fichiers PDF
  Permet de créer un PDF à partir d'éléments existants au lieu de le recréer entièrement. Choisissez cette option si vous avez des images, des pages numérisées ou d'autres fichiers PDF à combiner en un seul.

Comparaison avec d'autres solutions de génération de PDF

Cette section contient deux tableaux comparatifs : l’un reprenant les points clés et l’autre fournissant des informations détaillées et structurées sur la façon dont Docotic.Pdf avec l’extension Layout se compare à d’autres solutions populaires de génération de PDF.

Principaux points de comparaison

Il existe d'excellentes solutions pour générer des PDF, y compris des solutions gratuites. Cependant, leurs fonctionnalités, telles que la signature, le chiffrement ou la fusion de documents, varient, ce qui peut limiter le choix des outils réellement adaptés à vos besoins.

Comparaison détaillée

Examinez le tableau pour comprendre le contexte plus large et tirer vos propres conclusions.

Conclusion

Docotic.Pdf, avec son extension Layout, offre une solution moderne, performante et de haute qualité pour générer des PDF en C# et VB.NET. Cette bibliothèque permet de produire des rapports, des relevés, des factures et autres documents similaires. Son API fluide et bien conçue offre une excellente expérience de développement. Vous pouvez compter sur le support professionnel fourni par Bit Miracle pour Docotic.Pdf et ses extensions.

Contrairement à certaines autres solutions de génération de PDF, Docotic.Pdf est une API PDF complète. La bibliothèque peut signer les PDF générés avec des signatures numériques, y compris des signatures compatibles LTV. Docotic.Pdf est compatible avec les certificats stockés sur un support sécurisé, tels que les clés USB et les cartes à puce. Les modules de sécurité matériels (HSM) basés sur le cloud, comme Microsoft Azure Key Vault et AWS Key Management Service (KMS), sont également pris en charge.

Avec Docotic.Pdf, vous pouvez joindre des documents tels que des feuilles de calcul ou des notes vocales aux PDF générés. Pour afficher les documents sur une page web ou dans une interface similaire, vous pouvez créer des vignettes à partir d'une ou plusieurs de leurs pages.

Étapes suivantes :

• Explorez les exemples de code pour l’API Layout.
• Comparez la génération de PDF à partir de blocs de construction composables avec d’autres approches pour la création de PDF.
• Contactez-nous pour toute question, commentaire ou cas particulier.