Cette page peut contenir du texte traduit automatiquement.

Création de fichiers PDF avec l'API principale

Logo carré de Bit Miracle
Traduit par Bit Miracle. Article original de Sergey Bobrovsky
Mis à jour le 5 mai 2026

L'API principale de Docotic.Pdf offre un contrôle total sur la création de PDF. Elle permet de dessiner du texte, des images et des graphiques vectoriels sur les canevas fournis par les pages PDF, les objets XObject et les motifs de pavage.

Vous contrôlez chaque coordonnée et chaque opération de dessin, ce qui vous offre une maîtrise maximale de la mise en page de vos PDF. Pour les documents riches en graphiques ou à mise en page personnalisée où la précision est essentielle, ce niveau de contrôle est indispensable.

Grâce à l'API principale, vous pouvez également ajouter des annotations, des champs de formulaire, des calques, des signets et bien plus encore aux PDF créés. Cette API est la méthode la plus flexible et la plus puissante pour créer des PDF en .NET avec Docotic.Pdf.

Illustration des fonctionnalités principales de l'API pour la création de PDF, montrant les graphiques vectoriels, le placement d'images et le dessin de texte.

Consultez l'article qui décrit toutes les méthodes de création de PDF si vous souhaitez un aperçu plus large de toutes les approches disponibles dans Docotic.Pdf, y compris celles qui vont au-delà de l'API principale.

Avant de commencer

Avant de commencer à utiliser l'API principale, configurez votre environnement en installant Docotic.Pdf et en demandant une clé de licence.

Installer Docotic.Pdf

Pour créer des documents PDF en C# ou VB.NET, commencez par installer la bibliothèque depuis NuGet.

Install-Package BitMiracle.Docotic.Pdf

Si vous préférez installer la bibliothèque manuellement, téléchargez l'archive ZIP contenant les fichiers binaires de la bibliothèque, décompressez-la et ajoutez une référence à BitMiracle.Docotic.Pdf.dll depuis votre projet.

Obtenir une clé de licence

Une clé de licence est requise pour utiliser la bibliothèque. Pour l'essayer, demandez une clé de licence gratuite et temporaire en remplissant le formulaire sur la page de téléchargement de Docotic.Pdf.

Exemples de création de PDF de base

Cette section fournit des exemples de base qui montrent comment créer des documents PDF avec l'API Core, d'abord en C# puis en VB.NET.

Comment créer un PDF en C#

Maintenant que vous avez installé Docotic.Pdf et obtenu une clé de licence, il est facile de créer un PDF avec l'API principale.

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

using var pdf = new PdfDocument();
pdf.Save("empty.pdf");

Le code montre comment créer un fichier PDF vide. La première ligne ajoute une clé de licence. Sans licence, une exception sera levée à la ligne qui instancie un PdfDocument. La dernière ligne enregistre le document au format PDF.

La structure interne du fichier créé dépend des options d'enregistrement. Dans cet exemple, le code utilise la surcharge de la méthode Save qui enregistre avec les options par défaut. Pour comprendre le rôle de ces options par défaut et savoir quand les modifier, consultez la section relative aux options d'enregistrement.

Conformément à la tradition de la programmation, le deuxième exemple présente un message « Hello, world!» créé avec l'API Core.

using var pdf = new PdfDocument();

var page = pdf.Pages[0];
page.Canvas.DrawString(50, 50, "Hello, world!");

pdf.Save("hello.pdf");

Ce code insère la phrase classique sur le canevas de la première page du document, à l'emplacement spécifié. La ligne utilise la police et la taille de police par défaut. Pour plus d'informations sur l'utilisation du canevas PDF, poursuivez votre lecture.

Création d'un PDF à l'aide de VB.NET

Le code VB.NET permettant de créer un PDF ressemble beaucoup au code de la section précédente.

Using pdf As New PdfDocument()
    Dim page = pdf.Pages(0)
    page.Canvas.DrawString(50, 50, "Hello, world!")

    pdf.Save("hello.pdf")
End Using

La section précédente, qui comprend un exemple en C#, explique ce que fait le code et comment il fonctionne.

Travailler avec un canevas PDF

Pour modifier une zone de dessin dans un document PDF, utilisez l'API Canvas. Il s'agit d'un sous-ensemble de l'API Core.

L'API Canvas utilise un modèle de positionnement absolu. Vous choisissez les coordonnées, et la zone de dessin se positionne précisément à l'endroit indiqué. Le système de coordonnées place l'origine dans le coin supérieur gauche de la page. Les coordonnées augmentent vers la droite sur l'axe X et vers le bas sur l'axe Y.

