Generatore PDF .NET

Tradotto da Bit Miracle. Articolo originale di Sergey Bobrovsky

Aggiornato il 30 aprile 2026

Grazie a Docotic.Pdf, è possibile generare documenti PDF componendoli con elementi strutturali come pagine, contenitori, blocchi di testo, immagini, collegamenti, intestazioni, piè di pagina, tabelle, elenchi e altro ancora. Questi elementi sono disponibili tramite l'API Layout di alto livello, fornita dal componente aggiuntivo gratuito Layout per Docotic.Pdf. L'API supporta anche componenti personalizzati riutilizzabili.

L'API Layout consente di definire i documenti interamente tramite codice C# o VB.NET, utilizzando un approccio fluido. Sulla base di questa descrizione, il generatore PDF fornito dal componente aggiuntivo può produrre documenti con layout di complessità arbitraria, da semplici pagine a report PDF altamente strutturati.

Nozioni di base sulla generazione di PDF

Per generare documenti PDF utilizzando l'API Layout, è necessario il componente aggiuntivo gratuito Layout. È inoltre necessaria una chiave di licenza per utilizzare la libreria principale e i componenti aggiuntivi. È possibile utilizzare una chiave di prova gratuita o una chiave acquistata.

Installa il componente aggiuntivo

Il metodo consigliato è installare il componente aggiuntivo tramite NuGet.

Install-Package BitMiracle.Docotic.Pdf.Layout

Il gestore di pacchetti gestirà automaticamente le dipendenze.

Se preferisci installare il componente aggiuntivo manualmente, inizia scaricando l'archivio ZIP contenente i file binari di Docotic.Pdf. Estrai l'archivio e aggiungi i riferimenti alle seguenti DLL:

• BitMiracle.Docotic.Pdf.dll
• BitMiracle.Docotic.Pdf.Layout.dll dalla sottocartella Layout add-on.

Ottieni una chiave di licenza

Per provare la libreria, richiedi una chiave di licenza gratuita a tempo limitato compilando il modulo sulla pagina di download di Docotic.Pdf. Se hai già acquistato una licenza, utilizza il codice che ti è stato fornito dopo l'acquisto.

Il componente aggiuntivo Layout è gratuito e non richiede una licenza aggiuntiva. Puoi utilizzare l'API Layout con la licenza Docotic.Pdf che già possiedi.

Ciao mondo! con l'API Layout

Ecco un esempio di codice che utilizza l'API per generare un PDF con la classica frase "Hello, world!":

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

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

Questo codice genera un PDF di una sola pagina con il testo nell'angolo in alto a sinistra.

Comprensione dell'esempio di codice

L'esempio inizia aggiungendo una chiave di licenza. Senza una licenza, la libreria Docotic.Pdf non genererà alcun file. Il codice per la generazione del PDF inizia alla riga successiva.

Il codice crea un'istanza del generatore di documenti chiamando il metodo statico PdfDocumentBuilder.Create(). La chiamata al metodo Generate avvia il processo di generazione del PDF. Questo metodo accetta due parametri: il nome del file da produrre e un delegato di tipo Action<Document>. Il componente aggiuntivo genera hello.pdf come risultato della chiamata a Generate.

Per sapere quale layout deve avere il PDF, il generatore di documenti chiama il delegato con un'istanza di Document. Il codice del delegato compone il contenuto del documento. In questo esempio, il delegato utilizza il metodo Pages per fornire al generatore un altro delegato che definisce il layout delle pagine del documento.

Il generatore chiama il delegato fornito al metodo Pages con un'istanza di PageLayout. Questa istanza rappresenta una o più pagine del documento. Il numero esatto di pagine dipende dal contenuto aggiunto.

Il delegato di pagina chiama il metodo Content per accedere al contenitore di layout per il contenuto principale della/e pagina/e. Una chiamata concatenata al metodo Text del contenitore aggiunge il testo di esempio alla pagina. Consulta la guida sui contenitori di layout per una spiegazione dettagliata del loro funzionamento.

