ファサード API

ファサード API

A facade は、コア上に構築されたシンプルでタスク指向のラッパーです Document / Page / Annotation オブジェクトモデルです。ページツリーを自分で辿る代わりに、ソースPDFにファサードをバインドし、少数の高レベルメソッドを呼び出して結果を保存します。すべてのファサードは Aspose::Pdf::Facades は、以下で定義された同じ最小限の契約を実装します IFacade (BindPdf, Close) と、ファサードが出力を生成する場合、 ISaveableFacade (Save). 抽象的な Facade and SaveableFacade 基底クラスは、下記の具体的エディタが構築するデフォルトの bind/close/save 実装を提供します: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata、そしてフォーム志向の FormEditor / FormFieldFacade ペア。

Facade 基底クラスと bind/save ライフサイクル

IFacade は BindPdf(srcFile) を宣言します（インメモリ Document を受け取るオーバーロード版もあります）および Close()。ISaveableFacade は出力を書き込む facade 用に Save(destFile) を追加します。Facade は IFacade を実装し、バインドされた Document() を公開するので、facade メソッドで必要なものがカバーされていない場合にコアオブジェクトモデルに戻ることができます；SaveableFacade は Facade を Save 実装で拡張します。以下のすべての具体的エディタはこの形を継承するため、同じ bind → operate → save パターンが ファサード API 全体に適用されます。

AcroForm フィールドの入力と編集

FormEditor は、すでにバインドされたドキュメント上の AcroForm フィールドを追加、削除、名前変更、再配置します。AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) は、指定されたページ座標に、指定された FieldType（Text、CheckBox、Radio、ComboBox、ListBox、PushButton、MultiLineText、Barcode、Signature、Image、Numeric、DateTime）の新しいフィールドを作成します。RemoveField、RenameField、MoveField、および SetFieldAttribute は既存のフィールドを管理し、SetFieldScript / AddFieldScript は JavaScript アクションを付加します。SubmitFlag（SubmitFormFlag 値 — Fdf、Html、Xfdf、FdfWithComments、XfdfWithComments、または Pdf）は、送信ボタンがフォームデータを送信する方法を制御し、SetSubmitUrl はターゲットエンドポイントを設定します。

各新しいフィールドの視覚的外観は、FormEditor.Facade() を通じて制御され、FormFieldFacade を返します。その Font プロパティは FontStyle 値（Helvetica、HelveticaBold、Courier、TimesRoman、Symbol および関連バリアント）を受け取り、TextEncoding は EncodingType（Winansi、Macroman、Identity_h、Identity_v、Cp1250、Cp1252、Cp1257）を受け取り、BorderStyle / BorderWidth はフィールドの枠線を設定します。

FormEditor editor;
editor.SrcFileName("template.pdf");
editor.DestFileName("output.pdf");
editor.AddField(FieldType::Text, "FirstName", 1, 100, 700, 300, 720);
editor.SetFieldAttribute("FirstName", AnnotationFlags::Print);
editor.Save();

PdfBookmarkEditor でアウトラインを管理

PdfBookmarkEditor は PDF アウトラインエントリを作成、抽出、変更、削除します。CreateBookmarks() は Bookmarks コレクション（各エントリは Bookmark で、Title、PageNumber、Action、Level、Open、および ChildItems（入れ子のアウトライン用））をバインドされたドキュメントに書き込みます。ExtractBookmarks() は既存のアウトラインを Bookmarks コレクションとして読み戻し、DeleteBookmarks() はオプションの title フィルタを使用してエントリを削除します。ExportBookmarksToXML / ImportBookmarksWithXML はアウトラインを XML ファイルを介してラウンドトリップし、ExtractBookmarksToHTML / ExportBookmarksToHtml はアウトラインを HTML ページとしてレンダリングします。

PdfBookmarkEditor editor;
editor.BindPdf("input.pdf");
Bookmarks bookmarks = editor.ExtractBookmarks();
editor.DeleteBookmarks("Draft");
editor.Save("output.pdf");

PdfAnnotationEditor で注釈を編集

