Création de PDF avec le Core API

Traduit par Bit Miracle. Article original de Sergey Bobrovsky

Mis à jour le 29 juin 2026

Le Core Docotic.Pdf API fournit un contrôle complet sur la création de PDF. Il vous permet de dessiner du texte, des images et des graphiques vectoriels sur des canvas fournis par les pages PDF, les XObjects et les motifs de mosaïque.

Vous contrôlez chaque coordonnée et chaque opération de dessin, ce qui vous donne un contrôle maximal sur la mise en page de vos pages PDF. Pour les documents riches en graphiques ou à mise en page personnalisée où la précision compte, ce niveau de contrôle est indispensable.

Avec le Core API, 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 manière la plus flexible et la plus puissante de créer des PDF dans .NET fournie par Docotic.Pdf.

Consultez l'article qui présente toutes les méthodes de création de PDF si vous souhaitez une vue d'ensemble plus large de toutes les approches disponibles dans Docotic.Pdf, y compris celles au-delà du Core API.

Avant de commencer

Avant de commencer à travailler avec le Core API, préparez 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 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 essayer la bibliothèque, demandez une clé de licence gratuite limitée dans le temps en remplissant le formulaire sur la page de téléchargement de Docotic.Pdf.

Exemples de base de création de PDF

Cette section présente des exemples de base qui montrent comment créer des documents PDF avec le Core API, 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 le Core API.

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, vous obtiendrez une exception sur la ligne qui instancie un PdfDocument. La dernière ligne enregistre le document dans un fichier 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 ce que font ces valeurs par défaut et quand vous pouvez vouloir les ajuster, consultez la section sur les options d’enregistrement.

Par tradition de programmation, le deuxième exemple présente un Hello, world! créé avec le Core API.

using var pdf = new PdfDocument();

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

pdf.Save("hello.pdf");

Le code place la phrase classique sur le canvas de la première page du document, en commençant à la position explicitement spécifiée. La ligne utilise la police par défaut et la taille de police par défaut. Continuez à lire pour obtenir des informations supplémentaires sur le travail avec le canvas PDF.

Utiliser VB.NET pour créer un PDF

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 inclut un exemple en C#, explique ce que fait le code et comment il fonctionne.

Travailler avec le canvas PDF

Pour modifier un canvas dans un document PDF, utilisez le Canvas API. Il s'agit d'un sous-ensemble du Core API.

Le Canvas API utilise un modèle de positionnement absolu. Vous choisissez les coordonnées, et le canvas dessine exactement à 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 le long de l'axe X et vers le bas le long de l'axe Y.

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

Dessiner du texte

Dans la classe PdfCanvas, Docotic.Pdf fournit deux méthodes principales pour rendre du texte : DrawString et DrawText. Les deux méthodes utilisent la police actuelle du canvas, il est donc recommandé de définir la police souhaitée avant de dessiner du texte.

Utiliser DrawString

DrawString dessine toujours une seule ligne de texte. La méthode commence à dessiner à partir de la position actuelle du texte du canvas, sauf si vous utilisez une surcharge avec des coordonnées explicites. Certaines surcharges vous permettent de spécifier des options supplémentaires qui contrôlent la manière dont la ligne de texte est dessinée.

Vous avez déjà vu un exemple simple de DrawString dans l'extrait Hello, world!. Voici un autre exemple qui utilise des options de dessin de chaîne 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");

Utiliser DrawText

DrawText peut rendre plusieurs lignes de texte dans un rectangle spécifié. La méthode gère les retours à la ligne et découpe le texte qui ne tient pas dans l'espace autorisé. Les options de dessin de texte définissent l'alignement horizontal et vertical du texte ainsi que d'autres aspects du positionnement et du rendu du texte.

Voici comment dessiner du texte dans un PDF à l'aide de 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 affiner l'apparence du texte, vous pouvez ajuster les propriétés de canvas suivantes :

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

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

Ajouter et utiliser des polices

À moins d'être satisfait de la police Helvetica par défaut, vous devriez ajouter au PDF les polices dont vous avez besoin afin de garantir que votre texte s'affiche exactement comme prévu.

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
• des fichiers et flux externes

En outre, vous pouvez utiliser les 14 polices Type1 intégrées, disponibles dans n'importe quel lecteur PDF.

