Diese Seite kann automatisch übersetzten Text enthalten.
Container und ihr Inhalt
Ein Dokument ist eine Menge von Seiten. Jede Seite ist wiederum eine Menge von Inhaltselementen. Wie Sie vielleicht bereits wissen, stellt die Klasse PageLayout Container für Haupt- und Zusatzinhalte bereit. Aber was macht man mit diesen Containern?
Container helfen, Inhalte auf Seiten zu organisieren. Alles, was Sie auf eine Seite setzen, muss in einen Container. Wenn der Inhalt groß genug ist, kann ein Container mehr als eine Seite einnehmen.
Sie können etwas Text oder ein Bild in einen Container einfügen. Für Ausrichtungs- und Positionierungszwecke können Sie einen Container in einen anderen Container einfügen. Es gibt Container, die Platz für mehr als ein Inhaltselement bieten.
Container auf einer Seite werden durch Objekte der Klasse LayoutContainer dargestellt. Verwenden Sie diese Klasse, um Größe, Position, Inhalt und Renderprozess Ihrer Container festzulegen.
Dieser Artikel ist Teil einer Reihe über Layout API zur PDF-Erstellung. Wenn Sie neu bei der API sind, lesen Sie zuerst den Teil Erste Schritte mit Layout API.
Wie Container funktionieren
Sie beginnen, indem Sie einen Container abrufen. Zum Beispiel durch Aufrufen der Methode PageLayout.Content. Diese Methode gibt einen Container zurück, der keinen Platz belegt und keinen Inhalt oder Eigenschaften gesetzt hat. Verwenden Sie Methoden der Klasse LayoutContainer, um den Container einzurichten.
Das sehr wichtige Verständnis ist, dass alle LayoutContainer-Methoden Inhalt in den Container einfügen. Wenn Sie dem Container etwas Text hinzufügen, ist das erwartungsgemäß. Aber was wird zum Inhalt, wenn Sie einen Einzug oder eine Breite festlegen?
Wenn Sie eine Container-Eigenschaft setzen, erstellt die Bibliothek einen neuen Container mit der angegebenen Eigenschaft. Der neue Container wird zum Inhalt des ursprünglichen Containers. Die Bibliothek gibt den verschachtelten Container als Ergebnis der Methode 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 übergeordneter Container aus. Der Standardtextstil eines übergeordneten Containers wirkt sich auf Text in verschachtelten Containern aus. Das Layout-Add-on verwendet die Hierarchie der Container und ihre Eigenschaften, um das resultierende Layout aufzubauen.
Das Ergebnis des folgenden Codes könnte Sie überraschen, aber nehmen Sie sich bitte etwas Zeit, es zu analysieren. 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)) // orange
.PaddingLeft(50)
.Background(new PdfRgbColor(204, 204, 204)); // grau
}));
Dekoration
Dokumentdesign umfasst mehr als das Anordnen von Text und Bildern. Ein richtig gestaltetes Dokument schafft nicht nur eine wirkungsvolle, sondern auch eine optisch ansprechende Kommunikation.
Mit Layout API können Sie jedem Container eine Hintergrundfarbe zuweisen. Das hilft, innerhalb Ihres Inhalts eine Hierarchie zu schaffen. Sie können auch Begrenzungen durch Rahmen definieren. 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 deckende und halbtransluzente Farben in den Farbräumen Gray, RGB und CMYK. Neben durchgezogenen Linien unterstützt Layout API auch Linien mit Strichmustern.
Das Ergebnis des obigen Codes finden Sie in containers-decor.pdf.
Inhalt
Sehen wir uns an, was die Klasse LayoutContainer für die Organisation von Inhalt bereitstellt.
Text
Um etwas Text zu einem Container hinzuzufügen, verwenden Sie eine der Methoden Text.
Wenn der gesamte Text denselben Stil verwendet, nutzen Sie die einfache Kurzform der Methode. Diese Variante akzeptiert einen String und gibt ein TextSpan-Objekt zurück. Sie können dieses Objekt verwenden, um den Textstil für den Span festzulegen.
Es gibt noch eine weitere Variante der Methode Text, die einen Delegate vom Typ Action<TextContainer> akzeptiert. Verwenden Sie diese Variante, um Spans mit unterschiedlichen Stilen innerhalb eines Textblocks zu haben. Der TextContainer bietet Methoden zum Einfügen von Bildern und anderen Elementen zwischen Textspans. Es gibt weitere erweiterte Funktionen, etwa 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());
});
}));
Sie können das Ergebnis des Codes in containers-text.pdf sehen.
Image
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 innerhalb des Containers aussieht.
Die Bibliothek kann Bilder nur 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
Spalten bieten Platz für eine unbegrenzte Anzahl von Elementen, die vertikal nacheinander angeordnet werden. Sie können Elemente beliebigen Typs 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);
}
});
}));
Sie können das Ergebnis des Codes in containers-column.pdf sehen.
Lesen Sie den Artikel Zusammengesetzte Container für detaillierte Informationen zu den Funktionen des Column-Containers.
Row
Row-Container helfen, eine unbegrenzte Anzahl von Elementen horizontal zu organisieren. Jedes Element in einer Zeile ist ein Container. Deshalb können Sie in eine Zeile Inhalte unterschiedlicher Typen einfügen.
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);
}
});
}));
Sie können das Ergebnis des Codes in containers-row.pdf sehen.
Der Artikel Zusammengesetzte Container enthält detaillierte Informationen zu Row-Containern.
Table
Verwenden Sie Table-Container, um Ihre komplexesten Daten zu layouten. Beginnen Sie damit, mindestens eine Spalte zu definieren, und füllen Sie dann Spalten und Zeilen, indem Sie die Methode Cell mehrfach aufrufen.
Tabellen können einen Header und einen Footer 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 finden Sie in containers-table.pdf.
Lesen Sie im Artikel Tabellencontainer über alle Funktionen des Table-Containers.
Inlined
Der Containertyp InlineContainer bietet eine bequeme Möglichkeit, einen Bereich mit Elementen aus einer Sammlung von Containern zu füllen. Sie fügen einfach Elemente nacheinander hinzu, und die Bibliothek setzt sie der Reihe nach in eine Zeile. Wenn kein Platz für ein Element vorhanden ist, beginnt die Bibliothek eine neue Zeile.
Weitere Informationen zu InlineContainer-Containern finden Sie im Artikel Zusammengesetzte Container.
Layers
Es gibt Fälle, in denen es am besten ist, Inhalte auf mehreren Ebenen zu platzieren. Der Containertyp LayerContainer dient genau diesem Zweck. Sie müssen genau eine primäre Ebene und beliebig viele nicht primäre Ebenen definieren. Layout API setzt die Ebenen in derselben Reihenfolge zusammen, in der Sie sie erstellen.
Lesen Sie den Artikel Zusammengesetzte Container für weitere Details zum Typ LayerContainer.
Element
Dies ist eine spezielle Art von Inhalt. Sie können ein Element dynamisch erstellen und das Ergebnis in einen Container einsetzen.
Dynamisch erstellte Elemente können ein Layout bereitstellen, das von Seitennummer, Größe und anderen Eigenschaften abhängt.