このページには自動翻訳されたテキストを含めることができます。

複合コンテナ

複雑なコンテナは、コンテンツの構造化と整理に重要な役割を果たします。適切なコンテナを使用することで、テキストや画像をユーザーフレンドリーな方法で簡単に表示できます。

単純なテキストコンテナーと画像コンテナーのみを使用してドキュメントを作成することは確かに可能です。ただし、単純なコンテナーのみでは実装が困難または不可能な要件があります。複合コンテナーはそのような場合に役立ちます。また、複雑なコンテナーは、少ないコードで目的を達成するのに役立ちます。

複合コンテナ

LayoutContainer クラスのメソッドを使用して、Row や Column などの複雑なコンテナーをドキュメントページに追加します。これらのコンテナーを使用して、グリッドやリストなどの他のコンテナーを実装できます。あまり一般的ではないが、それでも重要なケースのために、Inlined メソッドと Layers メソッドもあります。

この記事は、PDF 生成のための Layout API に関するシリーズの一部です。 API を初めて使用する場合は、まず Layout API の使用開始の部分をお読みください。

Docotic.Pdf ライブラリ 9.5.17548-dev レイアウトアドオン 9.5.17548-dev
回帰テスト 14,726人が合格 NuGet の合計ダウンロード数 4,514,921

Row

Row コンテナは、1 行に水平に並べられたアイテムを配置するスペースを提供します。行内の各アイテムはコンテナです。つまり、異なるタイプのコンテンツを 1 行に配置できます。Spacing メソッドを使用して、アイテム間の間隔を指定できます。

行内のすべてのアイテムの高さは同じです。ライブラリは、最も高いアイテムの高さを行の高さとして使用します。アイテムの幅を指定する方法は 3 つあります。アイテムを作成するときに、そのうちの 1 つを選択する必要があります。行には、さまざまな方法で作成されたアイテムを含めることができます。

Row.AutoItem メソッドは、幅が明示的に指定されていないアイテムを作成します。このようなアイテムの場合、ライブラリはコンテンツの固有のサイズを計算します。計算されたコンテンツの幅がアイテムの幅になります。AutoItem で作成されたアイテムは長い行を折り返さないことに注意してください。

正確なポイント数に等しい幅を持つアイテムを作成するには、ConstantItem メソッドを使用します。

RelativeItem は、行内のアイテムの正確な幅がわからず、固有のサイズを使用したくない場合に便利です。代わりに、行内のアイテムの相対的な幅を指定できます。このメソッドは、アイテムが占める部分の数を受け入れます。部分の合計数は、この行のすべての RelativeItem 呼び出しのすべての数値の合計です。

たとえば、RelativeItem 呼び出しが 1 つある場合、数は重要ではありません。アイテムは使用可能な幅全体を占めます。アイテムが 2 つ以上ある場合、数によって比率が定義されます。

row.RelativeItem(2)
row.RelativeItem(3)
row.RelativeItem(1)

上記のコードで作成されたすべてのアイテムは、6 つの部分 (2 + 3 + 1 = 6) を占めます。個々のアイテムは、それぞれ 6 つのうち 2 つ、6 つのうち 3 つ、6 つのうち 1 つの部分を占めます。

Layout API は、次の式を使用して 1 つのパーツの幅を計算します。

PartWidth = (RowWidth - AutoWidth - ConstantWidth) / TotalParts

ここで:
RowWidth = 行コンテナの幅
AutoWidth = AutoItem メソッドで作成されたすべての項目の幅
ConstantWidth = ConstantItem メソッドで作成されたすべての項目の幅

以下は、3 種類すべての項目を含む行を作成する例です。

var monthNames = DateTimeFormatInfo.InvariantInfo.MonthNames;
var groups = new[]
{
    string.Join(", ", monthNames.Take(4)),
    string.Join(", ", monthNames.Skip(4).Take(4)),
    string.Join(", ", monthNames.Skip(8).Take(4)),
};

