Größe, Position und Darstellung von Containern

Der Inhalt ist der wichtigste Teil eines Dokuments. Es besteht kein Zweifel daran. Ein weiterer entscheidender Teil ist die Formatierung, die eine klare, professionelle und effektive Kommunikation schafft. Ein richtig formatiertes Dokument ist optisch ansprechend, lesbar und leicht zu navigieren.

Möglicherweise wissen Sie bereits, wie Sie Inhalte mithilfe von Containern organisieren. Und wie man ihnen eine Hintergrundfarbe verleiht. In diesem Artikel wird beschrieben, wie Sie Größe und Position für Container angeben. Es umfasst auch erweiterte Funktionen wie das bedingte Rendern von Inhalten. Es gibt Informationen zur Unterstützung von Inhaltsrichtungen von rechts nach links.

Die Klasse LayoutContainer bietet alles, was Sie zum professionellen Anordnen Ihrer Container benötigen. Durch Auffüllen und Ausrichten können Sie ein Dokument erstellen, das bei seinen Benutzern einen positiven Eindruck hinterlässt.

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.

Größe

Standardmäßig nehmen Container die kleinste Fläche ein, die für ihren Inhalt erforderlich ist. Anders ausgedrückt: Die Größe des Behälters entspricht der eigentlichen Größe seines Inhalts.

Die eigentliche Größe eines Bildes, die durch die Abmessungen der Bilddatei selbst bestimmt wird. Die eigentliche Größe einer Textspanne ist die Größe des Bereichs, der alle Glyphen in der Spanne abdeckt.

Die Größe eines zusammengesetzten Containers wie Column oder Table hängt von der Größe der Containerteile ab.

Width & Height

Mit den Methoden Width und Height ist es möglich, eine genaue Breite und Höhe eines Containers anzugeben. Dies ist sehr praktisch für Platzhaltercontainer.

Eine exakte Größe eignet sich auch gut für Bilder. Dies liegt daran, dass die Layout-API sie abhängig von ihrem ImageContentMode so skaliert, dass sie in den Container passen oder ihn füllen.

Bei zusammengesetzten Behältern und Behältern mit Text sollten Sie auf genaue Größen achten. Sie erhalten eine LayoutException, wenn ein Inhalt nicht in die angegebene Größe passt.

Es gibt Fälle, in denen Sie nur eine Einschränkung für die Breite oder Höhe festlegen möchten. Sie können Einschränkungen festlegen, indem Sie die Methoden MinWidth, MinHeight, MaxWidth und MaxHeight verwenden.

Bitte beachten Sie, dass die Bibliothek eine LayoutException auslöst, wenn es nicht möglich ist, die Einschränkungen zu erfüllen.

Extend

Ein Container kann so erweitert werden, dass er den größtmöglichen verfügbaren Platz einnimmt. Dies ist praktisch, wenn Sie die genaue Größe oder Größenbeschränkungen nicht kennen.

Verwenden Sie die Methode ExtendHorizontal, wenn der Container den gesamten verfügbaren Platz nur in horizontaler Richtung einnehmen soll. ExtendVertical ist nützlich, wenn Sie den Container nur in vertikaler Richtung erweitern möchten. Die Methode Extend bewirkt, dass der Container den gesamten verfügbaren Platz in beide Richtungen einnimmt.

var gray = new PdfGrayColor(75);
var text = "Content goes here";
var size = new PdfSize(150, 50);

PdfDocumentBuilder.Create().Generate("positioning-extend.pdf", doc =>
{
    for (int i = 0; i < 4; i++)
    {
        doc.Pages(page =>
        {
            page.Size(size);
            page.Content().Row(r =>
            {
                var container = r.AutoItem().Background(gray);
                switch (i)
                {
                    case 0:
                        container.Text(text);
                        break;

                    case 1:
                        container.ExtendHorizontal().Text(text);
                        break;

                    case 2:
                        container.ExtendVertical().Text(text);
                        break;

                    case 3:
                        container.Extend().Text(text);
                        break;
                }
            });
        });
    }
});

Das Ergebnis des obigen Codes ist in positioning-extend.pdf. Wie Sie sehen, enthält jede der vier Seiten den gleichen Text auf grauem Hintergrund. Die Größe des Containers ist jedoch auf jeder Seite unterschiedlich.