(0,0) ──► X
  │
  │
  ▼
  Y

Texte de dessin

Dans la classe PdfCanvas, Docotic.Pdf propose deux méthodes principales pour le rendu de texte : DrawString et DrawText. Ces deux méthodes utilisent la police du canevas actuel ; il est donc recommandé de définir la police souhaitée avant de dessiner du texte.

Utilisation de DrawString

La méthode DrawString dessine toujours une seule ligne de texte. Elle commence le dessin à partir de la position actuelle du texte sur le canevas, sauf si vous utilisez une surcharge avec des coordonnées explicites. Certaines surcharges permettent de spécifier des options supplémentaires qui contrôlent le tracé de la ligne de texte.

Vous avez déjà vu un exemple simple d'utilisation de DrawString dans l'extrait de code « Hello, world!». Voici un autre exemple qui utilise les options de dessin de chaînes de caractères pour souligner du texte.

using var pdf = new PdfDocument();

var canvas = pdf.Pages[0].Canvas;
canvas.DrawString(50, 50, "This text is underlined", new PdfStringDrawingOptions
{
    Underline = true,
});

pdf.Save("underlined-text.pdf");

Using DrawText

La méthode DrawText permet d'afficher plusieurs lignes de texte dans un rectangle spécifié. Elle gère les sauts de ligne et tronque le texte qui dépasse l'espace disponible. Les options de dessin de texte définissent l'alignement horizontal et vertical du texte, ainsi que d'autres aspects de son positionnement et de son rendu.

Voici comment dessiner du texte dans un PDF en C# :

using var pdf = new PdfDocument();

const string LongString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit";
var multiLineOptions = new PdfTextDrawingOptions(new PdfRectangle(70, 70, 40, 150))
{
    HorizontalAlignment = PdfTextAlign.Left,
    VerticalAlignment = PdfVerticalAlign.Top
};

var canvas = pdf.Pages[0].Canvas;
canvas.DrawText(LongString, multiLineOptions);

pdf.Save("drawtext.pdf");

Pour ajuster avec précision l'apparence du texte, vous pouvez modifier les propriétés suivantes du canevas :

  • espacement des caractères
  • espacement des mots
  • mise à l'échelle du texte
  • décalage de la ligne de base
  • mode de rendu (remplissage, contour, remplissage et contour, etc.)

Pour des exemples pratiques de méthodes et de propriétés liées au texte, consultez le groupe d'exemples de texte.

Ajout et utilisation de polices

À moins que la police Helvetica par défaut ne vous convienne, il est recommandé d'ajouter les polices nécessaires au PDF pour que votre texte s'affiche correctement.

Docotic.Pdf peut ajouter des polices Type1, TrueType, Compact Font Format (CFF) et OpenType à partir :

  • de la collection de polices installées sur le système
  • de fichiers et flux externes

Vous pouvez également utiliser les 14 polices Type1 intégrées, disponibles dans tous les lecteurs PDF.

Pour utiliser une police dans votre PDF, créez un objet PdfFont à l'aide de la méthode CreateFont ou CreateFontFromFile de l'objet PdfDocument correspondant. Attribuez ensuite la police à la zone de dessin avant d'y ajouter du texte. Il est également conseillé de définir la taille de la police.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var font = pdf.CreateFont("NSimSun");
canvas.Font = font;
canvas.FontSize = 14;
canvas.DrawString(10, 50, "Olá. 你好. Hello, Unicode!");

font.RemoveUnusedGlyphs();

pdf.Save("unicode-text.pdf");

La police doit contenir les glyphes de tous les caractères du texte que vous souhaitez afficher. Dans le cas contraire, une exception CannotShowTextException sera levée. Utilisez PdfFont.ContainsGlyphsForText pour vérifier que la police contient bien tous les glyphes requis.

La prise en charge d'Unicode dépend du type de police. Les polices de type 1 prennent uniquement en charge le jeu de caractères et l'encodage latins, à une exception près. Les polices intégrées Symbol et ZapfDingbats proposent des symboles mathématiques, grecs et décoratifs.

Les polices TrueType, CFF et OpenType prennent généralement en charge Unicode, mais il est possible qu'elles ne contiennent pas les glyphes de tous les caractères Unicode.

Docotic.Pdf tente d'intégrer le moins d'octets de police possible afin de réduire la taille du PDF généré. Toutefois, lorsqu'un document utilise des polices comportant de nombreux glyphes, le fichier résultant peut rester relativement volumineux. Utilisez PdfFont.RemoveUnusedGlyphs pour minimiser le nombre d'octets ajoutés par les polices intégrées.

