Come impaginare le pagine PDF

Il metodo PdfDocumentBuilder.Generate fornisce un oggetto di tipo Document al suo delegato. Utilizza il metodo Pages di quell'oggetto per costruire le pagine del tuo documento. È necessario fornire un delegato che accetti un parametro di tipo PageLayout nel metodo.

Una chiamata al metodo è sufficiente se tutte le pagine del documento PDF hanno lo stesso layout. Se hai layout diversi nel tuo documento, usa più di una chiamata al metodo Pages. Ad esempio, puoi chiamare il metodo una volta per impaginare una copertina. Quindi richiama nuovamente il metodo per descrivere il corpo del report.

Ogni chiamata a Pages crea almeno una pagina. La pagina creata può essere vuota se non è previsto alcun contenuto.

Questo articolo fa parte di una serie sull'API Layout per la generazione di PDF. Se sei nuovo all'API, leggi prima la parte Introduzione all'API Layout.

Slot di contenuto

Per descrivere il layout delle pagine, utilizzare contenitori predefiniti. Li chiamo anche slot di contenuto. Puoi accedere a questi contenitori chiamando i metodi di un oggetto PageLayout.

Esistono tre slot principali: Content, Header e Footer. E due slot per contenuti aggiuntivi: Background e Foreground. Per impostazione predefinita, tutti e cinque i contenitori sono vuoti e non occupano spazio sulla pagina. Distribuisci il contenuto della tua pagina tra gli slot in base alle tue esigenze.

Leggi l'articolo Contenitori e loro contenuto per sapere come impaginare le tue pagine utilizzando i contenitori.

Intestazione e piè di pagina

Non sarai sorpreso di sapere che il contenuto dell'intestazione e del piè di pagina va rispettivamente negli slot Header e Footer. L'API ripete questi slot sopra e sotto il contenuto principale su ciascuna pagina generata. L'API Layout non divide mai il contenuto dell'intestazione o del piè di pagina tra le pagine. Otterrai una LayoutException se un'intestazione o un piè di pagina non si adattano a una pagina.

Contenuto principale

Il contenuto della pagina principale, come immagini, tabelle e testo, va nello slot Content. L'API Layout divide automaticamente il contenuto in pagine.

Il codice seguente assegna contenuto di testo semplice a tutti gli slot di contenuto principali. Il codice imposta anche i colori di sfondo per gli slot.

PdfDocumentBuilder.Create().Generate("pages-main-slots.pdf", doc => doc.Pages(pages => {
    pages.Header()
        .Text("This text goes to the header")
        .BackgroundColor(new PdfRgbColor(66, 135, 245));

    pages.Content()
        .Text("The main content goes in this slot")
        .BackgroundColor(new PdfRgbColor(242, 233, 206));

    pages.Footer()
        .Text("This is the footer contents")
        .BackgroundColor(new PdfRgbColor(194, 192, 188));
}));

Controlla il risultato del codice in pages-main-slots.pdf.

Come puoi vedere, ogni slot occupa solo una parte della pagina. L'area esatta dipende dal contenuto all'interno dello slot. Lo slot Header si attacca alla parte superiore della pagina. Lo slot Content inizia immediatamente dopo Header. Lo slot Footer rimane attaccato al fondo.

Contenuti aggiuntivi

Background e Foreground forniscono contenitori utilizzabili per filigrane, sovrapposizioni e sfondi. Tutto il contenuto nello slot Background va sotto l'intestazione, il piè di pagina e il contenuto principale di una pagina. Il contenuto nello slot Foreground copre tutto ciò che viene aggiunto alla pagina.

Questi contenitori occupano l'intera pagina. Questa è la caratteristica unica di questi contenitori. L'API ripete i loro contenuti su ogni pagina generata. Esattamente come avviene per i contenitori di intestazione e piè di pagina.

Ho aggiunto alcune righe al codice precedente per mostrare come utilizzare i contenitori Foreground e Background.

PdfDocumentBuilder.Create().Generate("pages-all-slots.pdf", doc => doc.Pages(pages => {
    // ... 

    pages.Background()
        .Background(new PdfRgbColor(208, 227, 204));

    pages.Foreground()
        .Rotate(45)
        .Text(new string(' ', 30) + "Your watermark could go here, in the foreground");
}));

Per il contenitore Background, non fornisco alcun testo o qualcosa del genere. Specifico solo il colore di sfondo. Tutto sotto l'intestazione, il contenuto principale e il piè di pagina mostreranno quella tonalità di verde.

Ruoto il contenuto nel contenitore Foreground e vi aggiungo del testo. A causa degli spazi iniziali, il testo non copre il contenuto dell'intestazione o del piè di pagina. Il contenuto di tutti i contenitori è visibile nella pagina.

Puoi vedere il risultato del codice in pages-all-slots.pdf.

Impostazioni

Finora tutti gli snippet di codice si concentravano sui contenitori che compongono le pagine. È tempo di vedere come personalizzare le pagine stesse, piuttosto che i loro spazi di contenuto.

Per impostare le pagine, utilizzare i metodi della classe PageLayout. Ricorda che un oggetto PageLayout può descrivere più di una pagina. Le chiamate ai metodi influenzeranno tutte le pagine che descrivi.

Misurare

