該頁面可以包含自動翻譯的文字。

如何佈局 PDF 頁面

PdfDocumentBuilder.Generate 方法向其委託提供 Document 類型的物件。使用該物件的 Pages 方法來建立文檔頁面。您必須向該方法提供一個接受 PageLayout 類型參數的委託。

佈置 PDF 頁面

如果 PDF 文件中的所有頁面都具有相同的佈局，則呼叫該方法一次就足夠了。如果文件中有不同的佈局，請多次呼叫 Pages 方法。例如，您可以呼叫該方法一次來佈局封面。然後再次呼叫該方法來描述報表主體。

每次呼叫 Pages 都會建立至少一個頁面。如果沒有為其提供內容，則建立的頁面可以為空。

本文是用於 PDF 產生的 Layout API 的系列文章的一部分。如果您是 API 新手，請先閱讀 Layout API 入門部分。

Docotic.Pdf 函式庫 9.5.17573-dev 佈局附加元件 9.5.17573-dev
回歸測試 14,726 已通過 NuGet 總下載量 4,765,230

內容插槽

若要描述頁面佈局，請使用預先定義的容器。我也稱它們為內容槽。您可以透過呼叫 PageLayout 物件的方法來存取這些容器。

共有三個主要插槽：Content、Header 和 Footer。還有兩個用於附加內容的插槽：Background 和 Foreground。預設情況下，所有五個容器都是空的，不佔用頁面空間。您可以根據需要在插槽之間指派頁面內容。

閱讀容器及其內容物文章以了解如何使用容器佈局頁面。

頁首和頁尾

您不會驚訝地知道頁首和頁尾內容分別進入 Header 和 Footer 插槽。 API 在每個產生的頁面上的主要內容上方和下方重複這些插槽。 Layout API 永遠不會在頁面之間拆分頁首或頁尾內容。如果頁首或頁尾不適合頁面，您將收到 LayoutException。

主要內容

主頁內容（如圖像、表格和文字）進入 Content 槽。 Layout API 會自動將該內容拆分為頁面。

以下程式碼將簡單文字內容指派給所有主要內容槽。該代碼還設定了插槽的背景顏色。

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

檢查 pages-main-slots.pdf 中的程式碼結果。

正如您所看到的，每個插槽僅佔據頁面的一部分。確切的區域取決於插槽內的內容。 Header 插槽黏在頁面頂部。 Content 插槽在 Header 之後立即開始。 Footer 插槽黏在底部。

附加內容

Background 和 Foreground 提供可用於浮水印、疊加層和背景的容器。 Background 槽中的所有內容都位於頁首、頁尾和頁面主要內容的下方。 Foreground 槽中的內容涵蓋了新增到頁面的所有內容。

這些容器佔據了整個頁面。這是這些容器的獨特之處。 API 在每個產生的頁面上重複其內容。與頁首和頁尾容器完全相同。

我在上面的程式碼中添加了一些行來展示如何使用 Foreground 和 Background 容器。

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

對於 Background 容器，我不提供任何文字或其他內容。我只指定背景顏色。頁首、主要內容和頁腳下方的所有內容都會顯示綠色陰影。

我旋轉 Foreground 容器中的內容並向其中添加一些文字。由於前導空格，文字不會覆蓋頁首或頁尾內容。所有容器中的內容在頁面上都可見。

您可以在 pages-all-slots.pdf 查看程式碼的結果。

設定

到目前為止，所有程式碼片段都集中在構成頁面的容器上。現在是時候考慮如何自訂頁面本身，而不是其內容槽。

若要設定頁面，請使用 PageLayout 類別的方法。請記住，一個 PageLayout 物件可以描述多個頁面。方法呼叫將影響您描述的所有頁面。

尺寸

最基本的設定可能是頁面大小。您可以使用 Size 方法來指定頁面的預定義尺寸之一。有所有常見尺寸，如 A4、Ledger 或 Monarch 信封。

您也可以選擇指定頁面的方向。可以透過提供以磅為單位的寬度和高度來設定自訂頁面大小。

邊距

頁邊距可能有助於提高頁面的可讀性、美觀性和整體構圖。

使用 Margin 方法將所有邊距設定為相同的點值。使用 MarginVertical 和 MarginHorizontal 方法僅設定垂直或水平邊距。使用 MarginLeft/Top/Right/Bottom 方法獨立指定每個邊距。

文字樣式

Layout API 提供了 TextStyle 類別來建立文字樣式。您可以建立樣式並將其套用到文字以實現所需的外觀。

在某些情況下，頁面上的大部分文字都使用相同的樣式。您可以將該樣式設定為頁面的預設文字樣式。預設樣式會影響主要內容槽中的所有文字。但您可以覆蓋某些元素的預設樣式。只需對看起來不同的文字套用另一種樣式即可。

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

您可以在 pages-text-styles.pdf 查看程式碼的結果。

請注意，您可以使用 Document.Typography 方法設定文件範圍的文字樣式。 Typography 類別中的每個屬性都定義用例的樣式。這些樣式會覆寫 PageLayout.TextStyle 方法指定的樣式。例如，Typography.Body 屬性會覆蓋 Content 容器中文字的預設樣式。

內容方向

有些語言是從右向左寫的。 Layout API 可以很好地處理這些語言的文字。但您需要明確指定文字方向。

如果頁面上的大部分文字都是 RTL 語言，則可以將從右到左設定為頁面的預設內容方向。您將能夠為頁面中的任何容器指定不同的方向。

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("יש שפות שנכתבות מימין לשמאל.");
        });
    });
});

在上面的程式碼中，我將從右到左設定為預設內容方向。對於包含英文版本短語的容器，我將方向變更為從左到右。您可以在 pages-content-direction.pdf 中查看程式碼的結果。

頁碼

產生 PDF 時，Layout API 會自動計算目前頁碼。它還計算文檔中的總頁數。您可以透過呼叫任何文字容器的 CurrentPageNumber 和 PageCount 方法來取得數字。無論容器位於頁首、頁尾或主要內容槽中。

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

程式碼的結果在 pages-page-numbers.pdf。

這兩種方法都會傳回 TextPageNumber，您可以使用它來格式化數字。

在 PDF 文件中新增頁首和頁尾範例示範如何將自訂格式套用至頁碼。

範例程式碼

我們有一些範例應用程序，更詳細地涵蓋了上述功能。請花一些時間檢查一下。