Questa pagina può contenere testo tradotto automaticamente.

Creazione di PDF con il Core API

Logo quadrato di Bit Miracle
Tradotto da Bit Miracle. Articolo originale di Sergey Bobrovsky
Aggiornato il 29 giugno 2026

Il Core API di Docotic.Pdf fornisce il controllo completo sulla creazione di PDF. Consente di disegnare testo, immagini e grafica vettoriale su aree di disegno fornite da pagine PDF, XObject e pattern di tiling.

Hai il controllo su ogni coordinata e su ogni operazione di disegno, e questo ti offre il massimo controllo sul layout delle pagine PDF. Per documenti ricchi di grafica o con layout personalizzati in cui la precisione conta, questo livello di controllo è indispensabile.

Con il Core API, puoi anche aggiungere annotazioni, campi modulo, livelli, segnalibri e altro ancora ai PDF creati. L'API è il modo più flessibile e potente per creare PDF in .NET offerto da Docotic.Pdf.

Illustrazione delle funzionalità del Core API per la creazione di PDF, che mostra grafica vettoriale, posizionamento di immagini e disegno di testo.

Consulta l'articolo che illustra ogni metodo per creare PDF se desideri una panoramica più ampia di tutti gli approcci disponibili in Docotic.Pdf, inclusi quelli oltre il Core API.

Prima di iniziare

Prima di iniziare a lavorare con il Core API, configura l'ambiente installando Docotic.Pdf e richiedendo una chiave di licenza.

Installare Docotic.Pdf

Per creare documenti PDF in C# o VB.NET, inizia installando la libreria da NuGet.

Install-Package BitMiracle.Docotic.Pdf

Se preferisci installare la libreria manualmente, scarica l'archivio ZIP con i binari della libreria, decomprimilo e aggiungi al progetto un riferimento a BitMiracle.Docotic.Pdf.dll.

Ottenere una chiave di licenza

Per usare la libreria è necessaria una chiave di licenza. Per provarla, richiedi una chiave di licenza gratuita con durata limitata compilando il modulo nella pagina di download di Docotic.Pdf.

Esempi base di creazione di PDF

Questa sezione fornisce esempi base che mostrano come creare documenti PDF con il Core API, prima in C# e poi in VB.NET.

Come creare un PDF in C#

Ora che hai installato Docotic.Pdf e ottenuto una chiave di licenza, creare un PDF con il Core API è semplice.

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

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

Il codice mostra come creare un file PDF vuoto. La prima riga aggiunge una chiave di licenza. Senza licenza, otterrai un'eccezione nella riga che istanzia un PdfDocument. L'ultima riga salva il documento in un file PDF.

La struttura interna del file creato dipende dalle opzioni di salvataggio. In questo esempio, il codice usa l'overload del metodo Save che salva con le opzioni predefinite. Per capire cosa fanno questi valori predefiniti e quando potresti volerli modificare, vedi la sezione sulle opzioni di salvataggio.

Per rispettare la tradizione di programmazione, il secondo esempio mostra un Hello, world! creato con il Core API.

using var pdf = new PdfDocument();

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

pdf.Save("hello.pdf");

Il codice posiziona la frase classica sull'area di disegno della prima pagina del documento, a partire dalla posizione specificata esplicitamente. La riga usa il font predefinito e la dimensione del font predefinita. Continua a leggere per ulteriori informazioni sull'uso del canvas PDF.

Usare VB.NET per creare un PDF

Il codice VB.NET per creare un PDF è molto simile al codice della sezione precedente.

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

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

La sezione precedente, che include un esempio in C#, spiega cosa fa il codice e come funziona.

Lavorare con il canvas PDF

Per modificare un canvas in un documento PDF, usa la Canvas API. È un sottoinsieme del Core API.

La Canvas API usa un modello di posizionamento assoluto. Scegli le coordinate e il canvas disegna esattamente dove gli indichi. Il sistema di coordinate colloca l'origine nell'angolo superiore sinistro della pagina. Le coordinate aumentano verso destra lungo l'asse X e verso il basso lungo l'asse Y.

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

Disegnare testo

Nella classe PdfCanvas, Docotic.Pdf fornisce due metodi principali per il rendering del testo: DrawString e DrawText. Entrambi usano il font corrente del canvas, quindi è consigliabile impostare il font necessario prima di disegnare qualsiasi testo.

Usare DrawString

