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

Core API を使用した PDF の作成

Bit Miracleの正方形のロゴ
2026年6月29日に更新されました

Docotic.Pdf の Core API は、PDF 作成を完全に制御できます。PDF ページ、XObject、タイル パターンが提供するキャンバス上に、テキスト、画像、ベクター グラフィックスを描画できます。

座標と描画操作をすべて制御できるため、PDF ページのレイアウトを最大限に制御できます。精度が重要なグラフィックス重視またはカスタム レイアウトの文書では、このレベルの制御は不可欠です。

Core API を使うと、作成した PDF に注釈、フォーム フィールド、レイヤー、ブックマークなども追加できます。Docotic.Pdf が .NET で PDF を作成するために提供する、最も柔軟で強力な方法です。

PDF 作成における Core API の機能を示す図。ベクター グラフィックス、画像配置、テキスト描画を表示しています。

Docotic.Pdf で利用できるすべての方法を含め、Core API 以外の手段も含めてより広い概要を知りたい場合は、PDF を作成するすべての方法 を説明した記事を参照してください。

始める前に

Core API を使い始める前に、Docotic.Pdf をインストールし、ライセンス キーを要求して環境を整えてください。

Docotic.Pdf をインストールする

C# または VB.NET で PDF ドキュメントを作成するには、まず NuGet からライブラリをインストールします。

Install-Package BitMiracle.Docotic.Pdf

手動でライブラリをインストールする場合は、ライブラリ バイナリを含む ZIP アーカイブをダウンロードして展開し、プロジェクトから BitMiracle.Docotic.Pdf.dll への参照を追加します。

ライセンス キーを取得する

ライブラリを使用するにはライセンス キーが必要です。試用するには、Docotic.Pdf の ダウンロード ページ のフォームに入力して、無料の期間限定ライセンス キーを取得してください。

基本的な PDF 作成の例

このセクションでは、Core API を使用して PDF ドキュメントを作成する基本例を、まず C#、次に VB.NET で示します。

C# で PDF を作成する方法

Docotic.Pdf をインストールしてライセンス キーを取得したら、Core API を使って PDF を作成するのは簡単です。

BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

using var pdf = new PdfDocument();
pdf.Save("empty.pdf");

このコードは空の PDF ファイルを作成する方法を示しています。1 行目でライセンス キーを追加します。ライセンスがない場合、PdfDocument をインスタンス化する行で例外が発生します。最後の行は、ドキュメントを PDF ファイルとして保存します。

作成されたファイルの内部構造は保存オプションによって異なります。この例では、既定のオプションで保存する Save メソッドのオーバーロードを使用しています。これらの既定値が何を行うのか、またいつ調整したいかを理解するには、保存オプション のセクションを参照してください。

プログラミングの慣例に従い、2 番目の例では Core API で作成した Hello, world! を示します。

using var pdf = new PdfDocument();

var page = pdf.Pages[0];
page.Canvas.DrawString(50, 50, "Hello, world!");

pdf.Save("hello.pdf");

このコードは、ドキュメントの 1 ページ目のキャンバスに、明示的に指定した位置から古典的なフレーズを配置します。この行では既定のフォントと既定のフォント サイズを使用します。PDF キャンバスの操作については、引き続き説明を参照してください。

VB.NET を使用して PDF を作成する

PDF を作成する VB.NET のコードは、前のセクションのコードと非常によく似ています。

Using pdf As New PdfDocument()
    Dim page = pdf.Pages(0)
    page.Canvas.DrawString(50, 50, "Hello, world!")

    pdf.Save("hello.pdf")
End Using

前のセクションでは C# の例を含め、このコードが何を行い、どのように動作するかを説明しています。

PDF キャンバスの操作

PDF ドキュメントのキャンバスを変更するには、Canvas API を使用します。これは Core API のサブセットです。

Canvas API は絶対位置指定モデルを使用します。座標を選択すると、キャンバスは指示した場所に正確に描画します。座標系では、原点はページの左上隅に配置されます。X 軸は右方向、Y 軸は下方向に増加します。

(0,0) ──► X
  │
  │
  ▼
  Y

テキストの描画