PdfDocumentBuilder.Create().Generate("compounds-row.pdf", doc => doc.Pages(page =>
{
    page.Content()
        .Padding(20)
        .MinimalBox()
        .Row(row =>
        {
            row.ConstantItem(100)
                .Background(new PdfRgbColor(187, 237, 237))
                .Text("100 points wide");

            for (int i = 0; i < groups.Length; i++)
            {
                row.AutoItem().LineVertical(0.1);

                var numberOfParts = groups.Length - i + 1;
                row.RelativeItem(numberOfParts)
                    .PaddingHorizontal(5)
                    .Text(t =>
                    {
                        t.Line($"{numberOfParts} parts wide");
                        t.Line();
                        t.Line(groups[i]);
                    });
            }
        });
}));

コードの結果は compounds-row.pdf で確認できます。

Column

アイテムを縦に並べるには、Column コンテナを使用します。列内の各アイテムはコンテナです。このため、1 つの列に異なるタイプのコンテンツを配置できます。

各項目の幅は列の幅と同じです。各項目の高さは、項目のコンテンツとプロパティによって異なります。Column コンテナーはページングをサポートしているため、Layout アドオンは列の項目を複数のページにレンダリングできます。

デフォルトでは、Column コンテナーにはヘッダーまたはフッターのコンテンツがありません。対応するコンテナーにアクセスして設定するには、Header メソッドと Footer メソッドを使用します。列項目が複数のページにわたる場合、ライブラリは各ページでヘッダーとフッターの両方を繰り返します。

列項目間に垂直方向のスペースを追加するには、Spacing メソッドを使用します。ライブラリはヘッダーと最初の項目の間にスペースを適用しないことに注意してください。また、ライブラリはフッターの前にスペースを追加しません。

PdfDocumentBuilder.Create().Generate("compounds-column.pdf", doc => doc.Pages(page =>
{
    page.Size(PdfPaperSize.A6);

    page.Content()
        .Padding(20)
        .Column(column =>
        {
            column.Header()
                .Background(new PdfRgbColor(187, 237, 237))
                .Padding(5)
                .Text("Month names");

            for (int i = 0; i < 12; i++)
            {
                column.Item().Background(
                    new PdfGrayColor(i % 2 == 0 ? 90 : 100))
                    .Padding(5)
                    .Text(DateTimeFormatInfo.InvariantInfo.MonthNames[i]);
            }

            column.Footer().LineHorizontal(1);
        });
}));

コードの結果は compounds-column.pdf で確認できます。

グリッド

グリッドレイアウトは、アイテムを列と行に整理します。この点では、グリッドはテーブルに似ています。Layout API は、グリッド用の特別なコンテナータイプを提供しません。Column コンテナーと Row コンテナーを使用して、グリッドレイアウトを実装できます。

グリッドを列、その各項目を行と考えると分かりやすいでしょう。Column コンテナと Row コンテナの両方で、項目間の間隔を設定できます。必要に応じて、ヘッダーとフッターを追加できます。

各行は独立したレイアウトを持つことができます。各行には異なる数のアイテムを含めることができます。アイテムの幅と高さはそれぞれ異なっています。行内のアイテムの前、後、または間に余分なスペースを追加することができます。これには、コンテンツや装飾のないアイテムを使用します。

var blue = new PdfRgbColor(187, 237, 237);
var darkerBlue = blue.Darken(50);
PdfDocumentBuilder.Create().Generate("compounds-grid.pdf", doc => doc.Pages(page =>
{
    page.Size(300, 200);

    page.Content().Padding(15).Column(column =>
    {
        column.Spacing(10);

        column.Item().Row(row =>
        {
            row.Spacing(10);

            row.ConstantItem(100).Background(darkerBlue).Height(40);
            row.RelativeItem(4).Background(blue);
        });

        column.Item().Row(row =>
        {
            row.Spacing(10);

            row.RelativeItem(2).Background(blue).Height(60);
            row.RelativeItem(1);
            row.RelativeItem(2).Background(blue);
        });

        column.Item().Row(row =>
        {
            row.Spacing(10);

            row.RelativeItem(1).Background(blue).Height(50);
            row.RelativeItem(3).Background(blue);
            row.ConstantItem(50).Background(darkerBlue);
        });
    });
}));

コードの結果は compounds-grid.pdf で確認できます。