MinimalBox

LayoutContainer stellt die Methode MinimalBox bereit. Es ist das Gegenteil von Extend-Methoden. MinimalBox erzeugt verschachtelte Container, die nur den minimal notwendigen Platz für den Inhalt beanspruchen.

var gray = new PdfGrayColor(75);
var size = new PdfSize(150, 50);

PdfDocumentBuilder.Create().Generate("positioning-minimalbox.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Size(size);
        page.Content().MinimalBox().Background(gray).Text("I don't want more space");
    });

    doc.Pages(page =>
    {
        page.Size(size);
        page.Content().Background(gray).Text("I'll take everything");
    });
});

Das Ergebnis des obigen Codes befindet sich in positioning-minimalbox.pdf. Aufgrund des MinimalBox-Aufrufs belegt der Text auf der ersten Seite nur den erforderlichen Platz. Auf der zweiten Seite erstreckt sich der Text über die gesamte Seite.

Scale

Es ist möglich, beliebige Inhalte in einem Container zu skalieren. Die Methode Scale wirkt sich auf Inhalte sowohl in horizontaler als auch in vertikaler Richtung aus. Verwenden Sie die Methoden ScaleHorizontal oder ScaleVertical, um Inhalte nur in eine Richtung zu ändern. Bei den letzten beiden Methoden bleibt das Seitenverhältnis des Inhalts nicht erhalten.

Skalenwerte kleiner als 1 verringern die von einem Behälter eingenommene Fläche. Werte größer als 1 vergrößern die Fläche. Um Inhalte in einem Container umzudrehen, verwenden Sie einen negativen Skalierungswert. Beispielsweise führt ScaleVertical(-1) zu einer auf dem Kopf stehenden Version des Originalinhalts.

PdfDocumentBuilder.Create().Generate("positioning-scale.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Content()
            .MinimalBox()
            .Column(column =>
            {
                var scales = new[] { 0.5f, 0.75f, 1, 1.3f, 1.5f };

                foreach (var scale in scales)
                {
                    var percent = (int)(scale * 100);
                    column.Item()
                        .Scale(scale)
                        .Text(FormattableString.Invariant($"Scale equals {scale} ({percent}%)."))
                            .FontSize(20);

                    column.Item().LineHorizontal(0.5);
                }
            });
    });
});

Das Ergebnis des obigen Codes ist in positioning-scale.pdf.

ScaleToFit

Sie können den Inhalt verkleinern, um ihn an den verfügbaren Platz anzupassen. Zum Beispiel, wenn Sie einen festen Bereich zur Ausgabe des Namens oder der Adresse einer Person haben. Selbstverständlich können Sie bei einem längeren Namen den Bereich vergrößern. Ein einfacherer Ansatz könnte jedoch darin bestehen, den Text etwas zu verkleinern. Verwenden Sie die Methode ScaleToFit, um den Inhalt zu verkleinern.

ScaleToFit behält das Seitenverhältnis des Inhalts bei. Die Methode vergrößert den Inhalt nie. Bitte beachten Sie, dass diese Methode iterative Berechnungen durchführt. Dies kann den PDF-Generierungsprozess verlangsamen.

PdfDocumentBuilder.Create().Generate("positioning-scaletofit.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Content().Column(column =>
        {
            for (int i = 0; i < 5; i++)
            {
                column.Item()
                    .Width(230 - 20 * i)
                    .Height(20)
                    .ScaleToFit()
                    .Border(b => b.Thickness(0.5))
                    .Text(" This text should fit into the changing width.");
            }
        });
    });
});

Das Ergebnis des obigen Codes ist in positioning-scaletofit.pdf.

AspectRatio

Das Seitenverhältnis definiert das proportionale Verhältnis zwischen der Breite und Höhe eines Containers. Um das Seitenverhältnis eines Containers zu ermitteln, teilen Sie seine Breite durch seine Höhe.

Verwenden Sie die Methode AspectRatio, um das Seitenverhältnis für einen Container anzugeben. Es ist hilfreich, wenn Sie einen wiederverwendbaren Behälter für verschiedene Layouts oder Seitengrößen entwerfen.

