Questa pagina può contenere testo tradotto automaticamente.
Contenitori e i loro contenuti
Un documento è un insieme di pagine. Ogni pagina, a sua volta, è un insieme di elementi di contenuto. Come forse già sai, la classe PageLayout fornisce contenitori per il contenuto principale e aggiuntivo. Ma cosa fare con questi contenitori?
I contenitori aiutano a organizzare il contenuto nelle pagine. Tutto ciò che inserisci in una pagina deve andare in un contenitore. Se il contenuto è abbastanza grande, un contenitore può occupare spazio su più di una pagina.
Puoi inserire del testo o un'immagine in un contenitore. Per scopi di allineamento e posizionamento, puoi inserire un contenitore dentro un altro contenitore. Esistono contenitori che offrono spazio per più di un elemento di contenuto.
I contenitori in una pagina sono rappresentati da oggetti della classe LayoutContainer. Usa questa classe per configurare dimensioni, posizione, contenuto e processo di rendering dei tuoi contenitori.
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.
Come funzionano i contenitori
Si inizia ottenendo un contenitore. Ad esempio, chiamando il metodo PageLayout.Content. Questo metodo restituirà un contenitore che non occupa spazio e non ha contenuto né proprietà impostate. Usa i metodi della classe LayoutContainer per configurare il contenitore.
La cosa molto importante da capire è che tutti i metodi di LayoutContainer inseriscono contenuto nel contenitore. Quando aggiungi del testo al contenitore, è normale. Ma cosa diventa il contenuto quando imposti un rientro o una larghezza?
Quando imposti una proprietà del contenitore, la libreria crea un nuovo contenitore con la proprietà specificata. Il nuovo contenitore diventa il contenuto del contenitore originale. La libreria restituisce il contenitore annidato come risultato del metodo.
Le proprietà dei contenitori annidati influenzano i contenitori padre e viceversa. Ad esempio, la larghezza di un contenitore annidato influenza le dimensioni del contenitore padre. Lo stile di testo predefinito di un contenitore padre influenza il testo nei contenitori annidati. L'add-on Layout usa la gerarchia dei contenitori e delle loro proprietà per costruire il layout risultante.
Il risultato del codice seguente potrebbe sorprenderti, ma dedica un po' di tempo ad analizzarlo. Il codice illustra come funzionano i contenitori annidati.
PdfDocumentBuilder.Create().Generate("containers-how.pdf", doc => doc.Pages(page =>
{
page.Size(150, 150);
page.Content()
.Background(new PdfRgbColor(235, 64, 52)) // rosso
.PaddingTop(50)
.Background(new PdfRgbColor(187, 237, 237)) // blu
.PaddingRight(50)
.Background(new PdfRgbColor(15, 130, 9)) // verde
.PaddingBottom(50)
.Background(new PdfRgbColor(250, 123, 5)) // arancione
.PaddingLeft(50)
.Background(new PdfRgbColor(204, 204, 204)); // grigio
}));
Decorazione
La progettazione di un documento non si limita a disporre testo e immagini. Un documento progettato correttamente crea una comunicazione non solo efficace ma anche gradevole dal punto di vista visivo.
Con Layout API, puoi applicare un colore di sfondo a qualsiasi contenitore. Questo aiuta a stabilire una gerarchia all'interno del contenuto. Puoi anche definire i confini applicando bordi. Usa linee verticali e orizzontali per separare gli elementi di contenuto.
PdfDocumentBuilder.Create().Generate("containers-decor.pdf", doc => doc.Pages(page =>
{
page.Size(150, 150);
page.Content()
.Background(new PdfRgbColor(250, 123, 5))
.Border(b =>
{
b.Color(new PdfGrayColor(0), 50);
b.Thickness(15);
})
.PaddingTop(74)
.LineHorizontal(2)
.Color(new PdfCmykColor(73, 45, 0, 4))
.DashPattern(new PdfDashPattern(new double[] { 8, 2 }));
}));
L'API supporta colori opachi e semitrasparenti negli spazi colore Gray, RGB e CMYK. Oltre alle linee continue, Layout API supporta linee che usano schemi di tratteggio.
Il risultato del codice precedente è in containers-decor.pdf.
Contenuto
Vediamo cosa offre la classe LayoutContainer per organizzare il contenuto.
Text
Per aggiungere del testo a un contenitore, usa uno dei metodi Text.
Se tutto il testo usa lo stesso stile, usa la versione abbreviata e semplice del metodo. Questa versione accetta una stringa e restituisce un oggetto TextSpan. Puoi usare questo oggetto per configurare lo stile del testo per la porzione.
Esiste un'altra versione del metodo Text che accetta un delegato di tipo Action<TextContainer>. Usa questa versione per avere porzioni con stili diversi all'interno di un unico blocco di testo. Il TextContainer fornisce metodi per inserire immagini e altri elementi tra le porzioni di testo. Ci sono altre funzionalità avanzate, come la possibilità di impostare una distanza tra i paragrafi.
PdfDocumentBuilder.Create().Generate("containers-text.pdf", doc => doc.Pages(page =>
{
page.Header().Text("This is a simple text span");
page.Content().Text(t =>
{
t.Span("This line contains ");
t.Span("some underlined text").Style(TextStyle.Parent.Underline());
});
}));
Puoi vedere il risultato del codice in containers-text.pdf.
Image
Layout API fornisce metodi per creare oggetti Image dai dati di un'immagine in un file o in uno stream. Qualsiasi oggetto Image può fungere da contenuto di un contenitore. Puoi usare lo stesso oggetto Image in più contenitori. Esistono diverse modalità di contenuto che influenzano l'aspetto dell'immagine all'interno del contenitore.
La libreria può caricare immagini solo in formati raster: PNG, JPEG, JPEG 2000, BMP, GIF e TIFF.
PdfDocumentBuilder.Create().Generate("containers-image.pdf", doc =>
{
var imageFile = new FileInfo(@"path-to-image.jpg");
var image = doc.Image(imageFile);
doc.Pages(pages =>
{
pages.Size(image.Width, image.Height);
pages.Content().Image(image, ImageContentMode.FitArea);
});
});
Column
Le colonne offrono spazio per un numero illimitato di elementi disposti verticalmente uno dopo l'altro. Puoi usare elementi di qualsiasi tipo all'interno di una colonna. Ad esempio, una colonna può contenere elementi immagine e testo. La larghezza di ogni elemento è uguale alla larghezza della colonna. L'altezza di ogni elemento dipende dal contenuto e dalle proprietà dell'elemento.
PdfDocumentBuilder.Create().Generate("containers-column.pdf", doc => doc.Pages(page =>
{
page.Content().Column(c =>
{
for (int i = 0; i < 10; i++)
{
PdfColor color = i % 2 == 0
? new PdfRgbColor(187, 237, 237)
: new PdfGrayColor(66);
c.Item().Background(color).Height(10 + i * 3);
}
});
}));
Puoi vedere il risultato del codice in containers-column.pdf.
Leggi l'articolo Contenitori composti per informazioni dettagliate sulle funzionalità del contenitore Column.
Row
I contenitori Row aiutano a organizzare un numero illimitato di elementi orizzontalmente. Ogni elemento in una riga è un contenitore. Per questo motivo, puoi inserire contenuto di tipi diversi in una riga.
var rowItems = new[] { "three", "two", "one" };
PdfDocumentBuilder.Create().Generate("containers-row.pdf", doc => doc.Pages(page =>
{
page.Content().Row(row =>
{
for (int index = 0; index < rowItems.Length; index++)
{
row.AutoItem().Text(rowItems[index]);
if (index != rowItems.Length - 1)
row.AutoItem().PaddingHorizontal(10).LineVertical(0.5);
}
});
}));
Puoi vedere il risultato del codice in containers-row.pdf.
L'articolo Contenitori composti contiene informazioni dettagliate sui contenitori Row.
Table
Usa i contenitori Table per impaginare i dati più complessi. Inizia definendo almeno una colonna e poi riempi colonne e righe chiamando più volte il metodo Cell.
Le tabelle possono avere un'intestazione e un piè di pagina. Le celle in una tabella possono estendersi su più di una colonna e/o riga. Ecco un codice che aggiunge una tabella semplice.
PdfDocumentBuilder.Create().Generate("containers-table.pdf", doc => doc.Pages(page =>
{
page.Content().Table(t =>
{
t.Columns(c =>
{
for (int i = 0; i < 4; ++i)
c.ConstantColumn(50);
});
for (int i = 0; i < 16; i++)
{
t.Cell()
.Border(b => b.Thickness(0.5))
.PaddingHorizontal(10)
.Text($"{i + 1}");
}
});
}));
Il risultato del codice è in containers-table.pdf.
Leggi tutte le funzionalità del contenitore Table nell'articolo Contenitore tabella.
Inlined
Il tipo di contenitore InlineContainer offre un modo comodo per riempire un'area con elementi provenienti da una raccolta di contenitori. Devi solo aggiungere gli elementi uno dopo l'altro e la libreria li dispone in una riga uno dopo l'altro. Se non c'è spazio per inserire un elemento, la libreria inizia una nuova riga.
Maggiori informazioni sui contenitori InlineContainer sono nell'articolo Contenitori composti.
Layers
Ci sono casi in cui è meglio inserire il contenuto su più livelli. Il tipo di contenitore LayerContainer serve esattamente a questo scopo. Devi definire esattamente un livello primario e un numero qualsiasi di livelli non primari. Layout API comporrà i livelli nello stesso ordine in cui li crei.
Leggi Contenitori composti per maggiori dettagli sul tipo LayerContainer.
Element
Questo è un tipo speciale di contenuto. Puoi creare un elemento dinamicamente e inserire il risultato in un contenitore.
Gli elementi creati dinamicamente possono fornire un layout che dipende dal numero di pagina, dalle dimensioni e da altre proprietà.