リストは、情報を簡潔なポイントに分割することで読みやすさを向上させます。リスト項目には、テキストの横に数字、箇条書き、その他の記号を表示できます。Column および Row コンテナーを使用して、リストレイアウトを簡単に実装できます。Layout API は、リスト用の特別なコンテナータイプを提供していません。

季節ごとに月のリストを作成するサンプルコードを確認してください。リストにはヘッダーがあることに注意してください。項目に次の行に折り返される可能性のあるテキストが含まれている場合は、項目のテキスト部分に RelativeItem メソッドまたは ConstantItemメソッドのいずれかを使用します。

var monthNames = DateTimeFormatInfo.InvariantInfo.MonthNames.ToList();
monthNames.Insert(0, monthNames[11]);

PdfDocumentBuilder.Create().Generate("compounds-list.pdf", doc => doc.Pages(page =>
{
    page.Size(150, 200);

    page.Content().Padding(5).Column(column =>
    {
        column.Header()
            .Text("Months by seasons:")
            .Style(TextStyle.Parent.Underline());

        for (int i = 0; i < 4; i++)
        {
            var season = string.Join(", ", monthNames.Skip(i * 3).Take(3));
            column.Item().Row(row =>
            {
                row.Spacing(2);

                row.AutoItem().Text("•");
                row.RelativeItem().Text(season);
            });
        }
    });
}));

コードの結果は compounds-list.pdf で確認できます。

Table

テーブルレイアウトは、アイテムを列と行に整理します。Table コンテナータイプは、広範な機能セットを提供し、最も複雑なケースでも役立ちます。Table コンテナの記事ですべての機能についてお読みください。

InlineContainer

コンテナーに他のコンテナーのコレクションを追加できます。まず、LayoutContainer.Inlined メソッドを呼び出します。次に、提供されている InlineContainer の Item メソッドを呼び出して、子コンテナーを追加します。

Layout アドオンは、コンテナーを次々に一列に配置します。アイテムを配置するスペースがない場合、ライブラリは新しい行を開始します。アイテム間にスペースを追加するには、Spacing/HorizontalSpacing/VerticalSpacing メソッドを使用します。

配置メソッドを使用して、コンテナー内のアイテムの位置に影響を与えることができます。 AlignTop/AlignMiddle/AlignBottom メソッドは、アイテムを垂直方向に配置します。水平方向には、AlignLeft/AlignCenter/AlignRight/AlignJustify メソッドを使用します。

特別なケースがあります。アイテムを水平に揃える AlignSpaceAround メソッドです。また、最初のアイテムの前と最後のアイテムの後に余分なスペースを追加します。

var orange = new PdfRgbColor(250, 123, 5);
var brown = orange.Darken(50);
var itemProps = new (int Width, PdfColor Color)[] {
    (20, orange), (30, orange), (50, brown), (50, orange), (50, orange),
    (30, orange), (20, brown), (30, orange), (50, brown), (10, brown)
};

PdfDocumentBuilder.Create().Generate("compounds-inlined.pdf", doc => doc.Pages(page =>
{
    page.Size(150, 120);

    page.Content().Inlined(c =>
    {
        c.Spacing(5);

        foreach (var (Width, Color) in itemProps)
            c.Item().Height(30).Width(Width).Background(Color);
    });
}));

コードの結果は compounds-inlined.pdf で確認できます。

LayerContainer

メインページコンテンツの下または上にコンテンツを配置する必要がある場合があります。明らかな使用例は、PDF ページの上に透かしを追加することです。

まず、LayoutContainer.Layers メソッドを呼び出して LayerContainer オブジェクトを取得します。オブジェクトを取得したら、レイヤーの追加を開始できます。Layer メソッドを呼び出すと、セカンダリレイヤーが追加されます。メインコンテンツレイヤーを追加するには、PrimaryLayer メソッドを呼び出します。プライマリレイヤーは 1 つだけ追加する必要があります。

Layout API は、レイヤーを作成した順序でレイヤーを構成します。プライマリレイヤーの前に追加されたレイヤーは背景になります。プライマリレイヤーの後に追加されたすべてのレイヤーは、メインコンテンツの上になります。コンテナーは、メインコンテンツが占めるすべてのページでセカンダリレイヤーを繰り返します。