Pour utiliser une police dans votre PDF, créez un objet PdfFont en utilisant la méthode CreateFont ou CreateFontFromFile de l'objet PdfDocument correspondant. Affectez ensuite la police au canvas avant de dessiner du texte. Il est également recommandé de définir la taille de 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 des glyphes pour tous les caractères du texte que vous essayez de dessiner. Sinon, vous obtiendrez une CannotShowTextException. Utilisez PdfFont.ContainsGlyphsForText pour vérifier que la police contient tous les glyphes requis.

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

Les polices TrueType, CFF et OpenType prennent généralement en charge Unicode, mais elles ne contiennent pas forcément des glyphes pour tous les caractères Unicode.

Docotic.Pdf essaie d'intégrer le moins d'octets de police possible afin de réduire la taille du PDF de sortie. Cependant, lorsqu'un document utilise des polices contenant de nombreux glyphes, le fichier résultant peut quand même être relativement volumineux. Utilisez PdfFont.RemoveUnusedGlyphs pour minimiser le nombre d'octets ajoutés par les polices intégrées.

Calculer les dimensions du texte

Comme le Canvas API utilise un positionnement absolu, il est souvent nécessaire de savoir combien d'espace un fragment de texte occupera avant de le dessiner. C'est particulièrement important lorsque vous affichez du texte en plusieurs passes, par exemple pour découper de longues chaînes, aligner précisément du texte ou éviter les chevauchements avec d'autres contenus. La classe PdfCanvas fournit plusieurs méthodes qui vous aident à mesurer le texte à l'aide de la police et de la taille de police actuellement sélectionnées.

Utilisez PdfCanvas.MeasureText pour obtenir à la fois la largeur et la hauteur d'une chaîne telle qu'elle apparaîtrait sur le canvas. Les cas d'utilisation typiques incluent :

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

Pour les cas où vous centrez ou alignez le texte à droite et où vous n'avez besoin que de l'étendue horizontale, utilisez PdfCanvas.GetTextWidth. Pour connaître la hauteur d'une ligne de texte pour la police actuelle, utilisez PdfCanvas.GetTextHeight.

Dessiner des images

Pour dessiner une image sur un canvas PDF, créez d'abord un objet PdfImage, puis dessinez cet objet à 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 canvas de la première page.

Consultez la création de PDF à partir d'images pour plus de détails sur les formats d'image pris en charge et sur les techniques de conversion image vers PDF plus avancées.

Utiliser des 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 canvas PDF en utilisant les 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 canvas.

Les lignes et les courbes sont rendues à l'aide du stylo courant, défini via PdfCanvas.Pen, qui spécifie la couleur du contour, la largeur 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, est utilisé pour 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 canvas PDF conserve un état graphique, qui inclut le stylo, le pinceau, la police et les positions courantes. Utilisez SaveState pour préserver l'état actuel et RestoreState pour revenir à un état précédent. En plus d'annuler les transformations temporaires et les changements similaires, la restauration de l'état est le seul moyen de supprimer le découpage une fois qu'il a été appliqué.

Les chemins graphiques vous permettent de construire des formes complexes à partir de lignes, de courbes et de formes plus simples sans les dessiner immédiatement. Utilisez des méthodes Append telles que AppendLineTo ou AppendRectangle pour ajouter des segments au chemin courant. Les chemins ne produisent aucune sortie visible tant que vous ne les remplissez pas ou ne les tracez pas explicitement.

Vous pouvez utiliser n'importe quel chemin graphique construit comme région de découpage afin de restreindre les opérations de dessin suivantes. Le découpage reste actif jusqu'à ce que l'état graphique soit restauré.

Des exemples pratiques et exécutables de travail avec les graphiques vectoriels sont disponibles dans la section Graphiques du dépôt d'exemples.

Définir les couleurs et la transparence

Vous pouvez modifier les couleurs de contour et de remplissage via le stylo et le pinceau d'un canvas PDF. Pour cela, utilisez PdfPen.Color et PdfBrush.Color.

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, y compris les couleurs Lab* et les couleurs calibrées basées sur ICC. Le Core API prend également en charge les couleurs d'accompagnement et les espaces colorimétriques de séparation pour les flux de travail qui nécessitent des encres personnalisées ou une sortie spécifique à un canal.