Il generatore di documenti suddivide automaticamente il contenuto tra le pagine, creando esattamente il numero di pagine necessarie per contenere tutti i dati aggiunti al contenitore di layout del contenuto principale. In questo esempio, è sufficiente una sola pagina, quindi l'output contiene esattamente una pagina.

Compiti comuni oltre al campione di base

Il codice di esempio crea innanzitutto un'istanza di PdfDocumentBuilder e quindi chiama il metodo Generate per produrre un PDF. È possibile configurare il builder prima che inizi a generare il PDF.

Ad esempio, è possibile produrre un PDF crittografato fornendo un gestore di crittografia al builder. È anche possibile specificare metadati che il builder deve includere nel documento generato. Per maggiori dettagli su come personalizzare il builder, fare riferimento all'articolo dedicato.

Il codice di esempio utilizza solo il contenitore di layout dello slot di contenuto principale, ma sono disponibili anche altri slot di contenuto. Ecco l'elenco completo dei metodi di PageLayout per accedere agli slot di contenuto:

• Background() - restituisce il livello di sfondo, che viene coperto da altro contenuto.
• Header() - restituisce l'intestazione comune a tutte le pagine.
• Content() - restituisce lo slot di contenuto principale della pagina.
• Footer() - restituisce il piè di pagina comune a tutte le pagine.
• Foreground() - restituisce il livello di primo piano, che appare sopra altro contenuto.

Solo il contenuto dello slot principale influisce sul numero di pagine del PDF generato. Il generatore di documenti ripete tutti gli slot tranne quello fornito da Content() su ogni pagina. Per ulteriori informazioni sugli slot di contenuto, consultare l'articolo sul layout di pagina.

Molti documenti utilizzano layout diversi su pagine diverse. Ad esempio, la prima pagina potrebbe avere un design in stile copertina, mentre le pagine successive utilizzano un layout più semplice. Alcuni documenti includono pagine speciali per le tabelle o applicano sfondi diversi a seconda della sezione. Per generare tali documenti con Docotic.Pdf e il componente aggiuntivo Layout, è necessario richiamare il metodo Document.Pages più volte. È possibile trovare un esempio funzionante nel nostro repository di esempi.

Organizzazione del codice

Per codice breve, come nell'esempio, va bene concatenare le chiamate e usare lambda annidate. Quando si sviluppa qualcosa di più complesso, può essere più conveniente suddividere il codice in metodi separati. Questo rende il codice più facile da leggere e da manutenere.

Ecco come appare l'esempio "Hello, world!" quando il codice è suddiviso in metodi.

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

Perché generare PDF con l'API Docotic.Pdf Layout?

L'API Layout è un metodo moderno e intuitivo per generare PDF a partire da blocchi componibili, senza la necessità di comprendere i dettagli interni del formato PDF. Consente di impaginare i PDF con prestazioni elevate e un comportamento deterministico e prevedibile. È possibile utilizzare l'API in scenari di generazione di documenti ad alto volume.

L'API è disponibile quando si utilizza Docotic.Pdf insieme al componente aggiuntivo gratuito Layout. Sia Docotic.Pdf che il componente aggiuntivo Layout sono DLL interamente gestite, senza blocchi di codice non sicuri. L'API Layout è implementata senza dipendenze esterne di terze parti, come browser o binari Skia, risultando in una soluzione leggera, a basso overhead, facile da implementare e gestire.

Panoramica dell'API

L'API Layout è un'API fluida e piacevole da usare. Descrivi il layout del tuo documento interamente tramite codice, utilizzando elementi di layout flessibili, e il generatore adatta il flusso del contenuto, lo impagina automaticamente e genera il risultato come PDF.

Il componente aggiuntivo Layout utilizza un sistema di layout dichiarativo basato sul flusso. I suoi elementi di layout includono elenchi, colonne, righe, tabelle, immagini, blocchi di testo, intestazioni e piè di pagina, contenitori e altro ancora. Invece di posizionare manualmente gli elementi a coordinate precise, descrivi come devono comportarsi. Il generatore di documenti calcola quindi il layout finale e crea il PDF.