Calcul des dimensions du texte

L'API Canvas utilisant le positionnement absolu, il est souvent nécessaire de connaître l'espace occupé par un texte avant de le dessiner. Ceci est particulièrement important lors de l'affichage de texte en plusieurs étapes, par exemple pour découper de longues chaînes de caractères, aligner précisément du texte ou éviter les chevauchements avec d'autres contenus. La classe PdfCanvas propose plusieurs méthodes permettant de mesurer le texte en fonction de la police et de la taille de police actuellement sélectionnées.

Utilisez PdfCanvas.MeasureText pour obtenir la largeur et la hauteur d'une chaîne de caractères telle qu'elle apparaîtra sur le canevas. Cas d'utilisation typiques :

  • déterminer si le texte tient dans une zone donnée
  • calculer manuellement les sauts de ligne
  • positionner des blocs de texte les uns par rapport aux autres

Pour centrer ou aligner à droite du texte et n'avoir besoin que de sa largeur, utilisez PdfCanvas.GetTextWidth. Pour connaître la hauteur d'une ligne de texte avec la police actuelle, utilisez PdfCanvas.GetTextHeight.

Dessiner des images

Pour dessiner une image sur un canevas PDF, créez d'abord un objet PdfImage, puis dessinez-le à l'aide de la méthode PdfCanvas.DrawImage.

Voici comment ajouter une image à un PDF en C# :

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var image = pdf.CreateImage("image.png");
canvas.DrawImage(image, 10, 50);

pdf.Save("image.pdf");

Le code crée un objet image à l'aide de la méthode CreateImage de l'objet PdfDocument correspondant et dessine l'image sur le canevas de la première page.

Pour plus de détails sur les formats d'image pris en charge et les techniques avancées de conversion d'image en PDF, consultez la documentation relative à la création de PDF à partir d'images.

Utilisation de graphiques vectoriels

Docotic.Pdf vous permet de dessiner des lignes droites, des courbes de Bézier et des formes géométriques courantes directement sur un canevas PDF grâce aux méthodes de la classe PdfCanvas. Utilisez les méthodes commençant par Draw (par exemple, DrawLineTo, DrawCircle, DrawRectangle) pour placer des marques visibles sur le canevas.

Les lignes et les courbes sont rendues à l'aide du stylo courant, défini par PdfCanvas.Pen, qui spécifie la couleur, l'épaisseur et d'autres propriétés de dessin. Selon le mode de dessin, les formes peuvent être tracées, remplies ou tracées puis remplies. Le pinceau courant, accessible via PdfCanvas.Brush, sert à remplir l'intérieur des formes.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.DrawCircle(new PdfPoint(60, 100), 40);
canvas.DrawRectangle(
    new PdfRectangle(300, 60, 110, 70),
    PdfDrawMode.Fill);

canvas.CurrentPosition = new PdfPoint(150, 90);
canvas.DrawCurveTo(new PdfPoint(180, 60), new PdfPoint(230, 120), new PdfPoint(250, 90));

pdf.Save("curve-and-shapes.pdf");

Chaque zone de dessin PDF conserve un état graphique, incluant le stylet, le pinceau, la police et la position actuelle. Utilisez SaveState pour sauvegarder l'état actuel et RestoreState pour revenir à un état précédent. Outre l'annulation des transformations temporaires et autres modifications similaires, la restauration de l'état est le seul moyen de supprimer le rognage une fois appliqué.

Les tracés graphiques permettent de créer des formes complexes à partir de lignes, de courbes et de formes plus simples sans les dessiner immédiatement. Utilisez les méthodes Append telles que AppendLineTo ou AppendRectangle pour ajouter des segments au tracé actuel. Les tracés ne produisent aucun résultat visible tant que vous ne les remplissez pas ou ne les tracez pas explicitement.

Vous pouvez utiliser n'importe quel tracé graphique créé comme zone de rognage pour limiter les opérations de dessin suivantes. Le rognage reste actif jusqu'à la restauration de l'état graphique.

Des exemples pratiques et exécutables d'utilisation des graphiques vectoriels sont disponibles dans la section Graphics du dépôt d'exemples.

Réglage des couleurs et de la transparence

Vous pouvez modifier les couleurs de contour et de remplissage à l'aide du stylo et du pinceau d'un canevas PDF. Pour ce faire, utilisez PdfPen.Color et PdfBrush.Color.

