このページには自動翻訳されたテキストを含めることができます。
コンテナーとその内容
文書はページの集合です。各ページもまた、コンテンツ要素の集合です。すでにご存じかもしれませんが、PageLayout クラスは、メインコンテンツと追加コンテンツ用のコンテナーを提供します。では、これらのコンテナーをどう使えばよいのでしょうか?
コンテナーは、ページ上のコンテンツを整理するのに役立ちます。ページに配置するものはすべて、コンテナーに入れる必要があります。コンテンツが十分に大きい場合、1つのコンテナーが複数ページにわたって領域を占有できます。
コンテナーには、テキストや画像を入れられます。配置や位置決めの目的で、コンテナーを別のコンテナーの中に入れられます。1つ以上のコンテンツ要素を収容できるコンテナーもあります。
ページ上のコンテナーは、LayoutContainer クラスのオブジェクトとして表されます。このクラスを使って、コンテナーのサイズ、位置、コンテンツ、およびレンダリング処理を設定します。
この記事は、PDF 生成のための Layout API シリーズの一部です。API を初めて使う場合は、まず Layout API 入門 の部分をお読みください。
コンテナーの仕組み
まずコンテナーを取得します。たとえば、PageLayout.Content メソッドを呼び出します。このメソッドは、スペースを占有せず、コンテンツやプロパティが設定されていないコンテナーを返します。コンテナーの設定には、LayoutContainer クラスのメソッドを使います。
理解しておくべき非常に重要な点は、LayoutContainer のすべてのメソッドがコンテナー内にコンテンツを追加することです。コンテナーにテキストを追加するのは想定どおりですが、インデントや幅を設定した場合、何がコンテンツになるのでしょうか?
コンテナーのプロパティを設定すると、ライブラリは指定したプロパティを持つ新しいコンテナーを作成します。新しいコンテナーが元のコンテナーのコンテンツになります。メソッドの結果として、ライブラリは入れ子のコンテナーを返します。
入れ子のコンテナーのプロパティは親コンテナーに影響し、その逆も同様です。たとえば、入れ子のコンテナーの幅は親コンテナーのサイズに影響します。親コンテナーの既定のテキストスタイルは、入れ子のコンテナー内のテキストに影響します。Layout API のアドオンは、コンテナーの階層とそのプロパティを使って、最終的なレイアウトを構築します。
以下のコードの結果は驚くかもしれませんが、少し時間を取って分析してみてください。コードは、入れ子のコンテナーがどのように動作するかを示しています。
PdfDocumentBuilder.Create().Generate("containers-how.pdf", doc => doc.Pages(page =>
{
page.Size(150, 150);
page.Content()
.Background(new PdfRgbColor(235, 64, 52)) // 赤
.PaddingTop(50)
.Background(new PdfRgbColor(187, 237, 237)) // 青
.PaddingRight(50)
.Background(new PdfRgbColor(15, 130, 9)) // 緑
.PaddingBottom(50)
.Background(new PdfRgbColor(250, 123, 5)) // オレンジ
.PaddingLeft(50)
.Background(new PdfRgbColor(204, 204, 204)); // グレー
}));
装飾
文書デザインは、テキストと画像を配置するだけではありません。適切に設計された文書は、効果的であるだけでなく、視覚的にも魅力的なコミュニケーションを生み出します。
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 は dash patterns を使用する線もサポートします。
上記コードの結果は containers-decor.pdf にあります。
コンテンツ
コンテンツを整理するために LayoutContainer クラスが提供する機能を見てみましょう。
Text
コンテナーにテキストを追加するには、Text メソッドのいずれかを使います。
すべてのテキストが同じスタイルを使う場合は、簡易版のメソッドを使います。この版は文字列を受け取り、TextSpan オブジェクトを返します。このオブジェクトを使って、そのスパンのテキストスタイルを設定できます。
Text メソッドには、Action<TextContainer> 型のデリゲートを受け取る別の版もあります。その版を使うと、1つのテキストブロック内に異なるスタイルのスパンを含められます。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 コンテナーは、項目を水平方向に無制限に整理するのに役立ちます。行内の各項目はコンテナーです。そのため、行には異なる種類のコンテンツを配置できます。
var rowItems = new[] { "three", "two", "one" };
PdfDocumentBuilder.Create().Generate("containers-row.pdf", doc => doc.Pages(page =>
{
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 コンテナーを使います。まず少なくとも1列を定義し、次に Cell メソッドを複数回呼び出して列と行を埋めます。
テーブルにはヘッダーとフッターを持たせられます。テーブルのセルは、1列または1行を超えてまたがることができます。以下は、簡単なテーブルを追加するコードです。
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 コンテナーのすべての機能については、テーブル コンテナー 記事を参照してください。
Inlined
InlineContainer コンテナー型は、コンテナーのコレクションから項目で領域を埋める便利な方法を提供します。項目を順に追加するだけで、ライブラリがそれらを横一列に並べます。項目を配置するスペースがなくなると、新しい行を開始します。
InlineContainer コンテナーの詳細は、複合コンテナー 記事にあります。
Layers
コンテンツを複数のレイヤーに配置するのが最適な場合があります。LayerContainer コンテナー型は、まさにこの目的のためにあります。必ず1つだけプライマリレイヤーを定義し、非プライマリレイヤーは任意の数を定義できます。Layout API は、作成した順序でレイヤーを合成します。
LayerContainer 型の詳細については、複合コンテナー を参照してください。
Element
これは特別な種類のコンテンツです。要素を動的に作成し、その結果をコンテナーに入れられます。
動的に作成された要素は、ページ番号、サイズ、その他のプロパティに依存するレイアウトを提供できます。