PDF ページに透かしを追加する方法のサンプルコードを示します。

PdfDocumentBuilder.Create().Generate("compounds-layers.pdf", doc => doc.Pages(page =>
{
    var largeRedText = TextStyle.Parent.FontSize(48)
        .FontColor(new PdfRgbColor(235, 64, 52));

    page.Size(400, 250);

    page.Content()
        .Padding(25)
        .Layers(layers =>
        {
            layers.Layer()
                .AlignCenter()
                .Text(text => text.CurrentPageNumber().Style(largeRedText));

            layers.PrimaryLayer()
                .Background(new PdfGrayColor(85), 65)
                .Padding(25)
                .Text(new string('_', 790));

            layers.Layer()
                .AlignCenter()
                .AlignMiddle()
                .Text("Watermark")
                .Style(largeRedText);
        });
}));

コードの結果は compounds-layers.pdf で確認できます。

透かし

一般的な要件の 1 つは、PDF に透かしを追加することです。この要件はさまざまな理由で発生します。PDF に透かしを追加して、所有権を識別したり、PDF 内の情報の機密性や機密性を指摘したりできます。

PDF に透かしを入れる 1 つの方法は、レイヤーを使用することです。前のセクションの例を参照してください。別の方法を紹介します。

ページの背景と前景のコンテナを使用して PDF に透かしを入れます。Layout アドオンは、これらのコンテナを次のページで繰り返します。主要なドキュメントコンテンツを含むすべてのページにも、背景と前景のコンテナが含まれます。これにより、これらのコンテナがこのタスクに適しています。

まず、背景コンテナーに画像を追加します。同じ方法で PDF にロゴを追加できます。画像はページコンテンツの背後に表示されます。ドキュメントの何ページで背景画像が使用されるかは関係ありません。APIは、生成された PDF に画像バイトのコピーを 1 つだけ追加します。

主要なドキュメントコンテンツは何でも構いません。このサンプルコードでは、有名な Lorem Ipsum テキストを使用します。

テキストの透かしはフォアグラウンドコンテナーに入ります。テキスト自体は何でもよく、任意の色やフォントを使用できます。私は、大きなサイズの半透明の赤い文字で描かれた回転したテキストを使用しました。

サンプルコードは、サンプルコードのリポジトリから画像とテキストの両方を非同期的にダウンロードします。もちろん、ローカル画像を使用したり、ファイルからテキストを読み取ったりすることもできます。

var urlPrefix =
    "https://raw.githubusercontent.com/BitMiracle/Docotic.Pdf.Samples/master/Samples/Sample%20Data/";

using var client = new HttpClient();
using var imageResponse = await client.GetAsync(urlPrefix + "watermark-background.png");
using var imageStream = await imageResponse.Content.ReadAsStreamAsync().ConfigureAwait(false);

var loremIpsum = string.Empty;
using (var textResponse = await client.GetAsync(urlPrefix + "lorem-ipsum.txt"))
     loremIpsum = await textResponse.Content.ReadAsStringAsync().ConfigureAwait(false);

PdfDocumentBuilder.Create().Generate("compounds-watermarks.pdf", doc =>
{
    var image = doc.Image(imageStream);

    doc.Pages(page =>
    {
        page.Size(400, 250);

        page.Background()
            .AlignMiddle()
            .Image(image);

        page.Content()
            .Padding(25)
            .Text(loremIpsum);

        var largeRedText = TextStyle.Parent.FontSize(48)
            .FontColor(new PdfRgbColor(235, 64, 52), 50);
        page.Foreground()
            .Rotate(-30)
            .Translate(-50, 180)
            .Text("DO NOT COPY")
            .Style(largeRedText);
    });
});

コードの結果は compounds-watermarks.pdf で確認できます。

サンプルコード

上記の機能についてさらに詳しく説明したサンプルアプリがいくつかあります。ぜひご確認ください。

複合コンテナ

Row

Column

グリッド

リスト

Table

InlineContainer

LayerContainer

透かし

サンプル コード

サンプルコード