Il sistema di layout basato sul flusso garantisce che il layout si adatti alle dimensioni della pagina e al contenuto. Grazie a questo sistema, il componente aggiuntivo eccelle nella creazione di layout complessi, strutturati e basati su regole. Puoi annidare diversi tipi di contenitori e costruire strutture sofisticate senza sacrificare la leggibilità.

Quando lavori con l'API Layout, puoi concatenare la maggior parte delle chiamate. Ciò si traduce in un codice più compatto ed espressivo rispetto alle API tradizionali. L'ordine delle chiamate in una catena è importante. Tutto è fortemente tipizzato, garantendo la sicurezza in fase di compilazione e facilitando il refactoring del codice. È inoltre possibile eseguire unit test sul codice che utilizza l'API Layout.

Per rendere l'implementazione del layout ancora più concisa, è possibile estendere l'API con metodi personalizzati e creare un DSL pulito ed espressivo attorno ad essa.

Per ulteriori informazioni sul posizionamento e sulla creazione di DSL, consultare l'articolo che spiega come controllare le dimensioni, la posizione, l'allineamento e il comportamento di rendering dei contenitori.

Versioni .NET e supporto della piattaforma

È possibile utilizzare l'API Layout in progetti destinati a .NET Standard 2.1 e framework successivi. In altre parole, il componente aggiuntivo Layout è compatibile con .NET dalla versione 5 alla 10. Inoltre, è supportato .NET Core 3.0 e versioni successive.

È possibile generare PDF con l'API Layout in applicazioni ASP.NET Core, app MAUI, Unity, Xamarin e applicazioni console. Docotic.Pdf con il componente aggiuntivo Layout può produrre PDF su Windows, macOS e Linux.

Piattaforme cloud e immagini Docker

Docotic.Pdf con il componente aggiuntivo Layout può essere eseguito negli ambienti cloud Azure e AWS, comprese le configurazioni serverless. La libreria e il componente aggiuntivo supportano pienamente le modifiche dinamiche dell'hardware, l'autoscaling e altre funzionalità runtime native del cloud.

Nella maggior parte degli scenari cloud, è necessaria una licenza illimitata. Le FAQ sulle licenze spiegano come scegliere la licenza appropriata per le applicazioni cloud.

L'API Layout funziona direttamente nei container Docker. Non è necessaria alcuna configurazione speciale per generare PDF quando si eseguono la libreria e il componente aggiuntivo Layout all'interno di un container.

Aggiungere testo ai file PDF

Il testo è una parte fondamentale di qualsiasi documento PDF. È possibile utilizzare i metodi Text della classe LayoutContainer per aggiungere testo a uno slot di contenuto.

Il testo si estende

Nell'esempio "Hello, world", ho utilizzato l'overload LayoutContainer.Text(string) per aggiungere del testo al contenuto principale della pagina. Ora esaminiamo un altro overload del metodo 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.");
}

Questo codice utilizza i metodi Span e Line della classe TextContainer per aggiungere testo alla riga corrente. Il metodo Line completa inoltre la riga corrente. Il codice di esempio utilizza anche il metodo Hyperlink per allegare un collegamento a una risorsa esterna a uno specifico span di testo.

Si noti come il codice di esempio applichi una formattazione forte alla prima riga utilizzando il metodo Style. Esploriamo ora il concetto di stili di testo in modo più dettagliato.

Stili di testo

Gli stili di testo consentono di personalizzare l'aspetto del testo. La classe TextStyle fornisce metodi per modificare la dimensione del carattere, la spaziatura tra le lettere, i colori e altre proprietà del testo. Gli oggetti TextStyle sono immutabili, quindi ogni chiamata di metodo produce una nuova istanza di stile. È possibile applicare stili di testo a diversi livelli di layout.

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 proprietà TextStyle.Parent restituisce uno stile speciale in cui tutte le proprietà del testo sono indefinite. Nell'esempio precedente, il codice disegna "Hello, World!" in blu, con la seconda parola sottolineata, utilizzando una dimensione del carattere di 30 punti.

Questo accade perché il codice:

• imposta la dimensione del carattere a 30 punti a livello di pagina,
• quindi imposta il colore del testo su blu per lo spazio di contenuto principale,
• infine applica lo stile di sottolineatura all'ultimo span di testo.