PdfAnnotationEditor はドキュメント全体の注釈をフラット化およびインポートします。FlatteningAnnotations() は注釈をページのコンテンツストリームにマージし、インタラクティブなオブジェクトではなく静的コンテンツとして描画されます；start/end ページ範囲と注釈タイプを受け取るオーバーロードは操作を制限します。ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf は外部 FDF/XFDF ファイルから注釈を取り込み、DeleteAnnotations()（単一タイプの場合は DeleteAnnotations(annotType)）はそれらを削除します。

PdfAnnotationEditor editor;
editor.BindPdf("commented.pdf");
editor.FlatteningAnnotations();
editor.Save("flattened.pdf");

PdfContentEditor でページコンテンツを書き換える

PdfContentEditor はページを再構築せず、既に生成されたページのコンテンツストリームを編集します。ReplaceText(srcText, destText) は文書全体で一致するテキストを検索・置換し、置換を単一ページに限定するオーバーロードも提供します。ReplaceImage(pageNum, imageNum, fileName) と DeleteImage(pageNum, imageNum) は既存の画像 XObject を入れ替えまたは削除します。DeleteStampById / HideStampById / ShowStampById / MoveStampById はページ上のスタンプオブジェクトを管理します（スタンプの基になるコンテンツは Form または Image のいずれかで、StampType 列挙型に従います）。AddDocumentAdditionalAction / AddDocumentAttachment はドキュメントレベルの JavaScript アクションとファイル添付を付加します。

PdfContentEditor editor;
editor.BindPdf("template.pdf");
editor.ReplaceText("{{CustomerName}}", "Jane Doe");
editor.Save("output.pdf");

PdfExtractor でテキストと添付ファイルを抽出

PdfExtractor は BindPdf でバインドすることも、すでに開いている Document から直接構築することもできます。ExtractText() の後に HasNextPageText() / GetNextPageText(outputFile) を続けることで、ドキュメントをページごとに走査します。埋め込みファイルについては、GetAttachNames() が存在する添付ファイルを一覧表示し、GetAttachment( outputPath) が次のファイルをディスクに書き出します。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/facades/pdf_extractor.hpp>
#include <iostream>

int main() {
    Aspose::Pdf::Document doc("attachments.pdf");
    Aspose::Pdf::Facades::PdfExtractor extractor(doc);

    auto names = extractor.GetAttachNames();
    std::cout << "Attachments found: " << names.size() << "\n";

    if (!names.empty()) {
        extractor.GetAttachment("extracted-attachment.bin");
    }
}

ExtractImage() / HasNextImage() / GetNextImage(outputFile) は、GetNextPageText がページを巡回するのと同じ方法で埋め込みラスタ画像を抽出します。

PdfFileEditor を使用したファイルの結合と分割

PdfFileEditor はバインドされた Document ではなくファイルパスで動作するため、すべてのメソッドは入力/出力ファイル名を直接受け取ります。Concatenate（および例外をスローしない TryConcatenate）は複数のファイルをマージします；Append はあるファイルから別のファイルへページ範囲を挿入します；Extract はページ範囲または単一ページを新しいファイルに抽出します；Delete はページを削除します；そして SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks は文書をページ単位、ページごと、または固定サイズのチャンクに分割します。MakeBooklet と MakeNUp は小冊子印刷や N-up 印刷のためにページを再配置し、ResizeContents / AddMargins / AddPageBreak はファイル全体のページジオメトリを調整します。ほとんどの操作には、失敗時に例外をスローする代わりに false を返す Try 接頭辞付きの対応メソッドがあります。

PdfFileEditor editor;
editor.Concatenate("part1.pdf", "part2.pdf", "merged.pdf");
editor.Extract("merged.pdf", 1, 3, "first-three-pages.pdf");

PdfConverter を使用したページの画像へのレンダリング

PdfConverter はバインドされた文書ページをラスタ形式にレンダリングします。DoConvert() はページ範囲（StartPage / EndPage）を反復処理のために準備し、HasNextImage () / GetNextImage(outputFile) がページを一つずつ順に処理します。SaveAsTIFF は解像度、圧縮、TiffSettings 用のオーバーロードを備えて、全範囲を単一のマルチページ TIFF に書き込みます。RenderingOptions と Resolution はラスタライズ品質を制御し、ImageMergeMode（Vertical、Horizontal、Center）は呼び出し元が複数のレンダリング済みページ画像を1つの画像に結合する際の結合方法を管理します。

