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

如何排版 PDF 頁面

由 Bit Miracle 翻譯。原文作者：Sergey Bobrovsky

更新於 2026年7月3日

PdfDocumentBuilder.Generate 方法會將 Document 類型的物件提供給其委派。使用該物件的 Pages 方法來建構文件頁面。你必須提供一個接受 PageLayout 類型參數的委派給該方法。

排版 PDF 頁面

如果 PDF 文件中的所有頁面都具有相同版面，只要呼叫一次該方法即可。若文件中有不同版面，則可多次呼叫 Pages 方法。比如，你可以先呼叫一次該方法來排版封面頁，然後再次呼叫以描述報告主體。

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

本文是關於用於 PDF 產生的 Layout API 系列之一。如果你是首次接觸此 API，請先閱讀 Layout API 入門部分。

內容槽

若要描述頁面版面，請使用預先定義的容器。我也稱它們為內容槽。你可以透過呼叫 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 Envelope 都有提供。

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

頁邊距

頁邊距有助於提升可讀性、美感與頁面的整體構圖。

使用 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 文件中新增頁首和頁尾範例示範如何對頁碼套用自訂格式。

範例程式碼

我們有一些範例應用程式，可更詳細涵蓋前述功能。請花點時間查看。