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

容器及其內容物

文檔是一組頁面。每個頁面本身都是一組內容片段。您可能已經知道，PageLayout 為主要內容和附加內容提供了容器。但如何處理這些容器呢？

頁面內容的容器

容器有助於組織頁面上的內容。您放在頁面上的所有內容都必須放入容器中。如果內容夠大，一個容器可以佔據多個頁面的空間。

您可以將一些文字或圖像放入容器中。為了對齊和定位，您可以將一個容器放入另一個容器中。有些容器可以為多個內容提供空間。

頁面上的容器由 LayoutContainer 類別的物件表示。使用此類來設定容器的大小、位置、內容和渲染過程。

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

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

容器如何運作

您首先獲得一個容器。例如，透過呼叫 PageLayout.Content 方法。此方法將傳回一個不佔用空間且沒有設定內容或屬性的容器。使用 LayoutContainer 類別的方法來設定容器。

要理解的非常重要的一點是，所有 LayoutContainer 方法都將內容放入容器中。當您向容器添加一些文字時，這是預期的。但是，當您設定縮排或寬度時，內容會變成什麼呢？

當您設定容器屬性時，庫會建立具有指定屬性的新容器。新容器成為原始容器的內容。該庫傳回嵌套容器作為該方法的結果。

嵌套容器的屬性會影響父容器，反之亦然。例如，嵌套容器的寬度會影響父容器的大小。父容器的預設文字樣式會影響巢狀容器中的文字。 Layout 附加元件使用容器的層次結構及其屬性來建立結果佈局。

以下程式碼的結果可能會讓您感到驚訝，但請花一些時間分析它。該程式碼說明了嵌套容器的工作原理。

PdfDocumentBuilder.Create().Generate("containers-how.pdf", doc => doc.Pages(page =>
{
    page.Size(150, 150);
    page.Content()
        .Background(new PdfRgbColor(235, 64, 52)) // red

        .PaddingTop(50)
        .Background(new PdfRgbColor(187, 237, 237)) // blue

        .PaddingRight(50)
        .Background(new PdfRgbColor(15, 130, 9)) // green

        .PaddingBottom(50)
        .Background(new PdfRgbColor(250, 123, 5)) // orange

        .PaddingLeft(50)
        .Background(new PdfRgbColor(204, 204, 204)); // gray
}));

裝飾

文件設計不僅涉及排列文字和圖像。正確設計的文件不僅能創造有效的溝通，還能產生視覺上吸引人的溝通。

使用 Layout API，您可以將背景顏色套用至任何容器。這有助於在內容中建立層次結構。您也可以透過套用邊框來定義邊界。使用垂直線和水平線來分隔內容元素。

PdfDocumentBuilder.Create().Generate("containers-decor.pdf", doc => doc.Pages(page =>
{
    page.Size(150, 150);
    page.Content()
        .Background(new PdfRgbColor(250, 123, 5))
        .Border(b =>
        {
            b.Color(new PdfGrayColor(0), 50);
            b.Thickness(15);
        })
        .PaddingTop(74)
        .LineHorizontal(2)
            .Color(new PdfCmykColor(73, 45, 0, 4))
            .DashPattern(new PdfDashPattern(new double[] { 8, 2 }));
}));

此 API 支援 Gray、RGB 和 CMYK 色彩空間中的不透明和半透明顏色。除了實線之外，Layout API 還支援使用虛線圖案的線條。

上述程式碼的結果在containers-decor.pdf。

內容

讓我們看看 LayoutContainer 類別提供了什麼來組織內容。

Text

若要將一些文字新增至容器中，請使用 Text7 方法之一。

如果所有文字都使用相同的樣式，請使用該方法的簡單速記版本。該版本接受一個字串並傳回一個 TextSpan 物件。您可以使用該物件來設定跨度的文字樣式。