DrawString disegna sempre una singola riga di testo. Il metodo inizia a disegnare dalla posizione corrente del testo del canvas, a meno che tu non usi un overload con coordinate esplicite. Alcuni overload consentono di specificare opzioni aggiuntive che controllano come viene disegnata la riga di testo.

Hai già visto un semplice esempio di DrawString nello snippet Hello, world!. Ecco un altro esempio che usa opzioni di disegno delle stringhe per sottolineare il testo.

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");

Usare DrawText

DrawText può renderizzare più righe di testo all'interno di un rettangolo specificato. Il metodo gestisce le interruzioni di riga e ritaglia il testo che non rientra nello spazio consentito. Le opzioni di disegno del testo definiscono l'allineamento orizzontale e verticale del testo e altri aspetti del suo posizionamento e rendering.

Ecco come disegnare testo in un PDF usando 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");

Per affinare l'aspetto del testo, puoi regolare le seguenti proprietà del canvas:

  • spaziatura tra i caratteri
  • spaziatura tra le parole
  • scalatura del testo
  • innalzamento del testo (spostamento della baseline)
  • modalità di rendering (riempimento, contorno, riempimento e contorno, e altre)

Per esempi pratici di metodi e proprietà relativi al testo, consulta il gruppo di esempi Text.

Aggiungere e usare i font

A meno che il font Helvetica predefinito non ti basti, dovresti aggiungere al PDF i font necessari per assicurarti che il testo appaia esattamente come previsto.

Docotic.Pdf può aggiungere font Type1, TrueType, Compact Font Format (CFF) e OpenType da:

  • la raccolta di font installati nel sistema
  • file e flussi esterni

Inoltre, puoi usare i 14 font Type1 integrati, disponibili in qualsiasi visualizzatore PDF.

Per usare un font nel tuo PDF, crea un oggetto PdfFont usando il metodo CreateFont o CreateFontFromFile dell'oggetto PdfDocument corrispondente. Quindi assegna il font al canvas prima di disegnare il testo. È anche una buona idea impostare la dimensione del font.

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");

Il font deve contenere i glifi per tutti i caratteri del testo che stai cercando di disegnare. In caso contrario, otterrai una CannotShowTextException. Usa PdfFont.ContainsGlyphsForText per verificare che il font contenga tutti i glifi richiesti.

Il supporto Unicode dipende dal tipo di font. I font Type 1 supportano solo il set di caratteri e la codifica Latin, con una sola eccezione. I font integrati Symbol e ZapfDingbats forniscono simboli matematici, greci e decorativi.

I font TrueType, CFF e OpenType in genere supportano Unicode, ma potrebbero non includere i glifi per tutti i caratteri Unicode.

Docotic.Pdf cerca di incorporare il minor numero possibile di byte dei font per mantenere piccolo il PDF di output. Tuttavia, quando un documento usa font con molti glifi, il file risultante può comunque essere relativamente grande. Usa PdfFont.RemoveUnusedGlyphs per ridurre al minimo il numero di byte aggiunti dai font incorporati.

Calcolare le dimensioni del testo

Poiché la Canvas API usa il posizionamento assoluto, spesso è necessario sapere quanto spazio occuperà un testo prima di disegnarlo. Questo è particolarmente importante quando produci testo in più passaggi, ad esempio suddividendo stringhe lunghe, allineando il testo con precisione o evitando sovrapposizioni con altri contenuti. La classe PdfCanvas fornisce diversi metodi che aiutano a misurare il testo usando il font e la dimensione del font attualmente selezionati.

Usa PdfCanvas.MeasureText per ottenere sia la larghezza sia l'altezza di una stringa così come apparirebbe sul canvas. I casi d'uso tipici includono:

  • determinare se il testo rientra in un'area data
  • calcolare manualmente le interruzioni di riga
  • posizionare blocchi di testo uno rispetto all'altro

Nei casi in cui stai centrando o allineando a destra il testo e ti serve solo l'estensione orizzontale, usa PdfCanvas.GetTextWidth. Per conoscere l'altezza di una riga di testo per il font corrente, usa PdfCanvas.GetTextHeight.

Disegnare immagini

Per disegnare un'immagine su un canvas PDF, crea prima un oggetto PdfImage e poi disegna quell'oggetto usando il metodo PdfCanvas.DrawImage.

Ecco come aggiungere un'immagine a un PDF in 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");

Il codice crea un oggetto immagine usando il metodo CreateImage dell'oggetto PdfDocument corrispondente e disegna l'immagine sul canvas della prima pagina.