Ogni stile successivo eredita i precedenti tramite la proprietà TextStyle.Parent.

Utilizzando i metodi della classe TextStyle, è possibile, tra le altre cose, cambiare la direzione del testo da destra a sinistra. Per un altro esempio di utilizzo dell'ereditarietà degli stili di testo, consultare il nostro repository di esempi.

Tipografia

La classe TextStyle consente di personalizzare tutte le proprietà del testo, ad eccezione del carattere associato. Per modificare il carattere predefinito, utilizzare i metodi Document.TextStyleWithFont per creare uno stile di testo basato su un carattere specifico. È possibile utilizzare un carattere installato nel sistema operativo oppure caricarne uno da un file o da uno stream.

Dopo aver creato uno stile basato su un carattere, è possibile applicare ulteriori proprietà opzionali e quindi utilizzare lo stile risultante su un elemento di testo (span). Questo esempio in C# mostra come utilizzare un carattere di sistema.

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

Il metodo TextStyleWithFont include un parametro opzionale che specifica come il font deve essere incorporato nel documento generato. Per impostazione predefinita, la libreria:

• incorpora i glifi utilizzati per i font TrueType/OpenType,
• incorpora tutti i glifi per i font Type1 e CFF,
• non incorpora i glifi per i font PDF integrati (font Base14).

A causa di queste impostazioni predefinite, i documenti che utilizzano font TrueType e OpenType potrebbero rimanere di dimensioni ridotte anche quando vengono utilizzati font di grandi dimensioni. È inoltre possibile specificare un caricatore di font personalizzato, font di fallback e un gestore per i glifi mancanti. Consultare il codice di esempio nel nostro repository di esempi per i dettagli sulla gestione dei font nei documenti PDF.

L'API Layout fornisce una raccolta di stili predefiniti, a cui è possibile accedere e che è possibile modificare tramite 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());
    });
});

Consiglio di sovrascrivere gli stili predefiniti configurando la tipografia per l'intero documento, sebbene non sia obbligatorio e sia comunque possibile applicare stili di testo a livello di singolo elemento di testo.

Con la classe Typography, non è necessario memorizzare i riferimenti agli stili di testo in variabili. È sufficiente registrare gli stili desiderati utilizzando i metodi di Document.Typography e successivamente accedervi tramite le proprietà dell'oggetto Typography. Consultare l'esempio di tipografia per vedere come utilizzare stili di testo predefiniti e personalizzati durante la generazione di documenti PDF.

Lavorare con intestazioni e piè di pagina

Molti documenti PDF reali, come report o fatture, includono intestazioni e piè di pagina. Questa sezione mostra come aggiungerli a 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();
    });
}

Il metodo BuildPagesHeader imposta una dimensione del carattere più piccola per il testo dell'intestazione. Utilizza due righe per il contenuto dell'intestazione: una con il nome dell'utente corrente e un'altra con la data corrente. Il testo è allineato a destra.

Si noti che il codice non specifica esplicitamente alcuna dimensione per l'intestazione. Occupa l'intera larghezza della pagina meno i margini sinistro e destro e la sua altezza dipende dall'altezza delle righe di testo.

Il metodo BuildPagesFooter mostra come posizionare il numero di pagina corrente nel piè di pagina del PDF. La libreria calcola automaticamente il numero di pagina corrente e il numero totale di pagine. È possibile accedere a questi valori utilizzando i metodi CurrentPageNumber e PageCount di un oggetto TextContainer.

L'API Layout fornisce anche un modo per formattare i numeri di pagina. Ad esempio, è possibile disegnare i numeri di pagina esadecimali in questo modo:

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

Il nostro archivio di esempi contiene un altro esempio di aggiunta di un'intestazione e di un piè di pagina a un PDF. Questo esempio formatta i numeri di pagina come numeri romani.

Inserimento di immagini

Come dice il proverbio, un'immagine vale più di mille parole. Nei preventivi o nelle ricevute, spesso si include il logo aziendale o un'altra immagine importante. Per questo esempio, userò un'immagine semplice e gradevole.