PdfDocumentBuilder.Create().Generate("positioning-aspectratio.pdf", doc =>
{
    var ratios = new double[] { 0.25, 0.5, 1, 2 };
    foreach (var ratio in ratios)
    {
        var ratioText = ratio.ToString(CultureInfo.InvariantCulture);
        doc.Pages(page =>
        {
            page.Size(200, 200);
            page.Content().Column(column =>
            {
                column.Item()
                    .AspectRatio(ratio)
                    .Background(new PdfGrayColor(75))
                    .Text($"Width / Heigth = {ratioText}");
            });
        });
    }
});

Das Ergebnis des obigen Codes ist in positioning-aspectratio.pdf.

Die Methode verfügt über den optionalen Parameter vom Typ AspectRatioMode. Verwenden Sie diesen Parameter, um anzugeben, wie die Größe des Inhalts unter Beibehaltung des Seitenverhältnisses geändert werden soll.

Ein Container mit einem bestimmten Seitenverhältnis nimmt so viel Platz wie möglich ein. Je nach Modus versucht der Container, die gesamte verfügbare Fläche (Standard), Breite oder Höhe einzunehmen.

Bitte beachten Sie, dass die Bibliothek eine LayoutException auslösen kann. Dies geschieht, wenn die Anforderungen an Größe, Seitenverhältnis und Seitenverhältnismodus nicht erfüllt werden können.

Unconstrained

Für Container dürfen überhaupt keine Größenbeschränkungen gelten. Verwenden Sie die Methode Unconstrained, um alle Größenbeschränkungen aus einem Container zu entfernen.

Inhalte in einem uneingeschränkten Container nehmen Platz ein, dessen Größe der eigentlichen Größe des Inhalts entspricht. Der uneingeschränkte Container selbst nimmt keinen Platz ein. Dadurch können Geschwistercontainer den Inhalt des uneingeschränkten Containers abdecken.

PdfDocumentBuilder.Create().Generate("positioning-unconstrained.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Content().MinimalBox()
            .Border(b => b.Thickness(0.5))
            .Column(column =>
            {
                column.Item().Text("First item");

                column.Item().Unconstrained()
                    .Text("Second item ignores all size constraints");

                // Verwenden einer Leerzeile für das dritte Element
                column.Item().Text(new string(' ', 20))
                    .BackgroundColor(new PdfRgbColor(187, 237, 237), 50);

                column.Item().Text("Fourth item");
            });
    });
});

Das Ergebnis des obigen Codes ist in positioning-unconstrained.pdf. Im Code habe ich für das dritte Element in der Spalte eine Leerzeile mit halbtransparentem Hintergrund verwendet. Wie Sie sehen können, deckt der dritte Artikel teilweise den zweiten (uneingeschränkten) Artikel ab.

Position

Die Position eines Containers hängt von einer Reihe von Faktoren ab. Einige davon sind Ausrichtung, Auffüllung, Position des übergeordneten Containers und Inhaltsrichtung. Standardmäßig bleibt jeder Container an der äußerst linken und obersten verfügbaren Position hängen.

Padding

Eine der häufigsten Anforderungen besteht darin, etwas Platz um den Inhalt des Containers herum hinzuzufügen. LayoutContainer bietet eine Reihe von Methoden zum Einrichten des Füllbereichs eines Containers. Der Füllbereich ist der Raum zwischen seinem Inhalt und seinem Rand. Anders ausgedrückt stellt Padding den inneren Raum dar, der den Inhalt umgibt.

Die Methode Padding legt die Polsterung auf allen vier Seiten eines Containers gleichzeitig fest. Verwenden Sie die Methode PaddingHorizontal, um den Abstand nur auf der linken und rechten Seite festzulegen. PaddingVertical macht dasselbe nur auf der Ober- und Unterseite. Um die Polsterung individuell auf einer Seite einzurichten, verwenden Sie eine der Methoden PaddingTop/Bottom/Left/Right.

Align

Um die Position eines Containers zu ändern, verwenden Sie Ausrichtungsmethoden. Die Methoden AlignLeft/AlignCenter/AlignRight wenden eine horizontale Ausrichtung an und geben einen verschachtelten Container zurück. Die Methoden AlignTop/AlignMiddle/AlignBottom geben einen verschachtelten Container mit einer entsprechenden vertikalen Ausrichtung zurück.

