PDAnnotation

PDAnnotationは、Apache PDFBox PDModel APIにおける高レベルクラスで、PDFアノテーションオブジェクトへのプログラマティックなアクセスを提供します。アノテーションは、PDF仕様 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) で定義されているインタラクティブな要素で、ユーザーが元のコンテンツを変更することなく、PDFドキュメントにコメント、ハイライト、フォームフィールド、その他のマークアップを追加できるようにします。PDAnnotationクラスは、開発者がPDFファイル内のこれらのアノテーション構造を読み取り、作成、変更、削除できるようにするJavaオブジェクト表現として機能します。

PDAnnotationは、Apache PDFBoxのオブジェクト指向PDModelレイヤー内の抽象基底クラスで、PDFドキュメントに表示される様々なタイプのアノテーションを表現します。PDF構文を直接扱う低レベルのCOSDictionaryオブジェクトとは異なり、PDAnnotationは、位置、外観、色、動作などのアノテーション属性を操作するための型安全なメソッドとプロパティを備えた、より高レベルの抽象化を提供します。

このクラス階層には、 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) で定義された特定のアノテーションタイプに対応する多数のサブクラスが含まれています。これには、PDAnnotationText（付箋）、PDAnnotationLink（ハイパーリンク）、PDAnnotationMarkup（ハイライトとマークアップ）、PDAnnotationWidget（フォームフィールド）などがあります。各サブクラスは、基底のPDAnnotationクラスから共通機能を継承しながら、そのアノテーションタイプに適した特化したメソッドを提供します。

PDAnnotationは、ページコンテンツを表現するPDPageクラスや、フォント、画像、その他のアセットを管理するPDResourcesとは異なり、ページのコンテンツストリームとは別のレイヤーに存在するインタラクティブなオーバーレイとマークアップ要素に特化しています。

PDFドキュメントを扱う開発者にとって、PDAnnotationはインタラクティブ機能とドキュメントレビューワークフローを実装する上で不可欠です。このクラスにより、アプリケーションはプログラマティックにデータ収集用のフォームフィールドを追加し、ドキュメントセクション間のナビゲーションリンクを作成し、機密情報の墨消しを適用し、共同ドキュメントレビューのためのコメントシステムを実装することができます。

PDF/UA-1 ( Citation: N.A., 2014 (N.A.). (2014). Document management applications — Electronic document file format enhancement for accessibility — Part 1: Use of ISO 32000-1 (PDF/UA-1) .  International Organization for Standardization Retrieved from https://www.iso.org/standard/64599.html ) などの標準に基づくアクセシビリティ要件では、特に支援技術からプログラマティックにアクセス可能である必要があるフォームフィールドやインタラクティブ要素について、適切なアノテーション処理が必要とされることが多くあります。PDAnnotationを理解することで、開発者はインタラクティブ機能を追加しながら、PDF操作コードがアクセシビリティのコンプライアンスを維持できるようにすることができます。

このクラスはまた、既存のアノテーションからメタデータを抽出するための重要な機能を提供し、アプリケーションがコメントをインデックス化し、フォームデータを抽出し、ドキュメントのマークアップを分析し、マージ、分割、変換などのPDF処理操作中にアノテーション情報を保持できるようにします。

PDAnnotationは、PDF仕様で定義されたアノテーションのプロパティを含むCOSDictionaryオブジェクトをラップすることで機能します。getAnnotations()を使用してPDPageオブジェクトからアノテーションを取得すると、PDFBoxは基底ディクショナリの/Subtypeエントリに基づいて、適切なPDAnnotationサブクラスを自動的にインスタンス化します。

PDAnnotationを通じてアクセス可能な主要プロパティには、アノテーション矩形（ページ上の位置とサイズを定義）、外観ストリーム（レンダリング方法を制御）、フラグ（印刷や読み取り専用ステータスなどの動作を制御）、作成日や作成者などのメタデータがあります。開発者はセッターメソッドを使用してこれらのプロパティを変更でき、変更はドキュメント保存時に基底のCOSオブジェクトに反映されます。

新しいアノテーションを作成するには、適切なサブクラスをインスタンス化し、矩形境界などの必須プロパティを設定し、ページのアノテーションリストにアノテーションを追加する必要があります。 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) のアノテーションはドキュメントレベルの構造ではなくページレベルのオブジェクトであるため、アノテーションは特定のページに関連付ける必要があります。多くのアノテーションタイプでは、異なるPDFビューアー間で正しく表示されるように、外観ストリームも生成する必要があります。

フォームフィールドアノテーション（PDAnnotationWidget）には特別な考慮事項があります。これらはドキュメントのインタラクティブフォーム（AcroForm）に接続され、アノテーションの視覚的表現とフォームフィールドのデータ構造との間に双方向の関係を作成します。

• PDPage – アノテーションが表示されるPDFドキュメント内の単一ページを表現
• PDModel – PDAnnotationや関連クラスを含むApache PDFBoxの高レベルAPIレイヤー
• PDResources – ページコンテンツとアノテーションの外観で使用されるフォント、画像、その他のリソースを管理
• COSDictionary – PDF構文でアノテーションプロパティを格納する低レベルデータ構造
• AcroForm – ウィジェットアノテーションで表現されるフォームフィールドを管理するPDFインタラクティブフォーム構造