DioDocs for PDF は、C# で記述された .NET Standard 2.0 クラスライブラリのコレクションで、PDF ファイルのゼロからの作成および既存のドキュメントのロード、分析、変更を可能にする API を提供します。
DioDocs for PDF は、.NET Core、ASP.NET Core、.NET Framework など、.NET Standard がサポートするすべてのプラットフォームで動作します。
DioDocs for PDF およびサポートパッケージは、NuGet.org から入手できます。
アプリケーションで DioDocs for PDF を使用するには、DioDocs.Pdf.ja パッケージを参照します。これにより、必要なインフラストラクチャパッケージがダウンロードされます。
バーコードをレンダリングするには、DioDocs.Barcode.ja パッケージ（略して DsBarcode）をインストールします。これにより、DioDocs for PDF の使用時にバーコードの描画を可能にする拡張メソッドが提供されます。
Windows システムでは、オプションで DioDocs.Imaging.Windows.ja をインストールできます。これは、Windows レジストリで指定されたフォントのリンクなどをサポートします。このライブラリは、Windows 以外のシステムでも参照できますが、何も行いません。
DioDocs.Imaging.ja は、ラスターイメージの作成、読み込み、および保存を可能にするパッケージで、他のパッケージによって自動的に追加されるものです。
Documents.DX.Windows.ja は、DioDocs for PDF が Windows システム内で実行されている場合に、ネイティブイメージング API へのアクセスを提供するパッケージで、他のパッケージによって自動的に追加されるものです。
DioDocs for PDF のクラスや他のタイプおよび関連ライブラリは、Adobe が公開している Adobe PDF 仕様バージョン 1.7 および 2.0 に準拠する PDF オブジェクトモデルを公開します。DioDocs for PDF は、低レベルの機能を含む PDF 形式のすべての機能に可能な限り直接アクセスできるように設計されています。さらに、DioDocs for PDF は、プラットフォームに依存しない強力なテキストレイアウトエンジンと、DioDocs for PDF を使用した文書作成を簡単かつ便利に行えるハイレベル機能を提供します。
| 名前空間 | 説明 |
|---|---|
| GrapeCity.Documents.Common | インフラストラクチャおよびユーティリティタイプ（フォントサポートを含む）。 |
| GrapeCity.Documents.Drawing | 抽象 GcGraphics 表面上に描画するためのフレームワーク。 |
| GrapeCity.Documents.Pdf | GcPdfGraphics など、PDF ドキュメントの作成、処理、および変更に使用されるタイプ。ネストした名前空間には、特定の PDF 仕様領域をサポートするタイプが含まれます。 |
| GrapeCity.Documents.Text | テキスト処理用サブシステム。 |
DioDocs for PDF の PDF ドキュメントは、GrapeCity.Documents.Pdf.GcPdfDocument クラスのインスタンスによって表されます。新しい PDF を作成するには、GcPdfDocument のインスタンスを作成し、コンテンツを追加した後、GcPdfDocument.Save() オーバーロードの 1 つを呼び出して、ドキュメントをファイルに書き込みます。1 つの GcPdfDocument インスタンスに対して Save() メソッドを複数回呼び出すことができるため、多くの（異なる）PDF ドキュメントを作成できます。
GcPdfDocument の Load() メソッドを使用して、既存の PDF を分析/変更することもできます。GcPdfDocument のインスタンスで Load() メソッドを呼び出すと、最初にそのインスタンスがクリアされます。ここで重要なのは、Load() メソッドが、ロードされる PDF に対して呼び出し元によって開かれたストリームを受け取ることです。このストリームは読み取り可能でなければならず、ロードしたドキュメントを処理している間は開いたままにしておく必要があります。これは、Load() メソッドがドキュメント全体をメモリに実際にロードするのではなく、各部分を必要に応じてロードしてメモリの占有領域を最小限に抑え、パフォーマンスを向上させるためです。 Load() は「読み取り専用」メソッドです。 GcPdfDocument はロードされたストリームへの書き戻しを試みません。ドキュメントへの変更を保存するには、Save() メソッドを呼び出して、新しく作成されたドキュメントとなる出力ファイルまたはストリームを指定する必要があります。
GcPdfDocument の多くのプロパティとコレクションが、ドキュメントのコンテンツとプロパティへのアクセスを提供します。最も重要なコレクションは Pages（Pages コレクションを参照）で、ほかには Outlines、AcroForm、Security などがあります。
Pages コレクションは、ドキュメントのページのコレクションを表します。新しい GcPdfDocument が作成されたとき、このコレクションは初期状態で空です。一般的なコレクション変更メソッドが用意されており、ページのフェッチ、追加、挿入、削除、移動に使用できます。既存の PDF を GcPdfDocument にロードすると、Pages コレクションには、そのドキュメントからロードされたページが格納されます。これで、ゼロから作成されたドキュメントと同じ方法でドキュメントを変更できるようになります。
GcPdfDocument.Load() メソッドを使用して、既存のドキュメントを検査し、変更できます。次の変更を行うことができます。
現時点では、他の変更はサポートされていません。たとえば、既存のテキストやグラフィックを置き換えようとすると、現状では既存の項目を削除して新しいコンテンツストリームを追加するしかありません。
もう一度注意していただきたいのは、既存のドキュメントを GcPdfDocument インスタンスにロードすると、元のドキュメントとの接続は読み取り専用になるということです。つまり、コンテンツは基底のストリームから必要に応じてフェッチされますが、変更を書き戻す試みは行われません。変更を維持する必要がある場合は、GcPdfDocument.Save() メソッドを呼び出してください。
上記の Save() メソッドの他に、GcPdfDocument ではシーケンシャルモードで PDF を作成できます。このモードを使用するには、まずドキュメントの StartDoc() メソッドを呼び出し、このメソッドの唯一のパラメータとして書き込み可能なストリームを指定します。以下の制限がありますが、その後、コンテンツを通常どおりにドキュメントに追加できます。終了したら、EndDoc() メソッドを呼び出してドキュメントの書き込みを完了します。
シーケンシャルモードの制限は次のとおりです。
シーケンシャルモードのメリットは、ドキュメントのページが完成するとすぐに、そのドキュメントのページが基底のストリームに書き込まれることです。特に、極めて大きな PDF を作成する場合は、メモリの占有領域がはるかに小さくなります。
テキストの測定とレイアウトは、GrapeCity.Documents.Text 名前空間の特別なクラスセットによってサポートされています。これらのクラスは、ハイレベル（段落）から最下位レベル（個々のフォントやグリフの機能）までのテキスト要素へのアクセスを含む、機能豊富なオブジェクトモデルを提供します。テキスト処理は完全にプラットフォーム非依存で、オペレーティングシステムが提供する API にも依存しません。
GrapeCity.Documents.Text 名前空間で最も重要なクラスは TextLayout です。これは、テキストの 1 つ以上の段落を表し、次の機能をサポートします。
すべての機能が縦書き（中国語または日本語）や RTL/双方向テキストで完全にサポートされています。
テキストが TextLayout クラスのインスタンスに追加されて処理されると、指定されたフォントのグリフを使用してテキストの表現が生成されます。必要に応じて、元のテキストの任意のフラグメントについて、生成されたレイアウト内の座標を取得できます。
DrawTextLayout メソッドを使用して、TextLayout インスタンスを直接 GcGraphics にレンダリングすることもできます（グラフィックを参照）。GcGraphics にはシンプルな MeasureString/DrawString メソッドも便宜的に提供されています。
DioDocs for PDF は、描画を行うグラフィック面を提供します。これは抽象基本クラス GcGraphics の実装である GcPdfGraphics クラスによって表されます。 GcPdfGraphics は、線、四角形、ポリゴン、楕円などの通常のグラフィックプリミティブの測定、ストローク、塗りつぶしを行うことができる、柔軟で豊富なオブジェクトモデルを提供します。描画（ストローク）は、実線または破線で行うことができ、図形は単色ブラシまたはグラデーションブラシで塗りつぶすことができます。図形レンダリングメソッドの例については、GcPdfGraphics.DrawEllipse() または GcPdfGraphics.FillEllipse() メソッドを参照してください。複雑な図形は、グラフィックパスを使用して作成およびレンダリングできます。 例については、GcPdfGraphics.DrawPath() メソッドを参照してください。
3x2 行列を使用したグラフィック変換を完全にサポートしています（テキストを含む）。詳細については、GcPdfGraphics.Transform() メソッドを参照してください。
GcPdfGraphics と TextLayout で使用されるデフォルトの測定単位は、プリンタポイント（1/72 インチ）です。必要な場合は、GcPdfGraphics クラスと TextLayoutクラスの両方にある Resolution プロパティを使用して、任意の解像度に変更できます。
すべてのグラフィックオブジェクトの座標は、グラフィック面（GcPdfGraphics の場合、通常はページ）の左上隅から測定されます。これを変更するには、GcPdfGraphics.Transform を使用します。
PDF ドキュメント内のページに描画するには、そのページの GcPdfGraphics のインスタンスを使用する必要があります。GcPdfDocument.Pages コレクション内の各ページには、そのページのグラフィックをフェッチする Graphics プロパティがあります。そのプロパティを取得し、返されたグラフィックインスタンスに描画するだけです。初期状態では、各ページに 1 つのグラフィックが関連付けられています。ただし、ページに複数のコンテキストストリームが含まれている場合は、各コンテキストストリームが独自のグラフィックを持ち、Page.Graphics プロパティは、最後（1 番上）のコンテンツストリームのグラフィックを返します。(ページのすべてのコンテンツストリームには、ContentStreams コレクションを介してアクセスできます。)
Html は、HTML を PDF ファイルや PNG、JPEG、WebP 形式の画像にレンダリングするユーティリティライブラリです。GcHtml は、Chrome または Edge ブラウザ（現在のシステムに既にインストールされているか、一般的な Web サイトからダウンロードしたもの）をヘッドレスモードで使用します。また、.NET アプリケーションが x64、x86、AnyCPU のいずれのプラットフォームをターゲットに構築されているかは関係ありません。ブラウザは別プロセスで継続的に動作しています。
GrapeCity.Documents.Html ライブラリは、HTML レンダリング機能を公開するプラットフォームに依存しないメインパッケージで構成されています。 メインパッケージには、以下の名前空間が含まれます。
| 名前空間 | 説明 |
|---|---|
|
HTMLをPDFファイルにレンダリングするための拡張メソッドを提供し、HTMLをPDFファイルにレンダリングするためのフォーマット属性を表します。 この名前空間では、次のクラスが含まれます。
|
|
| GrapeCity.Documents.Html |
HTMLをPDFまたは画像に変換するメソッドを提供し、PDFまたは画像のパラメータを定義します。 この名前空間では、次のクラスが含まれます。 |
| GrapeCity.Documents.Drawing |
HTMLを画像にレンダリングする拡張メソッドとフォーマット属性を提供します。 この名前空間では、次のクラスが含まれます。 |
BrowserFetcher クラスには、GetSystemChromePath() と GetSystemEdgePath() の2つの静的メソッドがあります。 これらのメソッドは、それぞれ Chrome または Edge ブラウザの実行ファイルへのパスを返します。また、Chromium をダウンロードし、ローカルフォルダにインストールして使用する方法もあります。実行するには、BrowserFetcher クラスのインスタンスを作成し、必要に応じて、ホスト、プラットフォーム、リビジョン、インストール先フォルダなどの情報を渡します。その後、BrowserFetcher.GetDownloadedPath() メソッドを呼び出すと、必要に応じて Chromium をダウンロードし、Chromium を起動するための実行ファイルへのパスを返します。
GcHtmlBrowser クラスには、HTML を PDF や画像に変換できるメソッドがあります。 BrowserFetcher クラスで検出した Chromium ブラウザや Edge ブラウザを起動するための実行ファイルへのパスを指定して、ブラウザプロセスをバックグラウンドで効果的に実行する GcHtmlBrowser クラスのインスタンスを作成できます。また、GcHtmlBrowser は、LaunchOptions タイプの別のパラメータも受け取ります。LaunchOptions クラスは、ブラウザの起動に固有の様々な設定を提供します。
GcHtmlBrowser クラスには、NewPage(Uri uri) と NewPage(string html) という2つの重要なメソッドがあります。どちらのメソッドも、指定した Web アドレス、ファイル、または任意の HTML コンテンツに移動した後のブラウザタブを表す HtmlPage クラスのインスタンスを返します。PageOptions 型の第2パラメータを使用すると、HTTP認証のためのユーザー名やパスワード、JavaScript の無効化、遅延読み込みなど、新しいブラウザページに適用される様々なプロパティを設定することができます。
メモ:
HtmlPage クラスは、指定した Web アドレス、ファイル、または任意の HTML コンテンツに移動した後のブラウザタブを表します。このクラスには、SaveAsPdf、SaveAsPng、SaveAsJpeg、SaveAsWebp といったメソッドがあり、現在のページをそれぞれ PDF、PNG、JPEG、WebP 形式のラスター画像として保存できます。これらのメソッドの最初のパラメータは、保存先のファイルまたはストリームを指定します。第2パラメータは、HTML ページを単一の PDF ページとしてレンダリングするための追加オプションを渡し、ページサイズ、余白、ヘッダーとフッターなどを設定します。
HtmlPage クラスには、HTML ページのコンテンツの操作に役立つメソッドも含まれています。例えば、GetContent メソッドを使用すると、ページの完全な HTML コンテンツを取得することができます。SetContent メソッドは、HTML マークアップを更新します。Reload メソッドを使用して Web ページを再読み込みしたり、EvaluateExpression メソッドを使用してブラウザのコンテキスト内でスクリプトを実行したりすることもできます。WaitForNetworkIdle メソッドは、非同期の Web コンテンツの読み込みに役立ちます。
PdfOptions クラスは、HTML を PDF にレンダリングするための出力設定を表し、Chromium PDF exporter のためのパラメータを定義しています。PDF の場合、透明度はサポートしていません。
PageWidth プロパティと PageHeight プロパティが設定されていない場合、デフォルトでレター用紙サイズ（8.5 x 11 インチ）が使用されます。このクラスの Landscape プロパティは、用紙の向きを示し、FullPage プロパティが true に設定されている場合は無視されます。Marginsプロパティは、ページの余白をインチ単位で指定でき、デフォルト値は0です。Scale プロパティは、PDF のコンテンツを拡大縮小します（拡大縮小率は0.1から2.0まで設定できます）。また、生成されるページの相対的なサイズを変更しないように、必要に応じて PageWidth プロパティと PageHeight プロパティに拡大縮小された値を設定します。
PageRanges プロパティを使用して、出力する PDF ファイルのページ数を制限できます。「1-5、8、11-13」のような文字列で、希望するページ番号を指定できます。無効なページ範囲（例えば「9-5」など）は無視されます。
FullPage プロパティを true に設定すると、HTML 全体を単一の PDF ページとしてエクスポートできます。この場合、Scale を除く他のすべてのレイアウト設定は無視されます。
HtmlToPdfFormatクラスには、DrawHtml 拡張メソッドを使用して GcPdfGraphicsExt クラスで HTML を PDF ファイルにレンダリングするためのフォーマット属性が含まれます。HTML は、まず、単一ページ（FullPage が true にの場合）または指定されたページサイズ（MaxPageWidth、MaxPageHeight）、Scale、およびDefaultBackgroundColor で一時的な PDF に描画されます。その後、GcPdfDocumentに読み込まれ、HTML コンテンツの実際のサイズにトリミングされます。結果は、PDF の FormXObject として GcPdfGraphics にレンダリングされます。
なお、MaxPageWidth または MaxPageHeight プロパティが明示的に設定されていない場合、それらは 200 インチに等しいと見なされます。DefaultBackgroundColor は、デフォルトでは Color.Whiteと同等です。
HtmlToPdfFormat のその他のプロパティは、PageOptions/PdfOptions クラスの対応するプロパティにマップされています。
| HtmlToPdfFormat プロパティ | PageOptions/PdfOptions プロパティ |
| WindowSize | PageOptions.WindowSize |
| DefaultBackgroundColor | PageOptions.DefaultBackgroundColor |
| FullPage | PdfOptions.FullPage |
| DisplayBackgroundGraphics | PdfOptions.PrintBackground |
| Scale | PdfOptions.Scale |
| MaxPageWidth | PdfOptions.PageWidth |
| MaxPageHeight | PdfOptions.PageHeight |
GcHtml には、GcPdfGraphics を拡張し、HTML テキストまたはページをレンダリングや測定できる 4 つのメソッドがあります。