Ein Container mit explizit angewendeter Ausrichtung nimmt den Bereich mit der minimal erforderlichen Breite und/oder Höhe ein. Der folgende Code erstellt eine Spalte mit zwei Elementen. Bei einem Element wurde die Ausrichtung explizit angewendet.

PdfDocumentBuilder.Create().Generate("positioning-alignment.pdf", doc =>
{
    var color = new PdfRgbColor(187, 237, 237);
    var text = "Hello";
    doc.Pages(page =>
    {
        page.Size(200, 100);
        page.Content().Column(c =>
        {
            c.Item().Extend().Background(color).Text(text);
            c.Item().Extend().AlignLeft().Background(color).Text(text);
        });
    });
});

Der Aufruf Extend bewirkt, dass beide Elemente die gesamte Seite belegen. Ich rufe die Methode AlignLeft für das zweite Element auf. Dieser Aufruf ändert die Position nicht, da der Container des Elements den Text standardmäßig linksbündig ausrichtet. Die explizit angewendete Ausrichtung verändert jedoch die vom zweiten Element eingenommene Fläche.

Das Ergebnis des obigen Codes ist in positioning-alignment.pdf.

Translate

Um einen Container horizontal und/oder vertikal neu zu positionieren, verwenden Sie die Methoden Translate/TranslateX/TranslateY. Der erste bewegt Container sowohl horizontal als auch vertikal. Die anderen beiden bewegen Container nur in eine Richtung.

Alle diese Methoden überschreiben die Position, behalten jedoch Größenbeschränkungen bei. Der verschobene Container kann sich mit anderen Containern überschneiden. Verwenden Sie negative Parameterwerte, um nach links und/oder nach oben zu gelangen. Positive Werte bewirken eine Verschiebung nach rechts bzw. nach unten.

PdfDocumentBuilder.Create().Generate("positioning-translate.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Size(200, 100);
        page.Content().Row(r =>
        {
            r.ConstantItem(50)
                .Background(new PdfRgbColor(187, 237, 237))
                .Text("Left");

            r.ConstantItem(50)
                // Verschieben dieses Elements um 10 Punkte nach links und 5 Punkte nach unten
                .Translate(-10, 5)
                .Background(new PdfRgbColor(15, 130, 9))
                .Text("Right");
        });
    });
});

Das Ergebnis des obigen Codes ist in positioning-translate.pdf.

Rotate

Gedrehte Inhalte, insbesondere Text, können Ihre Dokumente auf unterschiedliche Weise verbessern. Sie können beispielsweise Platz sparen und Ihr Dokument ansprechender und ästhetisch ansprechender gestalten.

LayoutContainer bietet zwei Ansätze zum Drehen von Inhalten. Ganz gleich, welchen Ansatz Sie verwenden, der Container mit dem gedrehten Inhalt berücksichtigt Positions- und Größenbeschränkungen.

Um 90 Grad drehen

Die Methoden RotateRight und RotateLeft drehen den Inhalt um 90 Grad im Uhrzeigersinn bzw. gegen den Uhrzeigersinn.

Der folgende Code zeigt, wie Sie ein Dokument mit vertikalem Text neben dem Hauptseiteninhalt erstellen.

PdfDocumentBuilder.Create().Generate("positioning-rotate.pdf", doc =>
{
    var lightGray = new PdfGrayColor(90);
    doc.Pages(page =>
    {
        page.Size(298, 210);
        page.Content().Row(r =>
        {
            r.AutoItem()
                .RotateLeft()
                .Background(lightGray)
                .Text("This content goes up");

            r.RelativeItem(1)
                .ExtendVertical()
                .PaddingHorizontal(10)
                .Column(t =>
                {
                    for (int i = 0; i < 15; i++)
                        t.Item().Text("The main content line goes here");
                });

            r.AutoItem()
                .RotateRight()
                .Background(lightGray)
                .Text("This content goes down");
        });
    });
});

Das Ergebnis des obigen Codes ist in positioning-rotate.pdf.

In jeden beliebigen Winkel drehen

Die Methode Rotate dreht den Inhalt um eine beliebige Gradzahl. Positive Zahlen bewirken eine Drehung im Uhrzeigersinn. Negative Zahlen stehen für eine Drehung gegen den Uhrzeigersinn.

Der Drehursprungspunkt ist die obere linke Ecke des Containers. Der gedrehte Inhalt kann sich mit anderen Containern überschneiden.