PdfConverter converter;
converter.BindPdf("report.pdf");
converter.Resolution(Aspose::Pdf::Devices::Resolution(150));
converter.DoConvert();
while (converter.HasNextImage()) {
    converter.GetNextImage("page.png");
}

PdfFileSecurity を使用した文書の暗号化

PdfFileSecurity はソースファイルをバインドし、暗号化の適用または解除を行います。EncryptFile(userPassword, ownerPassword, privilege, keySize) は DocumentPrivilege（デフォルトコンストラクタと AllowPrint、AllowCopy、AllowModifyContents などのブールセッターで構築）と KeySize（x40、x128、または x256）を使用して暗号化します；5番目の cipher 引数を受け取るオーバーロードは、Algorithm（RC4 または AES）を明示的に選択します。DecryptFile( ownerPassword)、ChangePassword、SetPrivilege は残りのパスワード管理ケースをカバーし、いずれも例外をスローしない Try 接頭辞付きバリアントがあります。

PdfFileSecurity security;
security.BindPdf("input.pdf");

DocumentPrivilege privilege;
privilege.AllowPrint(true);
privilege.AllowModifyContents(false);

security.EncryptFile("user-pass", "owner-pass", privilege, KeySize::x256);

PdfFileSignature を使用した署名と検証

PdfFileSignature は、結合された文書上のデジタル署名に署名、認証、検査を行います。Sign(sigName, reason, contact, location, signature) は既存の署名フィールドに新しい署名を適用します；Certify は認証署名を適用します。GetSignatureNames(onlyEmpty) と GetBlankSignatureNames() は文書の署名フィールドを SignatureName 値として返し、VerifySignature(sigName) / IsCoversWholeDocument (sigName) は有効性とカバレッジをチェックします。RemoveSignature と RemoveSignatures() は既存の署名を削除し、SetCertificate(pfxFile, password) は署名資格情報を提供してから Sign を呼び出します。

PdfFileSignature signature;
signature.BindPdf("contract.pdf");
signature.SetCertificate("signing-cert.pfx", "cert-password");
bool signed_ok = signature.ContainsSignature();
signature.Save();

PdfFileStamp でヘッダー、フッター、ページ番号にスタンプを付けます。

PdfFileStamp は結合されたファイルのすべてのページに繰り返しコンテンツをオーバーレイします。AddPageNumber(format) は開始番号と任意の明示的座標を使用してページ番号ラベルをスタンプします；AddHeader(text, topMargin) と AddFooter(text, bottomMargin) は指定された余白に繰り返しヘッダー/フッターテキストを追加し、左/右余白用のオーバーロードも提供します。KeepSecurity は出力ファイルの既存の暗号化を保持し、Close() は結合文書を最終化して解放します。

PdfFileStamp stamp;
stamp.InputFile("input.pdf");
stamp.OutputFile("stamped.pdf");
stamp.AddPageNumber("Page # of #", 1);
stamp.Close();

PdfFileInfo を使用した文書情報の読み書き

PdfFileInfo は、フルオブジェクトモデルを開かずに、従来の PDF /Info 辞書と基本的なページごとのジオメトリを読み取り書き換えます。Author、Title、Subject、Keywords、CreationDate、および ModDate は読み書き可能なプロパティです；Producer と GetPdfVersion() は読み取り専用です。GetPageWidth、GetPageHeight、GetPageRotation はページ番号でページごとのジオメトリを返し、IsEncrypted() / HasOpenPassword() / HasEditPassword() は文書の保護状態を報告します。SaveNewInfo(outputFile) は変更を再び書き出します。

PdfFileInfo info;
info.BindPdf(document);
info.Title("Updated Report Title");
info.SaveNewInfo("output.pdf");

PdfPageEditor を使用したページの再配置

