So gestalten Sie das Layout von PDF-Seiten

Die Methode PdfDocumentBuilder.Generate stellt ihrem Delegaten ein Objekt vom Typ Document bereit. Verwenden Sie die Methode Pages dieses Objekts, um Ihre Dokumentseiten zu erstellen. Sie müssen einen Delegaten bereitstellen, der einen Parameter vom Typ PageLayout für die Methode akzeptiert.

Ein Aufruf der Methode reicht aus, wenn alle Seiten in Ihrem PDF-Dokument das gleiche Layout haben. Falls Sie unterschiedliche Layouts in Ihrem Dokument haben, verwenden Sie mehr als einen Aufruf der Methode Pages. Beispielsweise können Sie die Methode einmal aufrufen, um ein Deckblatt zu gestalten. Rufen Sie dann die Methode erneut auf, um den Berichtstext zu beschreiben.

Jeder Aufruf von Pages erstellt mindestens eine Seite. Die erstellte Seite kann leer sein, wenn kein Inhalt für sie bereitgestellt wird.

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.

Inhaltsslots

Um das Layout von Seiten zu beschreiben, verwenden Sie vordefinierte Container. Ich nenne sie auch Content-Slots. Sie können auf diese Container zugreifen, indem Sie Methoden eines PageLayout-Objekts aufrufen.

Es gibt drei Hauptslots: Content, Header und Footer. Und zwei Slots für zusätzliche Inhalte: Background und Foreground. Standardmäßig sind alle fünf Container leer und belegen keinen Seitenplatz. Sie verteilen Ihren Seiteninhalt entsprechend Ihren Anforderungen auf die Slots.

Lesen Sie den Artikel Container und ihr Inhalt, um zu erfahren, wie Sie Ihre Seiten mithilfe von Containern gestalten.

Kopf-und Fußzeile

Sie werden nicht überrascht sein zu erfahren, dass der Inhalt der Kopf- und Fußzeile in den Slots Header bzw. Footer abgelegt wird. Die API wiederholt diese Slots oberhalb und unterhalb des Hauptinhalts auf jeder generierten Seite. Die Layout-API teilt niemals Kopf- oder Fußzeileninhalte zwischen Seiten auf. Sie erhalten eine LayoutException, wenn eine Kopf- oder Fußzeile nicht auf eine Seite passt.

Hauptinhalt

Der Inhalt der Hauptseite, wie Bilder, Tabellen und Text, landet im Slot Content. Die Layout-API teilt diesen Inhalt automatisch in Seiten auf.

Der folgende Code weist allen Hauptinhaltsslots einfache Textinhalte zu. Der Code legt auch Hintergrundfarben für die Slots fest.

PdfDocumentBuilder.Create().Generate("pages-main-slots.pdf", doc => doc.Pages(pages => {
    pages.Header()
        .Text("This text goes to the header")
        .BackgroundColor(new PdfRgbColor(66, 135, 245));

    pages.Content()
        .Text("The main content goes in this slot")
        .BackgroundColor(new PdfRgbColor(242, 233, 206));

    pages.Footer()
        .Text("This is the footer contents")
        .BackgroundColor(new PdfRgbColor(194, 192, 188));
}));

Überprüfen Sie das Ergebnis des Codes in pages-main-slots.pdf.

Wie Sie sehen, nimmt jeder Slot nur einen Teil der Seite ein. Der genaue Bereich hängt vom Inhalt im Slot ab. Der Header-Slot bleibt oben auf der Seite. Der Content-Slot beginnt unmittelbar nach dem Header. Der Footer-Steckplatz bleibt unten hängen.

Zusätzlicher Inhalt

Background und Foreground stellen Container bereit, die für Wasserzeichen, Overlays und Hintergründe verwendet werden können. Der gesamte Inhalt im Slot Background befindet sich unter der Kopfzeile, der Fußzeile und dem Hauptinhalt einer Seite. Der Inhalt im Foreground-Slot deckt alles ab, was der Seite hinzugefügt wird.

