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

PDFページをレイアウトする方法

PdfDocumentBuilder.Generate メソッドは、Document タイプのオブジェクトをデリゲートに提供します。そのオブジェクトの Pages メソッドを使用してドキュメントページを作成します。 PageLayout タイプのパラメータを受け入れるデリゲートをメソッドに提供する必要があります。

PDFページのレイアウト

PDF ドキュメント内のすべてのページが同じレイアウトである場合は、メソッドを 1 回呼び出すだけで十分です。ドキュメント内に異なるレイアウトがある場合は、Pages メソッドを複数回呼び出してください。たとえば、メソッドを 1 回呼び出して表紙をレイアウトできます。次に、メソッドを再度呼び出してレポート本文を記述します。

Pages を呼び出すたびに、少なくとも 1 つのページが作成されます。コンテンツが提供されていない場合、作成されたページは空であってもかまいません。

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

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

コンテンツスロット

ページのレイアウトを記述するには、事前定義されたコンテナを使用します。私はそれらをコンテンツスロットとも呼びます。これらのコンテナにアクセスするには、PageLayout オブジェクトのメソッドを呼び出します。

メインスロットには、Content、Header、Footer の 3 つがあります。追加コンテンツ用の 2つのスロット: Background と Foreground。デフォルトでは、5 つのコンテナーはすべて空であり、ページ領域を占有しません。要件に応じてページコンテンツをスロット間で分散します。

コンテナを使用してページをレイアウトする方法については、コンテナとそのコンテンツの記事を参照してください。

ヘッダーとフッター

ヘッダーとフッターのコンテンツがそれぞれ 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 メソッドを使用して、ページに事前定義されたサイズの 1 つを指定できます。 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 ドキュメントにヘッダーとフッターを追加するの例は、ページ番号にカスタム書式設定を適用する方法を示しています。

サンプルコード

前述の機能をさらに詳細にカバーするサンプルアプリがいくつかあります。ぜひ時間をかけてチェックしてみてください。