PdfDocumentBuilder.Create().Generate("positioning-rotate2.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Size(298, 210);
        page.Content()
            .Padding(25)
            .Background(new PdfGrayColor(70)) // grau
            .AlignCenter()
            .AlignMiddle()

            .Background(new PdfGrayColor(100)) // Weiß

            .Rotate(30)

            .Width(100)
            .Height(100)
            .Background(new PdfRgbColor(187, 237, 237)); // Blau
    });
});

Das Ergebnis des obigen Codes ist in positioning-rotate2.pdf.

Um den Drehursprungspunkt zu ändern, rufen Sie vor dem Aufruf von Rotate eine der Translate-Methoden auf. Vergessen Sie nicht, den Ursprung nach dem Anruf zurückzuübersetzen.

// Verschieben Sie den Rotationsursprungspunkt
.TranslateX(50)
.TranslateY(50)

.Rotate(30)

// zurückübersetzen
.TranslateX(-50)
.TranslateY(-50)

Bedingtes Layout

Das Layout Ihres PDF-Dokuments kann von einer Bedingung abhängen. Beispielsweise können Sie für gerade und ungerade Zeilen in einer Spalte unterschiedliche Ausrichtungen oder Hintergrundfarben verwenden.

Verwenden Sie die Methode Container, um einen verschachtelten Container mit einem Layout einzufügen, das von einer Bedingung abhängt. Durch den Aufruf dieser Methode wird die Aufrufkette nicht unterbrochen.

PdfDocumentBuilder.Create().Generate("positioning-container.pdf", doc =>
{
    doc.Pages(page =>
    {
        page.Content().Column(c =>
        {
            for (int i = 0; i < 15; i++)
            {
                c.Item()
                    .TextStyle(TextStyle.Parent.FontSize(14))
                    .Container(x => i % 2 == 0 ? x.Background(new PdfGrayColor(70)) : x)
                    .Text($"Row {i + 1}");
            }
        });
    });
});

Das Ergebnis des obigen Codes ist in positioning-container.pdf.

DSL

Einige Teile eines Dokuments können dasselbe Layout verwenden. Sie können beispielsweise den gleich aussehenden Rahmen festlegen oder die gleiche Formatierung verwenden. Gemäß dem Prinzip „Wiederholen Sie sich nicht“ empfehle ich, allgemeinen Code in eine Methode zu extrahieren.

Die Verwendung einer Erweiterungsmethode für den allgemeinen Code bietet zwei Vorteile:

• Sie können die Methode in Ketten von Methodenaufrufen verwenden
• Sie können einen aussagekräftigen Namen für eine Reihe von Methodenaufrufen festlegen

Aufgrund dieser Vorteile können Sie eine domänenspezifische Sprache (DSL) erstellen. Mit DSL kann Ihr Layoutcode kürzer und verständlicher sein.

static class LayoutHelpers
{
    public static LayoutContainer NumberCell(this Table table)
        => table.Cell().Border(b => b.Thickness(0.5)).PaddingHorizontal(10);
}

PdfDocumentBuilder.Create().Generate("positioning-dsl.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.NumberCell().Text($"{i + 1}");
    });
}));

Rendering-Prozess

Das Layout-Add-on ordnet alle Inhalte, die Sie in einen Container legen, nach Größen- und Positionsbeschränkungen an. Einige Inhalte können sich über mehrere Seiten erstrecken. Es gibt eine strenge Reihenfolge, in der Inhalte gerendert werden. Content Flow ist ein anderer Name für diese Reihenfolge.

LayoutContainer bietet einige Methoden zum Optimieren des Inhaltsflusses. Sie benötigen sie möglicherweise nicht jedes Mal, aber es gibt Fälle, in denen es keine andere Möglichkeit gibt, das erforderliche Layout zu erreichen.

PageBreak

Wenn Sie einen Inhaltsblock von einer neuen Seite aus beginnen müssen, verwenden Sie die Methode PageBreak. Beispielsweise können Sie die Methode verwenden, um ein Column-Element auf einer neuen Seite zu beginnen.

Hier ist ein Beispielcode, der eine Spalte so teilt, dass jede Seite nur zwei Zeilen enthält.