Per utilizzare un'immagine, è necessario prima aggiungerla al documento. La libreria può caricare immagini da un file o da un flusso. Sono supportati solo i formati raster: PNG, JPEG, JPEG 2000, BMP, GIF e TIFF.

Una volta ottenuto un oggetto Image, è possibile impostarlo come contenuto di uno o più contenitori di layout richiamando il metodo Image del contenitore. È possibile ridimensionare, ruotare, aggiungere spaziatura e disporre l'immagine come qualsiasi altro contenuto.

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

Il codice di esempio utilizza sia testo che un'immagine nello slot del contenuto principale. Tuttavia, un contenitore di layout può contenere solo testo o solo un'immagine. Per includere entrambi nello slot del contenuto principale della pagina, è necessario un contenitore composto.

Utilizzo un contenitore Column per posizionare il testo e l'immagine verticalmente, uno dopo l'altro. Il metodo Item del contenitore Column fornisce un sottocontenitore. Una chiamata a Item crea un contenitore per il testo e un'altra crea un contenitore per l'immagine. Il contenitore composto con tutti i suoi sottocontenitori diventa il contenuto principale.

Per eseguire il codice di esempio, scarica l'immagine del fiore dal nostro repository di esempi e posizionala nella directory di lavoro della tua app.

Immagini online

Se disponi solo dell'URL di un'immagine anziché di un file, scarica l'immagine in un flusso di memoria e crea un oggetto Image da tale flusso. L'esempio seguente mostra come utilizzare le immagini online con 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);
            });
        });
    });
}

Poiché il metodo esegue un'operazione asincrona (scaricando un'immagine da un URL), viene dichiarato come async Task anziché void. Chi lo chiama deve utilizzare await per assicurarsi che la generazione del PDF venga completata correttamente. Nel proprio codice, un metodo simile potrebbe anche restituire un valore, nel qual caso verrebbe dichiarato come async Task<TResult>.

Creazione di elenchi

Cos'è una lista? Si può pensare a una lista come a un gruppo di elementi numerati scritti uno sotto l'altro. L'API Layout non fornisce un tipo di contenitore specifico per le liste, ma è facile implementarne uno utilizzando altri contenitori composti.

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

Il codice di esempio crea l'elenco come una colonna di righe. Ogni riga contiene due elementi: il primo (a sinistra) contiene il numero dell'elemento e il secondo (a destra) contiene il testo dell'elemento. Il codice imposta esplicitamente la spaziatura tra gli elementi in ciascuna riga.

Per disporre gli elementi, il contenitore Row deve avere la dimensione di ciascun elemento specificata esplicitamente oppure calcolarla. In questo esempio, vengono utilizzati i metodi AutoItem e RelativeItem. Di conseguenza, il contenitore Row calcola la larghezza necessaria per il primo elemento e quindi utilizza la larghezza rimanente disponibile per il secondo elemento.

Utilizzando questo approccio e regolando l'aspetto delle righe secondo necessità, è possibile creare un elenco che si adatti al meglio al layout e allo stile del documento.

Tavoli da costruzione

Molti documenti PDF contengono tabelle, il che non sorprende poiché le tabelle migliorano la chiarezza e l'organizzazione dei dati. Questa sezione mostra come creare una tabella in un PDF utilizzando 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()
    );
}

Il codice di esempio crea una semplice tabella che visualizza informazioni di base sui mesi dell'anno corrente e dei tre anni precedenti. Il codice definisce tre colonne con larghezze relative. Le colonne più a sinistra e più a destra sono quattro volte più larghe della colonna centrale.

Il codice definisce anche l'intestazione della tabella aggiungendo celle di intestazione e specificando il testo e il colore di sfondo per ciascuna cella. Quando una tabella non entra in una singola pagina, l'intestazione viene ripetuta su ogni pagina occupata dalla tabella. È possibile osservare questo comportamento nel PDF generato dal codice di esempio.

Per costruire le righe vengono utilizzati due semplici cicli. Il ciclo esterno itera sugli anni, mentre il ciclo interno itera sui mesi in ordine inverso. Il ciclo interno recupera le informazioni relative a ciascun mese e quindi aggiunge tre celle per formare una riga.