PdfCanvas クラスでは、Docotic.Pdf はテキストをレンダリングするための 2 つの主要メソッド DrawString と DrawText を提供しています。どちらのメソッドも現在のキャンバス フォントを使用するため、テキストを描画する前に必要なフォントを設定することを推奨します。

DrawString の使用

DrawString は常に 1 行のテキストを描画します。明示的な座標を指定するオーバーロードを使わない限り、このメソッドはキャンバスの現在のテキスト位置から描画を開始します。一部のオーバーロードでは、テキスト行の描画方法を制御する追加オプションを指定できます。

Hello, world! のスニペットで DrawString の簡単な例はすでに見ました。ここでは、文字列描画オプション を使用してテキストに下線を引く別の例を示します。

using var pdf = new PdfDocument();

var canvas = pdf.Pages[0].Canvas;
canvas.DrawString(50, 50, "This text is underlined", new PdfStringDrawingOptions
{
    Underline = true,
});

pdf.Save("underlined-text.pdf");

DrawText の使用

DrawText は、指定した矩形内に複数行のテキストを描画できます。このメソッドは改行を処理し、許容スペースに収まらないテキストをクリップします。テキスト描画オプション は、テキストの水平・垂直配置や、テキストの位置決めとレンダリングに関するその他の側面を定義します。

C# で PDF にテキストを描画する方法は次のとおりです。

using var pdf = new PdfDocument();

const string LongString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit";
var multiLineOptions = new PdfTextDrawingOptions(new PdfRectangle(70, 70, 40, 150))
{
    HorizontalAlignment = PdfTextAlign.Left,
    VerticalAlignment = PdfVerticalAlign.Top
};

var canvas = pdf.Pages[0].Canvas;
canvas.DrawText(LongString, multiLineOptions);

pdf.Save("drawtext.pdf");

テキストの見た目を細かく調整するには、次のキャンバス プロパティを調整できます。

  • 文字間隔
  • 単語間隔
  • テキストの拡大率
  • テキスト上昇量（ベースライン シフト）
  • 描画モード（塗りつぶし、線描画、塗りつぶしと線描画、その他）

テキスト関連のメソッドとプロパティの実用例については、Text サンプル グループ を参照してください。

フォントの追加と使用

既定の Helvetica フォントで十分でない場合は、テキストが意図したとおりに表示されるように、必要なフォントを PDF に追加する必要があります。

Docotic.Pdf は、次の場所から Type1、TrueType、Compact Font Format (CFF)、OpenType フォントを追加できます。

  • システムにインストールされたフォントのコレクション
  • 外部ファイルとストリーム

さらに、任意の PDF ビューアーで利用できる 14 種類の組み込み Type1 フォント も使用できます。

PDF でフォントを使用するには、対応する PdfDocument オブジェクトの CreateFont または CreateFontFromFile メソッドを使って PdfFont オブジェクトを作成します。次に、テキストを描画する前にそのフォントをキャンバスに割り当てます。フォント サイズも設定しておくとよいでしょう。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var font = pdf.CreateFont("NSimSun");
canvas.Font = font;
canvas.FontSize = 14;
canvas.DrawString(10, 50, "Olá. 你好. Hello, Unicode!");

font.RemoveUnusedGlyphs();

pdf.Save("unicode-text.pdf");

フォントには、描画しようとしているテキスト内のすべての文字に対応するグリフが含まれていなければなりません。そうでない場合は、CannotShowTextException が発生します。PdfFont.ContainsGlyphsForText を使用して、フォントに必要なすべてのグリフが含まれていることを確認してください。

Unicode のサポートはフォントの種類に依存します。Type 1 フォントは、1 つの例外を除き、ラテン文字セットとエンコーディングのみをサポートします。組み込みの Symbol フォントと ZapfDingbats フォントは、数学記号、ギリシャ文字、装飾記号を提供します。

TrueType、CFF、OpenType フォントは通常 Unicode をサポートしますが、すべての Unicode 文字のグリフを含むとは限りません。

Docotic.Pdf は、出力 PDF を小さく保つために、埋め込むフォント バイト数をできるだけ少なくしようとします。ただし、ドキュメントが多数のグリフを含むフォントを使用する場合、生成されるファイルは比較的大きくなることがあります。PdfFont.RemoveUnusedGlyphs を使用すると、埋め込みフォントによって追加されるバイト数を最小限に抑えられます。