PdfPageEditor はページコンテンツをブロックとして移動、サイズ変更、回転させます。MovePosition(offsetX, offsetY) は ProcessPages で選択されたページ上のコンテンツをシフトします；Zoom はそれをスケールします。Alignment（AlignmentType の一種 — Left、Center、または Right、それぞれ対応する静的メソッドから取得）と VerticalAlignment（VerticalAlignmentType の一種 — Top、Center、Bottom）は、ApplyChanges() が実行された後、ターゲット PageSize 内でコンテンツがどのように配置されるかを制御します。GetPageRotation はページの現在の回転角度（度）を読み取ります。

PdfPageEditor editor;
editor.BindPdf("input.pdf");
editor.Alignment(AlignmentType::Center());
editor.MovePosition(0, -20);
editor.ApplyChanges();

PdfXmpMetadata を使用した XMP メタデータの管理

PdfXmpMetadata はドキュメントの XMP パケット上にあるマップのようなファサードです。Add(key, value)、Remove(key)、Contains(key) / ContainsKey(key)、および TryGetValue(key, value) は個々のエントリを管理し、Keys() と Values() はパケット全体を列挙します。RegisterNamespaceURI(prefix, namespaceURI) はプロパティを追加する前にカスタム XMP 名前空間を宣言します。よく知られたプロパティ名は DefaultMetadataProperties（CreateDate、CreatorTool、Identifier、ModifyDate、Nickname、Thumbnails など）に一覧され、PropertyFlag（ReadOnly、Required、NoExport）は登録済みプロパティのスキーマ制約を記述します。

PdfXmpMetadata xmp;
xmp.BindPdf(document);
xmp.Add("dc:creator", "Report Generator");
xmp.Save("output.pdf");

ヒントとベストプラクティス

• すべてのファサードは同じ BindPdf（またはファイル名を受け取るコンストラクタ）→ 操作 → Save/Close のシーケンスに従います — 1 つのファサードを学べば次にも直接応用できます。
• 信頼できない、または予測不可能なソースからファイルを処理する場合は、PdfFileEditor と PdfFileSecurity の Try 接頭辞付きメソッドを使用してください — 失敗時に例外を投げる代わりに false を返します。
• PdfFileEditor メソッドはバインドされた Document ではなくファイルパスを受け取ります — Concatenate、Extract、または SplitFromFirst を呼び出す前に、ソースファイルを自分で開く必要はありません。
• ファサードはコアオブジェクトモデルを置き換えるのではなくラップします: Facade は、ファサードメソッドがカバーしないケースのために基礎となる Document() を公開します。
• バインドされたドキュメントの使用が終わったら、Close() を呼び出す（またはサポートされている場合はファサードをスコープ外にする）ことで、基礎となるファイルハンドルを解放します。

一般的な問題

FAQ

ファサードとコア Document API の違いは何ですか？

ファサードは、フォーム入力、ファイル結合、ページへのスタンプ付与など、単一の作業に特化した小さなメソッドインターフェースを提供します。コア API（Document、Page、Annotation）は、すべての PDF オブジェクトへのフルアクセスを提供します。Document() を公開するファサード（Facade 基底クラス経由）は、ファサードメソッドでカバーできない場合にコアモデルに戻ることを可能にします。

すべてのファサードメソッドの前に BindPdf を呼び出す必要がありますか？

はい、IFacade を実装するファサードの場合、BindPdf（PdfExtractor(doc) と同様のコンストラクタオーバーロード）を、バインドされたドキュメントを読み取ったり変更したりする任意の操作の前に実行する必要があります。

PdfFileEditor 操作をチェーンできますか？

各 PdfFileEditor メソッドは独自の入力ファイルを読み取り、独自の出力ファイルを書き出すため、あるメソッドの出力ファイルを次の呼び出しの入力ファイルとして渡すことで操作をチェーンします。例えば、Concatenate を merged.pdf に、次に merged.pdf から Extract に渡す、といった具合です。

例外をスローしないエラーモードをサポートしているファサードはどれですか？

PdfFileEditor（TryConcatenate、TryAppend、TryExtract、TrySplitFromFirst、および関連するTry*メソッド）とPdfFileSecurity（TryEncryptFile、TryDecryptFile、TrySetPrivilege、TryChangePassword）は、どちらもTryプレフィックス付きの代替手段を提供し、例外を投げる代わりにboolを返します。

API Reference の概要

参照

• Aspose.PDF — Enterprise Documentation