Per maggiori dettagli, è possibile leggere l'articolo che spiega in dettaglio le funzionalità del contenitore Tabella.

Creazione di collegamenti PDF interni

I documenti PDF supportano i collegamenti interni che consentono ai lettori di passare a un'altra sezione dello stesso file. In un visualizzatore PDF, questi collegamenti appaiono come elementi di testo o immagini cliccabili. Funzionano come i collegamenti ipertestuali, ma anziché puntare a un sito web esterno, permettono di navigare all'interno del documento stesso.

Molti documenti PDF utilizzano collegamenti interni per segnalibri o indice, aiutando i lettori a spostarsi rapidamente tra le sezioni. Ecco come aggiungere un collegamento a una sezione del documento utilizzando 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");
        });
    });
});

Il codice di esempio trasforma il testo della prima pagina in un collegamento alla sezione con il nome specificato. Questo viene fatto richiamando il metodo SectionLink sul contenitore di layout che contiene il testo. La sezione potrebbe non esistere ancora a questo punto. Il testo diventa cliccabile in un visualizzatore PDF.

Il codice contrassegna quindi il testo della seconda pagina come inizio della sezione con lo stesso nome. Il suo aspetto e il suo comportamento non cambiano, ma diventa la destinazione del collegamento sulla prima pagina. Questo viene fatto richiamando il metodo Section sul contenitore di layout corrispondente.

In questo esempio, sia il link che il suo target sono elementi di testo (span), ma è possibile creare sezioni e link su qualsiasi contenitore di layout. Può trattarsi di un contenitore con un'immagine, un contenitore di tabella o un contenitore creato dall'utente.

Per un esempio su come creare un indice PDF consultare il nostro repository di esempi.

Progettazione di layout PDF complessi

L'API Layout offre una varietà di contenitori di layout che è possibile combinare per produrre documenti PDF di complessità arbitraria. È inoltre possibile estendere l'API con componenti personalizzati.

Gli esempi in questa pagina sono volutamente semplici, progettati per creare documenti diretti in modo da potersi concentrare sulle idee principali senza perdersi nei dettagli. Se si desidera vedere come combinare diversi contenitori per generare un PDF più complesso, consultare l'esempio corrispondente nel nostro repository di esempi su GitHub.

Oltre a utilizzare i contenitori predefiniti, è possibile definire e utilizzare componenti di layout personalizzati. Questi componenti sono particolarmente utili quando si desidera che una singola classe incapsuli sia i dati che la logica di layout. Mantenere tutto in un unico posto rende il componente più facile da comprendere, modificare e riutilizzare, offrendo al contempo un modo flessibile per gestire layout complessi.

Per creare un componente di layout personalizzato, implementare l'interfaccia ILayoutComponent nella propria classe. Durante la generazione di un PDF, la libreria chiama il metodo Compose dell'interfaccia e fornisce un oggetto LayoutContext. Il tuo codice può utilizzare questo oggetto per creare elementi di layout e accedere alle informazioni sul documento in fase di generazione.

Per aggiungere un componente di layout personalizzato al tuo layout, chiama il metodo Component della classe LayoutContainer. In termini di dimensioni e posizionamento, un componente personalizzato si comporta esattamente come testo o immagini.

Per un esempio di implementazione di un componente personalizzato con l'interfaccia ILayoutComponent, consulta l'esempio Componenti di layout.

Altri modi per creare PDF

Docotic.Pdf offre diversi modi per creare PDF, ognuno adatto a scenari differenti. Questa sezione spiega quando è opportuno utilizzare l'API di Layout e quando altri approcci potrebbero essere più indicati.

Quando preferire l'API Layout

L'API Layout di Docotic.Pdf è un potente strumento per generare PDF da layout strutturati. Consente di creare documenti combinando testo, immagini, contenitori e tabelle in strutture annidate di complessità arbitraria. Il processo di generazione è veloce, utilizza una quantità di memoria ragionevole e si comporta in modo prevedibile.