Le code d'exemple ci-dessous montre comment créer des couleurs Lab, des couleurs basées sur des profils et des couleurs d'accompagnement. 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 aussi tracer et remplir des formes à l'aide de motifs de mosaïque. Un motif est défini par une cellule de motif dessinée sur son propre canvas. 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/pinceau au moment de l'utilisation.

Pour utiliser un motif, créez-en un en utilisant CreateColoredPattern ou CreateUncoloredPattern de l'objet PdfDocument correspondant. Appliquez ensuite le motif via PdfPen.Pattern et/ou PdfBrush.Pattern. Consultez le code d'exemple pour créer et utiliser des 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 produire des couleurs translucides.

En outre, les modes de fusion contrôlent la manière dont le contenu transparent interagit avec ce qui se trouve en dessous. Pour changer le mode de fusion d'un canvas, utilisez PdfCanvas.BlendMode.

Ajouter et personnaliser des pages

Docotic.Pdf expose la collection PdfDocument.Pages, que vous pouvez utiliser pour gérer toutes les pages d'un document. Dans la classe PdfDocument, il existe deux méthodes principales permettant d'ajouter de nouvelles pages : AddPage et InsertPage.

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

Chaque nouvelle page a la taille par défaut de 595 x 842 unités d'espace utilisateur. C'est la taille d'une feuille A4. Dans la plupart des cas, l'unité d'espace utilisateur dans PDF correspond à 1/72 de pouce. Ou, autrement dit, une unité d'espace utilisateur équivaut à 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 sur 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 du portrait au 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, il est également possible d'ajuster la taille de la page tout en rognant ou en redimensionnant le contenu existant.

Réutiliser du contenu avec des XObjects

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

Les XObjects sont similaires à des images vectorielles. Vous pouvez réutiliser le même objet sur plusieurs pages sans recréer le contenu ni alourdir la taille du document. Vous pouvez mettre à l'échelle et faire pivoter de tels objets sans introduire d'artefacts visuels. En raison de ces qualités, les XObjects sont idéaux pour les éléments répétés tels que les logos, les illustrations, les arrière-plans, les filigranes et les autres graphiques récurrents.

Créer et utiliser des XObjects

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 canvas avec du texte, des images et des graphiques de la même manière que pour le canvas d'une page normale.

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

Voici du code C# qui crée un XObject avec une illustration et dessine l'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 des XObjects

Les XObjects permettent aussi des scénarios qui vont au-delà de la simple réutilisation de graphiques. Un exemple courant consiste à combiner deux pages PDF existantes en une seule page plus grande. En transformant chaque page source en XObject, vous pouvez les dessiner côte à côte sur un nouveau canvas, créant ainsi efficacement une double page fusionnée. Cette approche vous donne un contrôle complet sur le positionnement, l'espacement et la mise à l'échelle, ce qui facilite la création de mises en page de comparaison, 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 d'origine et le dessiner à l'échelle de la nouvelle taille. Cela vous permet de réduire des pages trop grandes, d'agrandir des pages plus petites ou d'harmoniser un document de tailles mixtes avec un minimum d'effort.

Portée et contraintes du Core API

Le Core API offre un contrôle précis et de bas niveau sur la création de PDF, mais ne fournit aucune fonctionnalité de mise en page automatique. Il n'existe ni marges intégrées, ni en-têtes, ni pieds de page, ni logique de saut de page, et tout le contenu doit être positionné manuellement. La mesure du texte et sa répartition sur plusieurs pages relèvent entièrement de votre code, ce qui en fait l'approche la plus manuelle pour créer des PDF.

La mise en page automatique, y compris la prise en charge des tableaux, des paragraphes et des sauts de page, est disponible via le Layout API de niveau supérieur.

Conclusion

Le Core Docotic.Pdf API fournit un contrôle complet sur la création de PDF. Il vous permet de dessiner du texte, des images et des graphiques vectoriels sur des canvas fournis par les pages PDF, les XObjects et les motifs de mosaïque.

L'API est conçue pour les scénarios qui exigent un contrôle précis et de bas niveau : vous positionnez explicitement chaque élément, gérez vous-même la mesure du texte et la répartition sur plusieurs pages, et manipulez directement l'état graphique, les couleurs et la transparence.

Dans l'ensemble, le Core API est l'outil le plus flexible pour créer des PDF lorsque la précision et le contrôle sont prioritaires.