PdfDocumentBuilder.Create().Generate("positioning-pagebreak.pdf", doc => doc.Pages(page =>
{
    page.Size(200, 100);
    page.Content().Column(c =>
    {
        for (int i = 1; i <= 10; ++i)
        {
            c.Item().Text($"Item {i}");

            if (i % 2 == 0)
                c.Item().PageBreak();
        }
    });
}));

Das Ergebnis des obigen Codes ist in positioning-pagebreak.pdf.

ShowIf

Abhängig von einer Bedingung müssen Sie möglicherweise einen Container ein-/ausblenden. Für diesen Sonderfall des bedingten Layouts gibt es die Methode ShowIf, die im Wesentlichen ein syntaktischer Zucker ist.

Im folgenden Code verwende ich die Methode ShowIf, um nach jeweils 5 Elementen in einer Zeile eine vertikale Linie einzufügen.

PdfDocumentBuilder.Create().Generate("positioning-showif.pdf", doc => doc.Pages(page =>
{
    page.Size(200, 100);
    page.Content().Row(r =>
    {
        for (int i = 0; i < 10; ++i)
        {
            r.AutoItem().Text(i.ToString());
            r.AutoItem().ShowIf(i > 0 && (i + 1) % 5 == 0).LineVertical(0.5);
        }
    });
}));

Das Ergebnis des obigen Codes ist in positioning-showif.pdf.

ShowOnce

Sie können verhindern, dass sich ein Inhalt auf den nächsten Seiten wiederholt. Verwenden Sie die Methode ShowOnce, um die Layout-Engine anzuweisen, den Inhalt nur einmal vollständig zu rendern.

Überprüfen Sie den folgenden Code, um zu sehen, wie ShowOnce verhindert, dass „Environment“ auf der zweiten Seite angezeigt wird.

PdfDocumentBuilder.Create().Generate("positioning-showonce.pdf", doc => doc.Pages(page =>
{
    page.Size(200, 100);
    page.Content().Row(r =>
    {
        r.RelativeItem()
            .Background(new PdfGrayColor(75))
            .Border(b => b.Thickness(0.5))
            .Padding(5)
            .ShowOnce()
            .Text("Environment");

        r.RelativeItem()
            .Border(b => b.Thickness(0.5))
            .Padding(5)
            .Column(c =>
            {
                c.Item().Text(Environment.OSVersion.VersionString);
                c.Item().Text(string.Empty);
                c.Item().Text(
                    Environment.GetEnvironmentVariable("PROCESSOR_IDENTIFIER")
                    ?? string.Empty
                );
            });
    });
}));

Das Ergebnis des obigen Codes ist in positioning-showonce.pdf.

ShowEntire

Das Standardverhalten besteht darin, Inhalte zwischen Seiten aufzuteilen, wenn sie nicht auf eine Seite passen. Verwenden Sie die Methode ShowEntire, um den gesamten Container auf einer Seite darzustellen.

Bitte beachten Sie, dass die Bibliothek eine LayoutException auslöst, wenn es nicht möglich ist, den gesamten Inhalt auf einer Seite unterzubringen.

Aufgrund des ShowEntire-Aufrufs im folgenden Code beginnt der zweite Elementtext auf der zweiten Seite. Ohne den Aufruf würde es auf der ersten Seite beginnen, direkt nach dem ersten Artikeltext.

PdfDocumentBuilder.Create().Generate("positioning-showentire.pdf", doc => doc.Pages(page =>
{
    page.Size(100, 100);
    page.Content().Column(c =>
    {
        c.Item().Text(t =>
        {
            for (var i = 0; i < 4; i++)
                t.Line($"First item line {i + 1}");
        });

        c.Item()
            .Background(new PdfRgbColor(250, 123, 5))
            .ShowEntire()
            .Text(t =>
            {
                for (var i = 0; i < 4; i++)
                    t.Line($"Second item line {i + 1}");
            });
    });
}));

Das Ergebnis des obigen Codes ist in positioning-showentire.pdf.

EnsureSpace

In gewissem Sinne ist EnsureSpace ein Sonderfall der ShowEntire-Methode. Der Unterschied besteht darin, dass EnsureSpace nicht erfordert, dass der gesamte Inhalt auf eine Seite passt. Die Methode versucht nur, einen Teil des Inhalts mit der angegebenen Höhe anzupassen. Alles Weitere erfahren Sie auf der nächsten Seite.