Illustration de formes colorées dégoulinantes, certaines unies et d'autres à motifs, illustrant les capacités de l'API Core en matière de couleurs et de transparence.

Les espaces colorimétriques dépendants du périphérique pris en charge incluent Gray, RGB et CMYK, représentés par PdfGrayColor, PdfRgbColor et PdfCmykColor.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.Pen.Color = new PdfRgbColor(30, 60, 160);
canvas.Pen.Width = 3;

canvas.Brush.Color = new PdfCmykColor(0, 20, 5, 0);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

pdf.Save("fill-and-stroke-colors.pdf");

Docotic.Pdf prend en charge les espaces colorimétriques CIE indépendants du périphérique, notamment les couleurs L*a*b* et les couleurs calibrées ICC. L'API principale prend également en charge les tons directs et les espaces colorimétriques de séparation pour les flux de travail nécessitant des encres personnalisées ou une sortie spécifique à un canal.

L'exemple de code ci-dessous illustre la création de couleurs Lab, de couleurs basées sur un profil et de tons directs. Pour exécuter l'exemple, téléchargez d'abord le profil ICC utilisé.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var labColorSpace = new PdfLabColorSpace(pdf, [0.5, 1, 0.5]);
canvas.Pen.Color = new PdfLabColor(labColorSpace, 50, -50, 50);
canvas.Pen.Width = 3;

var rgbProfile = pdf.CreateColorProfile("AdobeCompat-v2.icc");
canvas.Brush.Color = new PdfRgbColor(rgbProfile, 210, 105, 30);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

var tintTransform = new PdfExponentialFunction(
    pdf, 1, [0d, 0, 0, 0], [0, 0.8, 0.73, 0.25], [0d, 1]);
var separationColorSpace = new PdfSeparationColorSpace(
    pdf, "BLOODRED", new PdfCmykColorSpace(), tintTransform);
canvas.Pen.Color = new PdfSpotColor(1.0, separationColorSpace);

canvas.DrawCircle(new PdfPoint(100, 70), 60);

pdf.Save("using-special-colors.pdf");

Vous pouvez également tracer et remplir des formes à l'aide de motifs répétitifs. Un motif est défini par une cellule dessinée sur son propre canevas. Il en existe deux types :

  • Motifs colorés : leurs cellules définissent leurs propres couleurs.
  • Motifs non colorés : leurs cellules sont teintées par la couleur du stylo ou du pinceau utilisé.

Pour utiliser un motif, créez-en un à l'aide de CreateColoredPattern ou CreateUncoloredPattern de l'objet PdfDocument correspondant. Appliquez ensuite le motif via PdfPen.Pattern et/ou PdfBrush.Pattern. Consultez l'exemple de code pour la création et l'utilisation de motifs dans le dépôt d'exemples.

Les couleurs semi-transparentes vous permettent de dessiner des formes, du texte et des images avec une opacité variable. Utilisez PdfPen.Opacity et PdfBrush.Opacity pour obtenir des couleurs translucides.

De plus, les modes de fusion contrôlent l'interaction du contenu transparent avec ce qui se trouve en dessous. Pour modifier le mode de fusion d'un canevas, utilisez PdfCanvas.BlendMode.

Ajout et personnalisation de pages

Docotic.Pdf expose la collection PdfDocument.Pages, qui permet de gérer toutes les pages d'un document. La classe PdfDocument propose deux méthodes principales pour ajouter des pages : AddPage et InsertPage.

Utilisez AddPage() pour ajouter une page à la fin du document. Pour insérer une page à n'importe quelle position, utilisez InsertPage(index). Ces deux méthodes renvoient l'instance PdfPage nouvellement créée.

Chaque page a par défaut une taille de 595 × 842 unités d'espace utilisateur, soit le format d'une feuille A4. En PDF, l'unité d'espace utilisateur est généralement de 1/72 de pouce. Autrement dit, une unité d'espace utilisateur correspond à un pixel lorsque la résolution de la page est de 72 pixels par pouce.

Vous pouvez modifier la taille d'une page à tout moment en définissant sa largeur et/ou sa hauteur à un nombre spécifique d'unités d'espace utilisateur.

using var pdf = new PdfDocument();
var page = pdf.Pages[0];

page.Width = 600;
page.Height = 800;

Une autre option consiste à utiliser l'une des tailles prédéfinies :

page.Size = PdfPaperSize.Ledger;

Il est également possible de changer l'orientation de la page de portrait à paysage, et de faire pivoter une page de 90°, 180° ou 270° dans le sens horaire.

page.Orientation = PdfPaperOrientation.Landscape;
page.Rotation = PdfRotation.Rotate180;

