Container und ihr Inhalt

Ein Dokument besteht aus einer Reihe von Seiten. Jede Seite besteht ihrerseits aus einer Reihe von Inhaltselementen. Wie Sie vielleicht bereits wissen, stellt PageLayout Container für Haupt- und Zusatzinhalte bereit. Aber wohin mit diesen Behältern?

Container helfen dabei, Inhalte auf Seiten zu organisieren. Alles, was Sie auf eine Seite setzen, muss in einen Container gelangen. Wenn der Inhalt groß genug ist, kann ein Container Platz auf mehr als einer Seite beanspruchen.

Sie können Text oder ein Bild in einen Container einfügen. Zur Ausrichtung und Positionierung können Sie einen Behälter in einen anderen Behälter stellen. Es gibt Container, die Platz für mehr als einen Inhalt bieten.

Container auf einer Seite werden durch Objekte der Klasse LayoutContainer dargestellt. Verwenden Sie diese Klasse, um Größe, Position, Inhalt und Rendering-Prozess Ihrer Container einzurichten.

Dieser Artikel ist Teil einer Serie über die Layout-API für die PDF-Generierung. Wenn Sie mit der API noch nicht vertraut sind, lesen Sie zuerst den Teil Erste Schritte mit der Layout-API.

Wie Container funktionieren

Sie beginnen mit der Beschaffung eines Containers. Zum Beispiel durch Aufrufen der Methode PageLayout.Content. Diese Methode gibt einen Container zurück, der keinen Platz einnimmt und für den weder Inhalt noch Eigenschaften festgelegt sind. Verwenden Sie Methoden der Klasse LayoutContainer, um den Container einzurichten.

Es ist sehr wichtig zu verstehen, dass alle LayoutContainer-Methoden Inhalte in den Container legen. Wenn Sie dem Container Text hinzufügen, wird dieser erwartet. Doch was wird zum Inhalt, wenn man einen Einzug oder eine Breite festlegt?

Wenn Sie eine Containereigenschaft festlegen, erstellt die Bibliothek einen neuen Container mit der angegebenen Eigenschaft. Der neue Container wird zum Inhalt des ursprünglichen Containers. Als Ergebnis der Methode gibt die Bibliothek den verschachtelten Container zurück.

Eigenschaften verschachtelter Container wirken sich auf übergeordnete Container aus und umgekehrt. Beispielsweise wirkt sich die Breite eines verschachtelten Containers auf die Größe des übergeordneten Containers aus. Der Standardtextstil eines übergeordneten Containers wirkt sich auf Text in verschachtelten Containern aus. Das Layout-Add-on nutzt die Hierarchie der Container und ihrer Eigenschaften, um das resultierende Layout aufzubauen.

Das Ergebnis des folgenden Codes könnte Sie überraschen, aber nehmen Sie sich bitte etwas Zeit für die Analyse. Der Code veranschaulicht, wie verschachtelte Container funktionieren.

PdfDocumentBuilder.Create().Generate("containers-how.pdf", doc => doc.Pages(page =>
{
    page.Size(150, 150);
    page.Content()
        .Background(new PdfRgbColor(235, 64, 52)) // Rot

        .PaddingTop(50)
        .Background(new PdfRgbColor(187, 237, 237)) // Blau

        .PaddingRight(50)
        .Background(new PdfRgbColor(15, 130, 9)) // Grün

        .PaddingBottom(50)
        .Background(new PdfRgbColor(250, 123, 5)) // orangefarben

        .PaddingLeft(50)
        .Background(new PdfRgbColor(204, 204, 204)); // grau
}));

Dekoration

Beim Dokumentdesign geht es um mehr als nur das Anordnen von Text und Bildern. Ein richtig gestaltetes Dokument schafft nicht nur eine effektive, sondern auch eine optisch ansprechende Kommunikation.

Mit der Layout-API können Sie jedem Container eine Hintergrundfarbe zuweisen. Dies hilft dabei, eine Hierarchie innerhalb Ihrer Inhalte zu etablieren. Sie können Grenzen auch definieren, indem Sie Rahmen anwenden. Verwenden Sie vertikale und horizontale Linien, um Inhaltselemente zu trennen.

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

Die API unterstützt undurchsichtige und halbtransparente Farben in den Farbräumen Grau, RGB und CMYK. Neben durchgezogenen Linien bietet die Layout-API Unterstützung für Linien, die Strichmuster verwenden.

Das Ergebnis des obigen Codes befindet sich in containers-decor.pdf.

Inhalt