Docotic.Pdf e il componente aggiuntivo Layout formano un set leggero e completamente autonomo. L'API non richiede librerie esterne o browser per generare PDF. Questo la rende una scelta ideale per microservizi .NET, applicazioni cloud (in particolare quelle serverless) e altri ambienti in cui le dimensioni sono un fattore critico.

Poiché il layout del documento è definito nel codice, è possibile eseguire unit test su qualsiasi sua parte. La logica di Layout può essere riutilizzata come qualsiasi altro codice ed è possibile incapsulare sia i dati che il comportamento del layout in componenti personalizzati.

Alternative all'API Layout

Un articolo dedicato fornisce un confronto dettagliato di tutti i metodi per creare PDF con Docotic.Pdf. Di seguito sono elencate alcune delle alternative più comunemente utilizzate.

• Conversione da HTML a PDF
  Riutilizza i modelli HTML/CSS esistenti. Scegli l'approccio da HTML a PDF quando il tuo team produce già documenti in HTML/CSS e hai bisogno di versioni PDF di tali documenti.

• Generazione di PDF di basso livello
  Offre il massimo controllo disponibile nella libreria sulla struttura e sul contenuto del PDF. Scegli questa opzione quando hai bisogno di posizionamento a livello di pixel o grafica vettoriale complessa. Questo approccio è consigliato per scenari critici in termini di prestazioni o quando è richiesto il minimo ingombro possibile.

• Generazione di PDF basata su modelli
  Offre un modo rapido e prevedibile per compilare documenti senza doverne progettare o organizzare gli elementi. Scegli questa opzione quando disponi di una struttura PDF predefinita, come ad esempio modelli approvati o soggetti a controllo di conformità, e devi solo modificare i campi di testo, sostituire i segnaposto, allegare documenti correlati ed eseguire attività simili.

• Unione e composizione di PDF
  Consente di creare un PDF a partire da elementi esistenti anziché da zero. Scegli questa opzione quando disponi di immagini, pagine scansionate o altri PDF che devono essere combinati in un unico file.

Confronto con altre soluzioni di generazione di PDF

Questa sezione contiene due tabelle comparative: una con i punti salienti e un'altra con informazioni dettagliate e strutturate su come Docotic.Pdf con il componente aggiuntivo Layout si confronta con altre soluzioni diffuse per la generazione di PDF.

Punti chiave del confronto

Esistono valide opzioni per generare PDF, anche gratuite. Tuttavia, funzionalità come la firma, la crittografia o l'unione di documenti variano, il che può limitare la scelta degli strumenti più adatti alle proprie esigenze.

Dettaglia

Esamina la tabella per comprendere il contesto più ampio e trarre le tue conclusioni.

Conclusione

Docotic.Pdf, con il componente aggiuntivo Layout, offre un metodo moderno, performante e di alta qualità per generare PDF in C# e VB.NET. La libreria permette di creare report, estratti conto, fatture e documenti simili. La sua API, ben progettata e intuitiva, offre un'esperienza di sviluppo eccellente. È possibile contare sul supporto professionale fornito da Bit Miracle per Docotic.Pdf e i suoi componenti aggiuntivi.

A differenza di altre soluzioni per la generazione di PDF, Docotic.Pdf è un'API PDF completa. La libreria consente di firmare i PDF generati con firme digitali, incluse le firme con LTV (Lifetime Value). Docotic.Pdf è in grado di utilizzare certificati archiviati su hardware sicuro come token USB e smart card. Sono supportati anche i moduli di sicurezza hardware (HSM) basati su cloud, come Microsoft Azure Key Vault e AWS Key Management Service (KMS).

Con Docotic.Pdf, puoi allegare documenti di supporto come fogli di calcolo o note vocali ai PDF generati. Per visualizzare i documenti su una pagina web o in un'interfaccia simile, puoi creare immagini in miniatura da una o più delle loro pagine.

Prossimi passi:

• Esplora gli esempi di codice per l'API Layout.
• Confronta la generazione di PDF tramite blocchi componibili con altri approcci per la creazione di PDF.
• Contattaci per domande, feedback o casi limite.