テキスト寸法の計算

Canvas API は絶対位置指定を使用するため、テキストの一部が描画前にどの程度のスペースを占めるかを把握する必要がよくあります。これは、長い文字列を分割して複数回に分けて出力する場合、テキストを正確に配置する場合、他のコンテンツとの重なりを避ける場合に特に重要です。PdfCanvas クラスには、現在選択されているフォントとフォント サイズを使用してテキストを測定するのに役立つ複数のメソッドがあります。

PdfCanvas.MeasureText を使用すると、文字列がキャンバス上に表示される場合の幅と高さの両方を取得できます。代表的な用途は次のとおりです。

  • テキストが指定領域に収まるかどうかを判断する
  • 手動で改行位置を計算する
  • テキスト ブロック同士の相対位置を決める

テキストを中央揃えまたは右揃えにし、横方向の幅だけが必要な場合は、PdfCanvas.GetTextWidth を使用します。現在のフォントで 1 行のテキストの高さを知るには、PdfCanvas.GetTextHeight を使用します。

画像の描画

PDF キャンバスに画像を描画するには、まず PdfImage オブジェクトを作成し、次に PdfCanvas.DrawImage メソッドを使ってそのオブジェクトを描画します。

C# で PDF に画像を追加する方法は次のとおりです。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var image = pdf.CreateImage("image.png");
canvas.DrawImage(image, 10, 50);

pdf.Save("image.pdf");

このコードは、対応する PdfDocument オブジェクトの CreateImage メソッドを使用して画像オブジェクトを作成し、1 ページ目のキャンバスに画像を描画します。

サポートされる画像形式や、より高度な画像から PDF への変換手法の詳細については、画像から PDF を作成する を参照してください。

ベクター グラフィックスの使用

Docotic.Pdf では、PdfCanvas クラスのメソッドを使用して、直線、ベジェ曲線、一般的な図形を PDF キャンバス上に直接描画できます。Draw で始まるメソッド（たとえば DrawLineTo、DrawCircle、DrawRectangle）を使用して、キャンバス上に表示されるマークを配置します。

線と曲線は、PdfCanvas.Pen を通じて定義される current pen によってレンダリングされます。これは、線色、幅、その他の描画プロパティを指定します。描画モードに応じて、図形は線描画、塗りつぶし、または線描画の後に塗りつぶしを行えます。PdfCanvas.Brush を通じてアクセスする current brush は、図形の内部を塗りつぶすために使用されます。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.DrawCircle(new PdfPoint(60, 100), 40);
canvas.DrawRectangle(
    new PdfRectangle(300, 60, 110, 70),
    PdfDrawMode.Fill);

canvas.CurrentPosition = new PdfPoint(150, 90);
canvas.DrawCurveTo(new PdfPoint(180, 60), new PdfPoint(230, 120), new PdfPoint(250, 90));

pdf.Save("curve-and-shapes.pdf");

各 PDF キャンバスは、ペン、ブラシ、フォント、現在位置を含むグラフィックス状態を保持しています。現在の状態を保持するには SaveState を使用し、以前の状態に戻すには RestoreState を使用します。一時的な変形や同様の変更を元に戻すだけでなく、クリッピングを適用した後に解除する唯一の方法は状態を復元することです。

グラフィックス パスを使うと、線、曲線、より単純な図形から、すぐには描画せずに複雑な図形を構築できます。AppendLineTo や AppendRectangle などの Append メソッドを使って、現在のパスにセグメントを追加します。パスは、明示的に塗りつぶしまたは線描画を行うまで、可視出力を生成しません。

構築したグラフィックス パスは、後続の描画操作を制限するクリッピング領域として使用できます。クリッピングは、グラフィックス状態が復元されるまで有効です。

ベクター グラフィックスを扱う実行可能な実用例は、サンプル リポジトリの Graphics セクション で利用できます。

色と透明度の設定

PDF キャンバスのペンとブラシを通じて、線色と塗りつぶし色を変更できます。これには PdfPen.Color と PdfBrush.Color を使用します。

色とりどりの滴る形状の図。一部は単色、一部はパターン付きで、色と透明度に関する Core API の機能を示しています。