Leggi come creare PDF da immagini per dettagli sui formati immagine supportati e su tecniche più avanzate di conversione immagine-PDF.

Usare la grafica vettoriale

Docotic.Pdf consente di disegnare linee rette, curve di Bezier e forme geometriche comuni direttamente su un canvas PDF usando i metodi della classe PdfCanvas. Usa metodi che iniziano con Draw (ad esempio DrawLineTo, DrawCircle, DrawRectangle) per posizionare segni visibili sul canvas.

Linee e curve vengono renderizzate usando la penna corrente, definita tramite PdfCanvas.Pen, che specifica colore di contorno, larghezza e altre proprietà di disegno. In base alla modalità di disegno, le forme possono essere tracciate, riempite, o tracciate e poi riempite. Il pennello corrente, accessibile tramite PdfCanvas.Brush, viene usato per riempire l'interno delle forme.

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");

Ogni canvas PDF mantiene uno stato grafico, che include la penna, il pennello, il font e le posizioni correnti. Usa SaveState per preservare lo stato corrente e RestoreState per tornare a uno stato precedente. Oltre a annullare trasformazioni temporanee e modifiche simili, il ripristino dello stato è l'unico modo per rimuovere il clipping una volta applicato.

I path grafici consentono di costruire forme complesse a partire da linee, curve e forme più semplici senza disegnarle immediatamente. Usa metodi Append come AppendLineTo o AppendRectangle per aggiungere segmenti al path corrente. I path non producono output visibile finché non li riempi o li tracci esplicitamente.

Puoi usare qualsiasi path grafico costruito come regione di clipping per limitare le operazioni di disegno successive. Il clipping rimane attivo finché lo stato grafico non viene ripristinato.

Esempi pratici ed eseguibili di lavoro con la grafica vettoriale sono disponibili nella sezione Graphics del repository di esempi.

Impostare colori e trasparenza

Puoi modificare i colori di contorno e di riempimento tramite la penna e il pennello di un canvas PDF. Per farlo, usa PdfPen.Color e PdfBrush.Color.

Illustrazione di forme colorate che gocciolano, alcune semplici e altre con pattern, che mostrano le funzionalità del Core API per colori e trasparenza.

Gli spazi colore dipendenti dal dispositivo supportati includono Gray, RGB e CMYK, rappresentati da PdfGrayColor, PdfRgbColor e 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 supporta spazi colore basati su CIE e indipendenti dal dispositivo, inclusi i colori L*a*b* e i colori calibrati basati su ICC. Il Core API supporta anche colori spot e spazi colore di separazione per flussi di lavoro che richiedono inchiostri personalizzati o output specifico per canale.

Il codice di esempio qui sotto mostra come creare colori Lab, colori basati su profilo e colori spot. Per eseguire l'esempio, scarica prima il profilo ICC usato.

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");

Puoi anche tracciare e riempire forme usando pattern di tiling. Un pattern è definito da una cella di pattern disegnata sul proprio canvas. Esistono due tipi:

  • Pattern colorati. Le loro celle definiscono i propri colori.
  • Pattern non colorati. Le loro celle vengono tinte dal colore della penna/del pennello al momento dell'uso.

Per usare un pattern, creane uno usando CreateColoredPattern o CreateUncoloredPattern dell'oggetto PdfDocument corrispondente. Quindi applica il pattern tramite PdfPen.Pattern e/o PdfBrush.Pattern. Consulta il codice di esempio per creare e usare pattern nel repository di esempi.

I colori semi-trasparenti consentono di disegnare forme, testo e immagini con opacità variabile. Usa PdfPen.Opacity e PdfBrush.Opacity per ottenere colori traslucidi.

Inoltre, le modalità di fusione controllano come il contenuto trasparente interagisce con ciò che si trova sotto. Per cambiare la modalità di fusione di un canvas, usa PdfCanvas.BlendMode.

Aggiungere e personalizzare le pagine

Docotic.Pdf espone la raccolta PdfDocument.Pages, che puoi usare per gestire tutte le pagine di un documento. Nella classe PdfDocument, ci sono due metodi principali che consentono di aggiungere nuove pagine: AddPage e InsertPage.

Usa AddPage() per aggiungere una nuova pagina alla fine del documento. Per inserire una pagina in qualsiasi posizione, usa InsertPage(index). Entrambi i metodi restituiscono la nuova istanza PdfPage.