還有另一個版本的 Text 方法接受 Action<TextContainer> 類型的委託。使用該版本可以在一個文字區塊中具有不同樣式的跨度。TextContainer 提供了在文字範圍之間插入圖像和其他元素的方法。還有其他高級功能，例如設定段落之間的距離的能力。

PdfDocumentBuilder.Create().Generate("containers-text.pdf", doc => doc.Pages(page =>
{
    page.Header().Text("This is a simple text span");

    page.Content().Text(t =>
    {
        t.Span("This line contains ");
        t.Span("some underlined text").Style(TextStyle.Parent.Underline());
    });
}));

您可以在 containers-text.pdf 中看到程式碼的結果。

Image

Layout API 提供了從檔案或流中的圖像資料建立 Image 物件的方法。任何 Image 物件都可以作為容器的內容。您可以在多個容器中使用相同的 Image 物件。有不同的內容模式會影響影像在容器內的外觀。

此函式庫只能載入光柵格式的圖片：PNG、JPEG、JPEG 2000、BMP、GIF 和 TIFF。

PdfDocumentBuilder.Create().Generate("containers-image.pdf", doc =>
{
    var imageFile = new FileInfo(@"path-to-image.jpg");
    var image = doc.Image(imageFile);

    doc.Pages(pages =>
    {
        pages.Size(image.Width, image.Height);
        pages.Content().Image(image, ImageContentMode.FitArea);
    });
});

Column

列為無數個連續垂直放置的項目提供空間。您可以在列中使用任何類型的項目。例如，列可以包含圖像和文字項目。每個項目的寬度等於列寬。每個項目的高度取決於項目的內容和屬性。

PdfDocumentBuilder.Create().Generate("containers-column.pdf", doc => doc.Pages(page =>
{
    page.Content().Column(c =>
    {
        for (int i = 0; i < 10; i++)
        {
            PdfColor color = i % 2 == 0
                ? new PdfRgbColor(187, 237, 237)
                : new PdfGrayColor(66);

            c.Item().Background(color).Height(10 + i * 3);
        }
    });
}));

您可以在 containers-column.pdf 中看到程式碼的結果。

Row

Row 容器有助於水平組織無限數量的項目。一行中的每個項目都是容器。因此，您可以將不同類型的內容放在一行中。

PdfDocumentBuilder.Create().Generate("containers-row.pdf", doc => doc.Pages(page =>
{
    var rowItems = new[] { "three", "two", "one" };

    page.Content().Row(row =>
    {
        for (int index = 0; index < rowItems.Length; index++)
        {
            row.AutoItem().Text(rowItems[index]);

            if (index != rowItems.Length - 1)
                row.AutoItem().PaddingHorizontal(10).LineVertical(0.5);
        }
    });
}));

您可以在 containers-row.pdf 中看到程式碼的結果。

Table

使用 Table 容器來佈局最複雜的資料。首先定義至少一列，然後透過多次呼叫 Cell 方法來填入列和行。

表格可以有頁首和頁尾。表中的儲存格可以跨越多列和/或多行。這是添加一個簡單表格的程式碼。

PdfDocumentBuilder.Create().Generate("containers-table.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.Cell()
                .Border(b => b.Thickness(0.5))
                .PaddingHorizontal(10)
                .Text($"{i + 1}");
        }
    });
}));

程式碼的結果在containers-table.pdf。

Inlined

Inlined 容器提供了一種用容器集合中的項目填滿區域的便捷方法。您只需一個接一個地添加項目，庫就會將它們一個接一個地排成一行。如果沒有空間放置項目，庫將開始一個新行。

Layers

在某些情況下，最好將內容放在多個圖層上。 Layers 容器正是用於此目的。您必須準確定義一個主要層和任意數量的非主要層。 Layout API 將依照您建立圖層的順序組成圖層。

Element

這是一種特殊的內容。您可以動態建立元素並將結果放入容器中。

動態建立的元素可以提供取決於頁碼、大小和其他屬性的佈局。