Diese Container nehmen die gesamte Seite ein. Das ist das Alleinstellungsmerkmal dieser Behälter. Die API wiederholt deren Inhalte auf jeder generierten Seite. Genau wie bei Kopf- und Fußzeilencontainern.

Ich habe dem obigen Code einige Zeilen hinzugefügt, um zu zeigen, wie die Container Foreground und Background verwendet werden.

PdfDocumentBuilder.Create().Generate("pages-all-slots.pdf", doc => doc.Pages(pages => {
    // ... 

    pages.Background()
        .Background(new PdfRgbColor(208, 227, 204));

    pages.Foreground()
        .Rotate(45)
        .Text(new string(' ', 30) + "Your watermark could go here, in the foreground");
}));

Für den Container Background stelle ich keinen Text oder ähnliches bereit. Ich gebe nur die Hintergrundfarbe an. Alles unterhalb der Kopfzeile, des Hauptinhalts und der Fußzeile wird diesen Grünton aufweisen.

Ich drehe den Inhalt im Container Foreground und füge etwas Text hinzu. Aufgrund der führenden Leerzeichen überdeckt der Text weder den Kopf- noch den Fußzeileninhalt. Der Inhalt aller Container ist auf der Seite sichtbar.

Sie können das Ergebnis des Codes in pages-all-slots.pdf sehen.

Einstellungen

Bisher konzentrierten sich alle Codefragmente auf Container, aus denen die Seiten bestehen. Es ist an der Zeit, zu prüfen, wie Sie die Seiten selbst und nicht ihre Inhaltsbereiche anpassen können.

Verwenden Sie zum Einrichten von Seiten Methoden der Klasse PageLayout. Denken Sie daran, dass ein PageLayout-Objekt mehr als eine Seite beschreiben kann. Methodenaufrufe wirken sich auf alle von Ihnen beschriebenen Seiten aus.

Größe

Die wahrscheinlich grundlegendste Einstellung ist die Seitengröße. Sie können die Methode Size verwenden, um eine der vordefinierten Größen für Ihre Seiten anzugeben. Es gibt alle gängigen Formate wie A4, Ledger oder Monarch Envelope.

Optional können Sie eine Ausrichtung für die Seiten angeben. Es ist möglich, eine benutzerdefinierte Seitengröße festzulegen, indem Sie die Breite und Höhe in Punkten angeben.

Ränder

Seitenränder können zur Lesbarkeit, Ästhetik und Gesamtkomposition Ihrer Seiten beitragen.

Stellen Sie alle Ränder mit der Methode Margin auf den gleichen Wert in Punkten ein. Verwenden Sie die Methoden MarginVertical und MarginHorizontal, um nur vertikale oder horizontale Ränder festzulegen. Verwenden Sie die Methoden MarginLeft/Top/Right/Bottom, um jeden Rand unabhängig anzugeben.

Textstil

Die Layout-API stellt die Klasse TextStyle zum Erstellen von Textstilen bereit. Sie erstellen Stile und wenden sie auf Text an, um das gewünschte Erscheinungsbild zu erzielen.

Es gibt Fälle, in denen ein großer Teil eines Textes auf Ihren Seiten denselben Stil verwendet. Sie können diesen Stil als Standardtextstil für die Seiten festlegen. Der Standardstil wirkt sich auf den gesamten Text in den Hauptinhaltsfeldern aus. Sie können den Standardstil jedoch für bestimmte Elemente überschreiben. Wenden Sie einfach einen anderen Stil auf Textteile an, die anders aussehen sollen.

PdfDocumentBuilder.Create().Generate("pages-text-styles.pdf", doc =>
{
    var defaultStyle = TextStyle.Parent.FontSize(30);
    var tightSpacing = TextStyle.Parent.LetterSpacing(-0.1);

    doc.Pages(pages =>
    {
        pages.TextStyle(defaultStyle);

        pages.Content().Text(t =>
        {
            t.Line("This line uses the default text style.");
            t.Line("This line uses a tight letter spacing.").Style(tightSpacing);
            t.Line("This line uses the default text style, again.");
        });
    });
});