Probabilmente, l'impostazione più basilare è la dimensione della pagina. Puoi utilizzare il metodo Size per specificare una delle dimensioni predefinite per le tue pagine. Ci sono tutti i soliti formati come A4, Ledger o Monarch Envelope.

Facoltativamente, è possibile specificare un orientamento per le pagine. È possibile impostare una dimensione di pagina personalizzata fornendo la larghezza e l'altezza in punti.

Margini

I margini della pagina possono contribuire alla leggibilità, all'estetica e alla composizione complessiva delle tue pagine.

Imposta tutti i margini sullo stesso valore in punti utilizzando il metodo Margin. Utilizza i metodi MarginVertical e MarginHorizontal per impostare solo i margini verticali o orizzontali. Utilizza i metodi MarginLeft/Top/Right/Bottom per specificare ciascun margine in modo indipendente.

Stile del testo

L'API Layout fornisce la classe TextStyle per la creazione di stili di testo. Puoi creare e applicare stili al testo per ottenere l'aspetto desiderato.

Ci sono casi in cui gran parte del testo sulle tue pagine utilizza lo stesso stile. Puoi impostare quello stile come stile di testo predefinito per le pagine. Lo stile predefinito influisce su tutto il testo negli slot di contenuto principali. Ma puoi sovrascrivere lo stile predefinito per determinati elementi. Basta applicare un altro stile a parti di testo che dovrebbero apparire diverse.

PdfDocumentBuilder.Create().Generate("pages-text-styles.pdf", doc =>
{
    var defaultStyle = TextStyle.Parent.FontSize(30);
    var tightSpacing = TextStyle.Parent.LetterSpacing(-0.1);

    doc.Pages(pages =>
    {
        pages.TextStyle(defaultStyle);

        pages.Content().Text(t =>
        {
            t.Line("This line uses the default text style.");
            t.Line("This line uses a tight letter spacing.").Style(tightSpacing);
            t.Line("This line uses the default text style, again.");
        });
    });
});

Puoi vedere il risultato del codice in pages-text-styles.pdf.

Tieni presente che puoi impostare stili di testo a livello di documento utilizzando il metodo Document.Typography. Ogni proprietà nella classe Typography definisce uno stile per un caso d'uso. Questi stili sovrascrivono lo stile specificato dal metodo PageLayout.TextStyle. Ad esempio, la proprietà Typography.Body sovrascrive lo stile predefinito per il testo nei contenitori Content.

Direzione del contenuto

Ci sono lingue scritte da destra a sinistra. L'API Layout gestisce perfettamente il testo in queste lingue. Ma dovresti specificare esplicitamente la direzione del testo.

Se la maggior parte del testo sulle tue pagine è in una lingua RTL, puoi impostare da destra a sinistra come direzione predefinita del contenuto per le pagine. Potrai specificare direzioni diverse per qualsiasi contenitore nelle tue pagine.

PdfDocumentBuilder.Create().Generate("pages-content-direction.pdf", doc =>
{
    var defaultTextStyle = doc.TextStyleWithFont(SystemFont.Family("Calibri"));

    doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6).TextStyle(defaultTextStyle);

        pages.ContentFromRightToLeft();

        pages.Content().Column(column =>
        {
            column.Item()
                .ContentFromLeftToRight()
                .Text("There are languages written from right to left.");

            column.Item()
                .Text("هناك لغات تكتب من اليمين إلى اليسار.");

            column.Item()
                .Text("יש שפות שנכתבות מימין לשמאל.");
        });
    });
});

Nel codice sopra, ho impostato da destra a sinistra come direzione del contenuto predefinita. Per il contenitore con la versione inglese della frase, cambio la direzione da sinistra a destra. Puoi vedere il risultato del codice in pages-content-direction.pdf.

Numeri di pagina

Durante la generazione di PDF, l'API Layout calcola automaticamente il numero di pagina corrente. Calcola anche il numero totale di pagine del documento. Puoi ottenere i numeri chiamando i metodi CurrentPageNumber e PageCount di qualsiasi contenitore di testo. Non importa se il contenitore si trova nell'intestazione, nel piè di pagina o nello spazio del contenuto principale.

PdfDocumentBuilder.Create().Generate("pages-page-numbers.pdf", doc => doc.Pages(pages =>
{
    pages.Content().Text(t =>
    {
        t.Span("This line is on page ");
        t.CurrentPageNumber();
        t.Line();
        t.Line("Check the footer.");
    });

    pages.Footer().Row(r =>
    {
        r.AutoItem().Text("Created with Docotic.Pdf Layout API");

        r.RelativeItem(2).Text(t =>
        {
            t.AlignRight();

            t.Span("Page ");
            t.CurrentPageNumber();
            t.Span(" of ");
            t.PageCount();
        });
    });
}));

Il risultato del codice è in pages-page-numbers.pdf.

Entrambi i metodi restituiscono TextPageNumber che puoi utilizzare per formattare i numeri.

L'esempio Aggiungi intestazione e piè di pagina ai documenti PDF mostra come applicare una formattazione personalizzata ai numeri di pagina.

Codice d'esempio

Abbiamo alcune app di esempio che coprono le funzionalità sopra menzionate in modo più dettagliato. Per favore, dedica un po' di tempo a controllarli.

• Layout di pagina nei documenti PDF
• Aggiungi intestazione e piè di pagina ai documenti PDF
• Stile del testo