サポートされるデバイス依存の色空間には Gray、RGB、CMYK があり、それぞれ PdfGrayColor、PdfRgbColor、PdfCmykColor で表されます。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.Pen.Color = new PdfRgbColor(30, 60, 160);
canvas.Pen.Width = 3;

canvas.Brush.Color = new PdfCmykColor(0, 20, 5, 0);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

pdf.Save("fill-and-stroke-colors.pdf");

Docotic.Pdf は、L*a*b* 色や ICC ベースのキャリブレーション色を含む、CIE ベースのデバイス非依存色空間をサポートしています。Core API は、カスタム インクやチャネル別出力が必要なワークフロー向けに、スポット カラーと分離色空間もサポートします。

以下のサンプル コードは、Lab 色、プロファイル ベースの色、スポット カラーの作成方法を示しています。例を実行するには、まず使用されている ICC プロファイル をダウンロードしてください。

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

var labColorSpace = new PdfLabColorSpace(pdf, [0.5, 1, 0.5]);
canvas.Pen.Color = new PdfLabColor(labColorSpace, 50, -50, 50);
canvas.Pen.Width = 3;

var rgbProfile = pdf.CreateColorProfile("AdobeCompat-v2.icc");
canvas.Brush.Color = new PdfRgbColor(rgbProfile, 210, 105, 30);

canvas.DrawRectangle(
    new PdfRectangle(50, 50, 100, 40),
    PdfDrawMode.FillAndStroke);

var tintTransform = new PdfExponentialFunction(
    pdf, 1, [0d, 0, 0, 0], [0, 0.8, 0.73, 0.25], [0d, 1]);
var separationColorSpace = new PdfSeparationColorSpace(
    pdf, "BLOODRED", new PdfCmykColorSpace(), tintTransform);
canvas.Pen.Color = new PdfSpotColor(1.0, separationColorSpace);

canvas.DrawCircle(new PdfPoint(100, 70), 60);

pdf.Save("using-special-colors.pdf");

タイル パターンを使って図形を線描画および塗りつぶしすることもできます。パターンは、独自のキャンバス上に描画されたパターン セルで定義されます。次の 2 種類があります。

  • Colored パターン。セル自体が色を定義します。
  • Uncolored パターン。セルは使用時にペン/ブラシの色で着色されます。

パターンを使用するには、対応する PdfDocument オブジェクトの CreateColoredPattern または CreateUncoloredPattern を使って作成します。次に、PdfPen.Pattern や PdfBrush.Pattern を通じてパターンを適用します。サンプル リポジトリの パターンの作成と使用 のサンプル コードを確認してください。

半透明の色を使うと、図形、テキスト、画像をさまざまな不透明度で描画できます。PdfPen.Opacity と PdfBrush.Opacity を使用して半透明の色を作成します。

さらに、blend modes によって、透明なコンテンツがその下にある内容とどのように相互作用するかを制御できます。キャンバスのブレンド モードを変更するには、PdfCanvas.BlendMode を使用します。

ページの追加とカスタマイズ

Docotic.Pdf は PdfDocument.Pages コレクションを公開しており、これを使ってドキュメント内のすべてのページを管理できます。PdfDocument クラスには、新しいページを追加するための主なメソッドとして AddPage と InsertPage があります。

AddPage() を使用すると、ドキュメントの末尾に新しいページを追加できます。任意の位置にページを挿入するには、InsertPage(index) を使用します。どちらのメソッドも、新しく作成された PdfPage インスタンスを返します。

新しいページの既定サイズは 595 x 842 ユーザー空間単位です。これは A4 用紙のサイズです。ほとんどの場合、PDF のユーザー空間単位は 1/72 インチです。別の言い方をすると、ページの解像度が 1 インチあたり 72 ピクセルのとき、1 ユーザー空間単位は 1 ピクセルに相当します。

ページの幅や高さを特定のユーザー空間単位数に設定することで、ページ サイズはいつでも変更できます。

using var pdf = new PdfDocument();
var page = pdf.Pages[0];

page.Width = 600;
page.Height = 800;

別の方法として、あらかじめ定義されたサイズのいずれかを使用することもできます。

page.Size = PdfPaperSize.Ledger;

ページの向きを縦から横に変更したり、ページを時計回りに 90°、180°、270° 回転させたりすることもできます。