Sie können das Ergebnis des Codes in pages-text-styles.pdf sehen.

Bitte beachten Sie, dass Sie mit der Methode Document.Typography dokumentweite Textstile einrichten können. Jede Eigenschaft in der Klasse Typography definiert einen Stil für einen Anwendungsfall. Diese Stile überschreiben den durch die Methode PageLayout.TextStyle angegebenen Stil. Beispielsweise überschreibt die Eigenschaft Typography.Body den Standardstil für Text in Content-Containern.

Inhaltliche Ausrichtung

Es gibt Sprachen, die von rechts nach links geschrieben werden. Die Layout-API verarbeitet Text in diesen Sprachen problemlos. Sie müssten jedoch die Textrichtung explizit angeben.

Wenn der Großteil des Textes auf Ihren Seiten in einer RTL-Sprache verfasst ist, können Sie die Richtung von rechts nach links als Standardinhaltsrichtung für die Seiten festlegen. Sie können für jeden Container auf Ihren Seiten eine andere Richtung angeben.

PdfDocumentBuilder.Create().Generate("pages-content-direction.pdf", doc =>
{
    var defaultTextStyle = doc.TextStyleWithFont(SystemFont.Family("Calibri"));

    doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6).TextStyle(defaultTextStyle);

        pages.ContentFromRightToLeft();

        pages.Content().Column(column =>
        {
            column.Item()
                .ContentFromLeftToRight()
                .Text("There are languages written from right to left.");

            column.Item()
                .Text("هناك لغات تكتب من اليمين إلى اليسار.");

            column.Item()
                .Text("יש שפות שנכתבות מימין לשמאל.");
        });
    });
});

Im obigen Code habe ich die Richtung von rechts nach links als Standardinhaltsrichtung festgelegt. Für den Container mit der englischen Version des Satzes ändere ich die Richtung auf links nach rechts. Sie können das Ergebnis des Codes in pages-content-direction.pdf sehen.

Seitenzahlen

Beim Generieren von PDF berechnet die Layout-API automatisch die aktuelle Seitenzahl. Außerdem wird die Gesamtzahl der Seiten im Dokument berechnet. Sie können die Zahlen erhalten, indem Sie die Methoden CurrentPageNumber und PageCount eines beliebigen Textcontainers aufrufen. Egal, ob sich der Container im Header, Footer oder im Hauptinhaltsslot befindet.

PdfDocumentBuilder.Create().Generate("pages-page-numbers.pdf", doc => doc.Pages(pages =>
{
    pages.Content().Text(t =>
    {
        t.Span("This line is on page ");
        t.CurrentPageNumber();
        t.Line();
        t.Line("Check the footer.");
    });

    pages.Footer().Row(r =>
    {
        r.AutoItem().Text("Created with Docotic.Pdf Layout API");

        r.RelativeItem(2).Text(t =>
        {
            t.AlignRight();

            t.Span("Page ");
            t.CurrentPageNumber();
            t.Span(" of ");
            t.PageCount();
        });
    });
}));

Das Ergebnis des Codes befindet sich in pages-page-numbers.pdf.

Beide Methoden geben TextPageNumber zurück, mit dem Sie die Zahlen formatieren können.

Das Beispiel Fügen Sie Kopf- und Fußzeilen zu PDF-Dokumenten hinzu zeigt, wie eine benutzerdefinierte Formatierung auf Seitenzahlen angewendet wird.

Beispielcode

Wir haben einige Beispiel-Apps, die die oben genannten Funktionen detaillierter abdecken. Bitte nehmen Sie sich etwas Zeit und schauen Sie sich diese an.

• Seitenlayout in PDF-Dokumenten
• Fügen Sie Kopf- und Fußzeilen zu PDF-Dokumenten hinzu
• Textstil