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

如何佈局 PDF 頁面

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

佈置 PDF 頁面

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

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

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

Docotic.Pdf 函式庫 9.3.17105-dev 佈局附加元件 9.3.17105-dev
回歸測試 14,681 已通過 NuGet 總下載量 4,234,061

內容插槽

若要描述頁面佈局，請使用預先定義的容器。我也稱它們為內容槽。您可以透過呼叫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 方法指定的樣式。例如，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 文件中新增頁首和頁尾範例示範如何將自訂格式套用至頁碼。

範例程式碼

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