Au-delà de la définition de la largeur, de la hauteur ou d'une taille prédéfinie de la page, il est également possible d'ajuster la taille de la page en même temps que le recadrage ou le redimensionnement du contenu existant.

Réutilisation de contenu avec XObjects

Un XObject PDF est un conteneur de graphiques vectoriels, d'images et de texte. Chaque XObject possède son propre espace de travail, ce qui permet de créer des XObjects aussi complexes que des pages PDF classiques.

Les XObjects sont similaires aux images vectorielles. Vous pouvez réutiliser le même objet sur plusieurs pages sans avoir à recréer son contenu ni à augmenter la taille du document. Vous pouvez redimensionner et faire pivoter ces objets sans introduire d'artefacts visuels. Grâce à ces qualités, les XObjects sont idéaux pour les éléments répétitifs tels que les logos, les illustrations, les arrière-plans, les filigranes et autres graphiques récurrents.

Création et utilisation d'objets XObject

Pour créer un XObject, utilisez la méthode PdfDocument.CreateXObject. Modifiez la largeur et la hauteur de l'objet si nécessaire. Remplissez ensuite le canevas avec du texte, des images et des graphiques, comme pour un canevas de page classique.

Utilisez la méthode PdfCanvas.DrawXObject dans votre code C# ou VB.NET pour ajouter le XObject à d'autres canevas. Notez que vous pouvez dessiner des XObjects sur les canevas fournis par les pages et par d'autres XObjects.

Voici un exemple de code C# qui crée un XObject contenant une illustration et dessine cette illustration sur deux pages.

using var pdf = new PdfDocument();

var xobj = pdf.CreateXObject();

var options = new PdfTextDrawingOptions(new PdfRectangle(0, 0, 100, 50))
{
    HorizontalAlignment = PdfTextAlign.Center,
    VerticalAlignment = PdfVerticalAlign.Center,
};
xobj.Canvas.FontSize = 16;
xobj.Canvas.DrawText("Company Logo", options);
xobj.Canvas.DrawRectangle(options.Bounds);

var page1 = pdf.Pages[0];
page1.Canvas.DrawXObject(xobj, 100, 100);

var page2 = pdf.AddPage();
page2.Canvas.DrawXObject(xobj, 200, 200);

pdf.Save("using-xobjects.pdf");

Transformer des pages avec XObjects

Les XObjects permettent également des scénarios allant au-delà de la simple réutilisation d'éléments graphiques. Un exemple courant consiste à combiner deux pages PDF existantes en une seule page plus grande. En convertissant chaque page source en XObject, vous pouvez les dessiner côte à côte sur un nouveau canevas, créant ainsi une double page fusionnée. Cette approche vous offre un contrôle total sur le positionnement, l'espacement et l'échelle, facilitant la création de mises en page comparatives, de doubles pages de livre ou d'aperçus multipages.

La même technique peut être appliquée lorsque vous devez redimensionner des pages PDF. Au lieu de redessiner ou de reconstruire le contenu, vous pouvez créer un XObject à partir de la page originale et le dessiner à la nouvelle taille. Cela vous permet de réduire les pages trop grandes, d'agrandir les petites ou de normaliser un document de tailles variées avec un minimum d'effort.

Portée et contraintes de l'API principale

L'API Core offre un contrôle précis et de bas niveau sur la création de PDF, mais ne propose aucune fonctionnalité de mise en page automatique. Elle ne gère ni les marges, ni les en-têtes, ni les pieds de page, ni la logique de saut de page ; tout le contenu doit être positionné manuellement. Le dimensionnement du texte et sa répartition sur les pages sont entièrement à la charge de votre code, ce qui en fait la méthode la plus manuelle pour créer des PDF.

La mise en page automatique, incluant la prise en charge des tableaux, des paragraphes et des sauts de page, est disponible via l'API Layout de plus haut niveau.

Conclusion

L'API principale de Docotic.Pdf offre un contrôle total sur la création de PDF. Elle permet de dessiner du texte, des images et des graphiques vectoriels sur les canevas fournis par les pages PDF, les XObjects et les motifs de pavage.

Cette API est conçue pour les scénarios exigeant un contrôle précis et de bas niveau : vous positionnez chaque élément explicitement, gérez vous-même la taille du texte et le découpage des pages, et manipulez directement l'état, les couleurs et la transparence des graphiques.

En résumé, l'API principale est l'outil le plus flexible pour la création de PDF lorsque la précision et le contrôle sont primordiaux.

Essayez la bibliothèque avec une clé gratuite