Questa pagina può contenere testo tradotto automaticamente.
Come impaginare le pagine PDF
Il metodo PdfDocumentBuilder.Generate fornisce al relativo delegato un oggetto di tipo Document. Usa il metodo Pages di quell'oggetto per costruire le pagine del documento. Devi fornire al metodo un delegato che accetti un parametro di tipo PageLayout.
Una chiamata al metodo è sufficiente se tutte le pagine del documento PDF hanno lo stesso layout. Se nel documento hai layout diversi, usa più di una chiamata al metodo Pages. Ad esempio, puoi chiamare il metodo una volta per impaginare una pagina di copertina. Poi richiama il metodo per descrivere il corpo del report.
Ogni chiamata a Pages crea almeno una pagina. La pagina creata può essere vuota se non viene fornito alcun contenuto.
Questo articolo fa parte di una serie su Layout API per la generazione di PDF. Se sei nuovo dell'API, leggi prima la parte Introduzione a Layout API.
Slot di contenuto
Per descrivere il layout delle pagine, usa contenitori predefiniti. Li chiamo anche slot di contenuto. Puoi accedere a questi contenitori chiamando i metodi di un oggetto PageLayout.
Ci sono 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 nella pagina. Distribuisci il contenuto della pagina tra gli slot in base alle tue esigenze.
Leggi l'articolo Contenitori e i loro contenuti per sapere come impaginare le pagine usando i contenitori.
Intestazione e piè di pagina
Non ti sorprenderà sapere che il contenuto dell'intestazione e del piè di pagina va negli slot Header e Footer, rispettivamente. L'API ripete questi slot sopra e sotto il contenuto principale su ogni pagina generata. Layout API non divide mai il contenuto dell'intestazione o del piè di pagina tra le pagine. Riceverai una LayoutException se un'intestazione o un piè di pagina non entra in una pagina.
Contenuto principale
Il contenuto principale della pagina, come immagini, tabelle e testo, va nello slot Content. Layout API divide automaticamente quel contenuto tra le pagine.
Il codice seguente assegna un semplice contenuto testuale a tutti gli slot del contenuto principale. 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 aggancia alla parte superiore della pagina. Lo slot Content inizia immediatamente dopo Header. Lo slot Footer si aggancia alla parte inferiore.
Contenuto aggiuntivo
I contenitori 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 il loro contenuto su ogni pagina generata. Esattamente come fa per i contenitori di intestazione e piè di pagina.
Ho aggiunto alcune righe al codice precedente per mostrare come usare 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 altro. Specifico solo il colore di sfondo. Tutto ciò che si trova sotto l'intestazione, il contenuto principale e il piè di pagina mostrerà 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 in tutti i contenitori è visibile sulla pagina.
Puoi vedere il risultato del codice in pages-all-slots.pdf.
Impostazioni
Finora, tutti gli snippet di codice si sono concentrati sui contenitori che compongono le pagine. È il momento di vedere come personalizzare le pagine stesse, invece dei relativi slot di contenuto.
Per configurare le pagine, usa i metodi della classe PageLayout. Ricorda che un oggetto PageLayout può descrivere più di una pagina. Le chiamate ai metodi influiranno su tutte le pagine descritte.
Dimensioni
Probabilmente, l'impostazione più basilare è la dimensione della pagina. Puoi usare il metodo Size per specificare una delle dimensioni predefinite per le tue pagine. Ci sono tutte le dimensioni comuni come A4, Ledger o Monarch Envelope.
Facoltativamente, puoi specificare un orientamento per le pagine. È possibile impostare una dimensione personalizzata delle pagine fornendo larghezza e 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 allo stesso valore in punti usando il metodo Margin. Usa i metodi MarginVertical e MarginHorizontal per impostare solo i margini verticali o orizzontali. Usa i metodi MarginLeft/Top/Right/Bottom per specificare ogni margine in modo indipendente.
Stile del testo
Layout API fornisce la classe TextStyle per creare stili di testo. Crei e applichi stili al testo per ottenere l'aspetto desiderato.
Ci sono casi in cui gran parte del testo nelle tue pagine usa 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 del contenuto principale. Ma puoi sovrascrivere lo stile predefinito per determinati elementi. Basta applicare un altro stile ai pezzi di testo che devono apparire in modo diverso.
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.
Nota che puoi configurare gli stili di testo a livello di documento usando il metodo Document.Typography. Ogni proprietà della 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. Layout API gestisce senza problemi il testo in queste lingue. Ma dovrai specificare esplicitamente la direzione del testo.
Se la maggior parte del testo nelle tue pagine è in una lingua RTL, puoi impostare la direzione da destra a sinistra come direzione predefinita del contenuto per le pagine. Potrai specificare una direzione diversa 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 predefinita del contenuto. Per il contenitore con la versione inglese della frase, cambio la direzione in da sinistra a destra. Puoi vedere il risultato del codice in pages-content-direction.pdf.
Numeri di pagina
Durante la generazione del PDF, Layout API calcola automaticamente il numero della pagina corrente. Calcola anche il numero totale di pagine nel documento. Puoi ottenere i numeri chiamando i metodi CurrentPageNumber e PageCount di qualsiasi contenitore di testo. Indipendentemente dal fatto che il contenitore si trovi nell'intestazione, nel piè di pagina o nello slot 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 un'istanza TextPageNumber che puoi usare 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. Dedica un po' di tempo a provarle.