Wenn ein nicht belegter Bereich der aktuellen Seite eine geringere Höhe als die angeforderte hat, wird der gesamte Inhalt auf einer neuen Seite gerendert. Hier liefert die Methode das gleiche Ergebnis wie die Methode ShowEntire.

StopPaging

Verwenden Sie die Methode StopPaging, um eine Ausgabe auf höchstens einer Seite zu erzeugen. Der Aufruf dieser Methode für einen Container verhindert dessen Paging. Das Layout-Add-on teilt den Inhalt dieses Containers nicht auf mehrere Seiten auf. Es werden keine Daten gerendert, die nicht auf eine Seite passen.

Der folgende Beispielcode fügt dem Dokument zwei Seitensätze hinzu. Beide Sets verwenden als Inhalt eine Liste mit Wochentagsnamen. Der erste Satz enthält nur eine Seite, da der Code die Methode StopPaging für den Inhaltscontainer der Seiten aufruft.

PdfDocumentBuilder.Create().Generate("positioning-stoppaging.pdf", doc =>
{
    static Action<TextContainer> produceText(string heading)
    {
        var text = string.Join('\n', DateTimeFormatInfo.InvariantInfo.DayNames);
        return t =>
        {
            t.Line(heading).BackgroundColor(new PdfRgbColor(250, 123, 5));
            t.Span(text);
        };
    }

    doc.Pages(page =>
    {
        page.Size(100, 100);
        page.Content()
            .StopPaging()
            .Text(produceText("Without paging:"));
    });

    doc.Pages(page =>
    {
        page.Size(100, 100);
        page.Content()
            .Text(produceText("Default behaviour:"));
    });
});

Das Ergebnis des obigen Codes ist in positioning-stoppaging.pdf.

SkipOnce

Sie können das Erscheinen von Inhalten verschieben. Wenn ein Container auf mehr als einer Seite angezeigt wird, verwenden Sie SkipOnce, um die erste Seite zu überspringen und den Inhalt ab der zweiten Seite auf allen Seiten darzustellen.

Diese Funktion ist für alle Arten von Headern nützlich, Sie können sie aber auch für andere Inhalte verwenden. Sehen Sie sich den folgenden Code an, um zu sehen, wie SkipOnce verhindert, dass die Kopfzeile auf der ersten Seite angezeigt wird.

PdfDocumentBuilder.Create().Generate("positioning-skiponce.pdf", doc => doc.Pages(page =>
{
    page.Size(298, 210);

    page.Header()
        .SkipOnce()
        .Text("This header will appear starting from page 2")
        .Style(TextStyle.Parent.Underline());

    page.Content().Column(c =>
    {
        for (int i = 0; i < 5; i++)
        {
            if (i > 0)
                c.Item().PageBreak();

            c.Item().Text($"Page {i + 1}");
        }
    });
}));

Das Ergebnis des obigen Codes ist in positioning-skiponce.pdf.

Inhaltliche Ausrichtung

Die Standardinhaltsrichtung ist von links nach rechts. Container richten ihren Text und andere Inhalte links aus.

Es gibt aber auch Sprachen, die von rechts nach links geschrieben werden (z. B. Arabisch und Hebräisch). Verwenden Sie beim Erstellen von Inhalten in diesen Sprachen die Methode ContentFromRightToLeft. Ein Aufruf ändert die Inhaltsrichtung des Containers von rechts nach links. Die Methode ändert auch die Standardausrichtung.

Wenn der Großteil des Inhalts auf Ihren Seiten in einer RTL-Sprache vorliegt, können Sie die Richtung von rechts nach links als Standardinhaltsrichtung für die Seiten festlegen. Verwenden Sie dazu die Methode PageLayout.ContentFromRightToLeft. Um dann die Standardinhaltsrichtung für ausgewählte Container zu überschreiben, verwenden Sie die Methode ContentFromLeftToRight.

Bitte beachten Sie, dass die Inhaltsrichtung keinen Einfluss auf die explizit angegebene Ausrichtung hat. Beispielsweise bleiben rechtsbündig ausgerichtete Inhalte auf der rechten Seite, unabhängig davon, welche Inhaltsrichtung Sie für den Container festlegen. Die visuelle Reihenfolge der untergeordneten Elemente unterscheidet sich je nach Richtung des Inhalts.