Ogni nuova pagina ha la dimensione predefinita di 595 x 842 unità di spazio utente. È la dimensione di un foglio A4. Nella maggior parte dei casi, l'unità di spazio utente in PDF è 1/72 di pollice. O, per dirla diversamente, un'unità di spazio utente equivale a un pixel quando la risoluzione della pagina è di 72 pixel per pollice.

Puoi modificare la dimensione di una pagina in qualsiasi momento impostandone la larghezza e/o l'altezza a un numero specifico di unità di spazio utente.

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

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

Un'altra opzione è usare una delle dimensioni predefinite:

page.Size = PdfPaperSize.Ledger;

È anche possibile cambiare l'orientamento della pagina da verticale a orizzontale e ruotare una pagina di 90°, 180° o 270° in senso orario.

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

Oltre a impostare larghezza, altezza o una dimensione predefinita della pagina, è anche possibile regolare la dimensione della pagina insieme al ritaglio o ridimensionamento del contenuto esistente.

Riutilizzare contenuti con XObject

Un XObject PDF è un contenitore con grafica vettoriale, immagini e testo. Ogni XObject ha la propria area di disegno, quindi puoi creare XObject complessi quanto pagine PDF normali.

Gli XObject sono simili alle immagini vettoriali. Puoi riutilizzare lo stesso oggetto su più pagine senza ricreare il contenuto o aumentare la dimensione del documento. Puoi scalare e ruotare tali oggetti senza introdurre artefatti visivi. Grazie a queste caratteristiche, gli XObject sono ideali per elementi ripetuti come loghi, illustrazioni, sfondi, watermark e altre grafiche ricorrenti.

Creare e usare XObject

Per creare un XObject, usa il metodo PdfDocument.CreateXObject. Modifica la larghezza e l'altezza dell'oggetto, se necessario. Quindi riempi l'area di disegno con testo, immagini e grafica nello stesso modo di un normale canvas di pagina.

Usa il metodo PdfCanvas.DrawXObject nel tuo codice C# o VB.NET per aggiungere l'XObject ad altri canvas. Nota che puoi disegnare XObject su canvas forniti sia da pagine sia da altri XObject.

Ecco codice C# che crea un XObject con un'illustrazione e disegna l'illustrazione su due pagine.

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");

Trasformare pagine con XObject

Gli XObject consentono anche scenari che vanno oltre il semplice riuso della grafica. Un esempio comune è combinare due pagine PDF esistenti in un'unica pagina più grande. Convertendo ciascuna pagina sorgente in un XObject, puoi disegnarle affiancate su un nuovo canvas, creando di fatto un foglio di due pagine unito. Questo approccio ti dà il controllo completo su posizionamento, spaziatura e scalatura, rendendo facile costruire layout di confronto, pagine affiancate di libri o anteprime multi-pagina.

La stessa tecnica può essere applicata quando devi ridimensionare le pagine PDF. Invece di ridisegnare o ricostruire il contenuto, puoi creare un XObject dalla pagina originale e disegnarlo in scala alla nuova dimensione. Questo ti permette di ridurre pagine troppo grandi, ingrandire quelle piccole o normalizzare un documento con dimensioni miste con il minimo sforzo.

Ambito e limiti del Core API

Il Core API offre un controllo preciso e di basso livello sulla creazione di PDF, ma non fornisce funzionalità di layout automatico. Non ci sono margini, intestazioni, piè di pagina o logica di interruzione di pagina integrati, e tutto il contenuto deve essere posizionato manualmente. La misurazione del testo e la suddivisione su più pagine sono responsabilità lasciate interamente al tuo codice, rendendo questo l'approccio più manuale per creare PDF.

Il layout automatico, incluso il supporto per tabelle, paragrafi e interruzione di pagina, è disponibile tramite il Layout API di livello superiore.

Conclusione

Il Core API di Docotic.Pdf fornisce il controllo completo sulla creazione di PDF. Consente di disegnare testo, immagini e grafica vettoriale su aree di disegno fornite da pagine PDF, XObject e pattern di tiling.

L'API è progettata per scenari che richiedono un controllo preciso e di basso livello: posizioni ogni elemento esplicitamente, gestisci da solo la misurazione del testo e la suddivisione delle pagine e manipoli direttamente stato grafico, colori e trasparenza.

Nel complesso, il Core API è lo strumento più flessibile per creare PDF quando la priorità è precisione e controllo.

Prova la biblioteca con una chiave gratuita