page.Orientation = PdfPaperOrientation.Landscape;
page.Rotation = PdfRotation.Rotate180;

ページ幅、高さ、または定義済みサイズの設定に加えて、既存コンテンツのクロップまたはサイズ変更 と合わせてページ サイズを調整することも可能です。

XObject を使用したコンテンツの再利用

PDF XObject は、ベクター グラフィックス、画像、テキストを格納するコンテナーです。各 XObject は独自のキャンバスを持つため、通常の PDF ページと同じくらい複雑な XObject を作成できます。

XObject はベクター画像に似ています。同じオブジェクトを複数ページで再利用でき、コンテンツを再作成したりドキュメント サイズを肥大化させたりする必要がありません。このようなオブジェクトは、視覚的なアーティファクトを発生させずに拡大縮小や回転ができます。これらの特性により、XObject はロゴ、イラスト、背景、透かし、その他の繰り返し使われるグラフィックスに最適です。

XObject の作成と使用

XObject を作成するには、PdfDocument.CreateXObject メソッドを使用します。必要に応じて、オブジェクトの幅と高さを変更します。次に、通常のページ キャンバスと同じ方法で、テキスト、画像、グラフィックスでキャンバスを埋めます。

他のキャンバスに XObject を追加するには、C# または VB.NET のコードで PdfCanvas.DrawXObject メソッドを使用します。XObject は、ページと他の XObject の両方が提供するキャンバス上に描画できる点に注意してください。

次の C# コードは、イラストを含む XObject を作成し、そのイラストを 2 ページに描画します。

using var pdf = new PdfDocument();

var xobj = pdf.CreateXObject();

var options = new PdfTextDrawingOptions(new PdfRectangle(0, 0, 100, 50))
{
    HorizontalAlignment = PdfTextAlign.Center,
    VerticalAlignment = PdfVerticalAlign.Center,
};
xobj.Canvas.FontSize = 16;
xobj.Canvas.DrawText("Company Logo", options);
xobj.Canvas.DrawRectangle(options.Bounds);

var page1 = pdf.Pages[0];
page1.Canvas.DrawXObject(xobj, 100, 100);

var page2 = pdf.AddPage();
page2.Canvas.DrawXObject(xobj, 200, 200);

pdf.Save("using-xobjects.pdf");

XObject を使用したページ変換

XObject は、グラフィックスの単純な再利用を超えたシナリオも可能にします。よくある例は、既存の 2 つの PDF ページを 1 つのより大きなページにまとめることです。各元ページを XObject に変換すると、新しいキャンバス上でそれらを並べて描画でき、実質的に 2 ページ見開きの結合 を作成できます。この方法では、配置、間隔、拡大縮小を完全に制御できるため、比較レイアウト、書籍の見開き、複数ページのプレビューを簡単に作成できます。

同じ手法は、PDF ページのサイズ変更 が必要な場合にも適用できます。コンテンツを再描画または再構築する代わりに、元のページから XObject を作成し、新しいサイズに合わせて拡大縮小して描画できます。これにより、大きすぎるページを縮小したり、小さいページを拡大したり、サイズが混在するドキュメントを最小限の手間で正規化できます。

Core API の範囲と制約

Core API は、PDF 作成に対して正確で低レベルな制御を提供しますが、自動レイアウト機能は提供しません。組み込みの余白、ヘッダー、フッター、ページ区切りロジックはなく、すべてのコンテンツを手動で配置する必要があります。テキストの測定やページ間での分割は完全にコード側の責務であり、これが PDF 作成における最も手作業の多い方法です。

表、段落、ページ区切りのサポートを含む自動レイアウトは、より高レベルな Layout API で利用できます。

結論

Docotic.Pdf の core API は、PDF 作成を完全に制御できます。PDF ページ、XObject、タイル パターンが提供するキャンバス上に、テキスト、画像、ベクター グラフィックスを描画できます。

この API は、正確な低レベル制御を必要とするシナリオ向けに設計されています。各要素を明示的に配置し、テキスト測定とページ分割を自分で管理し、グラフィックス状態、色、透明度を直接操作します。

全体として、Core API は、精度と制御を最優先する場合に PDF を構築するための最も柔軟なツールです。

無料のライセンスキーでライブラリを試す