Sehen wir uns an, was die Klasse LayoutContainer zum Organisieren von Inhalten bereitstellt.

Text

Um einem Container Text hinzuzufügen, verwenden Sie eine der Text-Methoden.

Wenn der gesamte Text denselben Stil verwendet, verwenden Sie die einfache Kurzform der Methode. Diese Version akzeptiert eine Zeichenfolge und gibt ein TextSpan-Objekt zurück. Mit diesem Objekt können Sie den Textstil für den Bereich einrichten.

Es gibt eine andere Version der Text-Methode, die einen Delegaten vom Typ Action<TextContainer> akzeptiert. Verwenden Sie diese Version, um Abschnitte mit unterschiedlichen Stilen innerhalb eines Textblocks zu erstellen. TextContainer bietet Methoden zum Einfügen von Bildern und anderen Elementen zwischen Textbereichen. Es gibt weitere erweiterte Funktionen, wie die Möglichkeit, einen Abstand zwischen Absätzen festzulegen.

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

Das Ergebnis des Codes können Sie in containers-text.pdf sehen.

Image

Die Layout-API bietet Methoden zum Erstellen von Image-Objekten aus Bilddaten in einer Datei oder einem Stream. Jedes Image-Objekt kann als Inhalt eines Containers dienen. Sie können dasselbe Image-Objekt in mehreren Containern verwenden. Es gibt verschiedene Inhaltsmodi, die beeinflussen, wie das Bild im Container aussieht.

Die Bibliothek kann nur Bilder in Rasterformaten laden: PNG, JPEG, JPEG 2000, BMP, GIF und 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

Säulen bieten Platz für eine unbegrenzte Anzahl vertikal hintereinander platzierter Gegenstände. Sie können Elemente jeder Art innerhalb einer Spalte verwenden. Beispielsweise kann eine Spalte Bild- und Textelemente enthalten. Die Breite jedes Elements entspricht der Spaltenbreite. Die Höhe jedes Elements hängt vom Inhalt und den Eigenschaften des Elements ab.

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

Das Ergebnis des Codes können Sie in containers-column.pdf sehen.

Lesen Sie den Artikel Verbundbehälter, um ausführliche Informationen zu den Funktionen des Column-Containers zu erhalten.

Row

Row-Container helfen dabei, eine unbegrenzte Anzahl von Elementen horizontal zu organisieren. Jedes Element in einer Reihe ist ein Container. Dadurch können Sie Inhalte unterschiedlicher Art hintereinander anordnen.

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

Das Ergebnis des Codes können Sie in containers-row.pdf sehen.

Der Artikel Verbundbehälter enthält detaillierte Informationen zu Row-Containern.

Table

Verwenden Sie Table-Container zum Layouten Ihrer komplexesten Daten. Definieren Sie zunächst mindestens eine Spalte und füllen Sie dann Spalten und Zeilen, indem Sie die Methode Cell mehrmals aufrufen.

Tabellen können eine Kopf- und eine Fußzeile haben. Zellen in einer Tabelle können sich über mehr als eine Spalte und/oder Zeile erstrecken. Hier ist ein Code, der eine einfache Tabelle hinzufügt.

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

Das Ergebnis des Codes befindet sich in containers-table.pdf.

Lesen Sie im Artikel Table-Container alles über die Funktionen des Table-Containers.

Inlined

InlineContainer-Container bieten eine praktische Möglichkeit, einen Bereich mit Gegenständen aus einer Sammlung von Containern zu füllen. Sie fügen einfach Elemente nacheinander hinzu und die Bibliothek stellt sie nacheinander in eine Reihe. Wenn kein Platz zum Platzieren eines Elements vorhanden ist, beginnt die Bibliothek mit einer neuen Zeile.

Weitere Informationen zu InlineContainer-Containern finden Sie im Artikel Verbundbehälter.

Layers

Es gibt Fälle, in denen es am besten ist, Inhalte auf mehreren Ebenen zu platzieren. Der Container LayerContainer erfüllt genau diesen Zweck. Sie müssen genau eine primäre Ebene und eine beliebige Anzahl nicht-primärer Ebenen definieren. Die Layout-API erstellt Ebenen in derselben Reihenfolge, in der Sie sie erstellen.

Lesen Sie die Verbundbehälter für weitere Einzelheiten zum Typ LayerContainer.

Element

Dies ist eine besondere Art von Inhalt. Sie können ein Element dynamisch erstellen und das Ergebnis in einen Container stellen.

Dynamisch erstellte Elemente können ein Layout bereitstellen, das von der Seitenzahl, der Größe und anderen Eigenschaften abhängt.