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

容器及其內容物

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

頁面內容的容器

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

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

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

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

Docotic.Pdf 函式庫 9.4.17467-dev 佈局附加元件 9.4.17467-dev
回歸測試 14,760 已通過 NuGet 總下載量 4,415,970

容器如何運作

您首先獲得一個容器。 例如,透過呼叫 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 支援 GrayRGBCMYK 色彩空間中的不透明和半透明顏色。除了實線之外,佈局 API還支援使用 虛線圖案 的線條。

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

內容

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

Text

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

如果所有文字都使用相同的樣式,請使用該方法的簡單速記版本。 該版本接受一個字串並傳回一個 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 中看到程式碼的結 果。

有關 Column 容器功能的詳細信息,請閱讀 複合容器 文章。

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 中看到程式碼的結果。

複合容器 文章包含有關 Row 容器的詳細資訊。

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

請閱讀 Table 容器 文章中了解所有Table容器功能。

Inlined

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

有關InlineContainer容器的更多資訊位於 複合容器 文章中。

Layers

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

有關 LayerContainer 類型的更多詳細信息,請閱讀 複合容器

Element

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

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