Contenitori e loro contenuto

Un documento è un insieme di pagine. Ogni pagina, a sua volta, è un insieme di contenuti. Come forse già saprai, PageLayout fornisce contenitori per contenuti principali e aggiuntivi. Ma cosa fare con questi contenitori?

I contenitori aiutano a organizzare i contenuti nelle pagine. Tutto ciò che metti in una pagina deve finire in un contenitore. Se il contenuto è sufficientemente 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, è possibile inserire un contenitore all'interno di un altro contenitore. Esistono contenitori che offrono spazio per più di un contenuto.

I contenitori su una pagina sono rappresentati da oggetti della classe LayoutContainer. Utilizza questa classe per impostare dimensioni, posizione, contenuto e processo di rendering dei tuoi contenitori.

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.

Come funzionano i contenitori

Inizi procurandoti un contenitore. Ad esempio, chiamando il metodo PageLayout.Content. Questo metodo restituirà un contenitore che non occupa spazio e non ha contenuto o proprietà impostate. Utilizza i metodi della classe LayoutContainer per impostare il contenitore.

La cosa molto importante da capire è che tutti i metodi LayoutContainer inseriscono il contenuto nel contenitore. Quando aggiungi del testo al contenitore, è previsto. Ma cosa diventa il contenuto quando imposti un rientro o una larghezza?

Quando imposti una proprietà 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 nidificati influiscono sui contenitori principali e viceversa. Ad esempio, la larghezza di un contenitore nidificato influisce sulla dimensione del contenitore principale. Lo stile di testo predefinito di un contenitore principale influisce sul testo nei contenitori nidificati. Il componente aggiuntivo Layout utilizza la gerarchia dei contenitori e le loro proprietà per creare il layout risultante.

Il risultato del seguente codice potrebbe sorprenderti, ma per favore dedica un po' di tempo ad analizzarlo. Il codice illustra come funzionano i contenitori nidificati.

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 documenti implica molto più che la semplice disposizione di testo e immagini. Un documento progettato correttamente crea non solo una comunicazione efficace ma anche visivamente accattivante.

Con l'API Layout, puoi applicare un colore di sfondo a qualsiasi contenitore. Ciò aiuta a stabilire una gerarchia all'interno dei tuoi contenuti. È inoltre possibile definire i confini applicando i bordi. Utilizza 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 semitraslucidi negli spazi colore Grigio, RGB e CMYK. Oltre alle linee continue, l'API Layout fornisce supporto per le linee che utilizzano modelli di trattini.

Il risultato del codice sopra è in containers-decor.pdf.

Contenuto

Vediamo cosa offre la classe LayoutContainer per l'organizzazione dei contenuti.

Text

Per aggiungere del testo a un contenitore, utilizza uno dei metodi Text.

Se tutto il testo utilizza lo stesso stile, utilizza la versione semplice e abbreviata del metodo. Quella versione accetta una stringa e restituisce un oggetto TextSpan. Puoi utilizzare quell'oggetto per impostare lo stile del testo per l'intervallo.

Esiste un'altra versione del metodo Text che accetta un delegato di tipo Action<TextContainer>. Utilizza quella versione per avere intervalli con stili diversi all'interno di un blocco di testo. TextContainer fornisce metodi per inserire immagini e altri elementi tra 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

L'API Layout fornisce metodi per creare oggetti Image da dati di immagine in un file o in un flusso. Qualsiasi oggetto Image può fungere da contenuto di un contenitore. Puoi utilizzare lo stesso oggetto Image in più contenitori. Esistono diverse modalità di contenuto che influiscono sull'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 posizionati verticalmente uno dopo l'altro. Puoi utilizzare elementi di qualsiasi tipo all'interno di una colonna. Ad esempio, una colonna può contenere immagini ed elementi di testo. La larghezza di ogni elemento è uguale alla larghezza della colonna. L'altezza di ciascun articolo dipende dal contenuto e dalle proprietà dell'articolo.

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 in orizzontale. Ogni elemento in una riga è un contenitore. Per questo motivo, puoi mettere in fila contenuti di diversi tipi.

PdfDocumentBuilder.Create().Generate("containers-row.pdf", doc => doc.Pages(page =>
{
    var rowItems = new[] { "three", "two", "one" };

    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

Utilizza i contenitori Table per disporre i dati più complessi. Inizia definendo almeno una colonna, quindi riempi colonne e righe chiamando più volte il metodo Cell.

Le tabelle possono avere un'intestazione e un piè di pagina. Le celle di una tabella possono estendersi su più colonne e/o righe. Ecco un codice che aggiunge una semplice tabella.

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

The result of the code is in containers-table.pdf.

Leggi tutte le funzionalità del contenitore Table nell'articolo Contenitore Table.

Inlined

Il contenitore InlineContainer fornisce un modo conveniente per riempire un'area con elementi da una raccolta di contenitori. Basta aggiungere gli elementi uno dopo l'altro e la libreria li mette in fila uno dopo l'altro. Se non c'è spazio per inserire un elemento, la libreria inizia una nuova riga.

Maggiori informazioni sui contenitori InlineContainer si trovano nell'articolo Contenitori composti.

Layers

Ci sono casi in cui è meglio posizionare il contenuto su più livelli. Il contenitore LayerContainer serve esattamente a questo scopo. È necessario definire esattamente un livello primario e un numero qualsiasi di livelli non primari. L'API Layout 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à.