PDF アノテーションの操作

PDF アノテーションの操作

C++ 用 Aspose.PDF FOSS の PDF アノテーションは、Annotation 基底クラスとその具体的なサブタイプ（TextAnnotation、LinkAnnotation、HighlightAnnotation、FreeTextAnnotation、CircleAnnotation、WatermarkAnnotation、WidgetAnnotation など）で表現されます。各ページは Page.Annotations() を通じてアノテーションを公開し、AnnotationCollection を返します。本ガイドでは、ページへのアノテーションの追加、イテレーションと削除、既存ドキュメントからのアノテーションの読み取り、リンクアクションの添付、外観のカスタマイズ、そしてアノテーションのフラッティングについて説明します。

ページへのアノテーションの追加

具体的なアノテーションインスタンスを作成し、Rectangle で位置を設定し、AnnotationCollection.Add() を使ってページのコレクションに追加します。TextAnnotation は、ページ上の点に固定された付箋スタイルのコメントを表します：

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& page = doc.Pages()[1];

    Aspose::Pdf::Annotations::TextAnnotation note(doc);
    note.Rect(Aspose::Pdf::Rectangle(100.0, 700.0, 200.0, 720.0, false));
    note.Contents("Reviewed and approved");

    page.Annotations().Add(note);
    doc.Save("annotated.pdf");
}

Annotation.Contents() / Contents(value) はノートテキストの取得と設定を行い、Annotation.Rect() / Rect(value) はページ上でアノテーションの位置を決定します。

アノテーションのイテレーションと削除

AnnotationCollection はカウント、インデックスアクセス、メンバーシップのチェック、値またはインデックスによる削除をサポートします：

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("input.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

    std::cout << "Annotation count: " << annotations.Count() << "\n";

    for (int i = 0; i < annotations.Count(); ++i) {
        std::cout << "Contents: " << annotations[i].Contents() << "\n";
    }

    if (annotations.Count() > 0) {
        annotations.Delete(0);   // remove by index
    }
    annotations.Clear();         // remove everything
}

AnnotationCollection.Contains(annotation) と Remove(annotation) は特定のアノテーション参照に対して動作します；Delete(index) は位置で削除し、Delete(annotation) はインデックスを必要とせず特定のアノテーションを削除します。IsReadOnly() はコレクションが変更可能かどうかを報告します。

既存のドキュメントからアノテーションを読み取る

ドキュメントがロードされると、アノテーションはすでに設定されており、何も追加せずに検査できます。Annotation.AnnotationType() はサブタイプ（AnnotationType::Text、AnnotationType::Highlight、AnnotationType::Link、AnnotationType::FreeText、AnnotationType::FileAttachment、AnnotationType::Watermark、その他）を報告します：

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();

    for (int i = 0; i < annotations.Count(); ++i) {
        auto& a = annotations[i];
        if (a.AnnotationType() == Aspose::Pdf::Annotations::AnnotationType::Text) {
            std::cout << "Note: " << a.Contents() << "\n";
        }
    }
}

アノテーションの順序とサブタイプは保存/再読み込みの往復で保持されるため、ドキュメントを読み込んだ後に Annotations() をインデックス付けするコードは、ファイルが書き込まれたときと同じシーケンスを見ることができます。

リンクアノテーションとアクション

LinkAnnotation はページにクリック可能な領域を付加し、アクティブ化されたときに PdfAction をディスパッチします。NamedAction は事前定義されたナビゲーションターゲットへジャンプし、JavascriptAction は ECMAScript 文字列を実行し、SubmitFormAction は FileSpecification を介して URL にフォームデータを投稿します：

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/link_annotation.hpp>
#include <aspose/pdf/annotations/named_action.hpp>
#include <aspose/pdf/annotations/predefined_action.hpp>
#include <aspose/pdf/rectangle.hpp>

int main() {
    Aspose::Pdf::Document doc;
    auto page = doc.Pages().Add();

    Aspose::Pdf::Annotations::LinkAnnotation link(
        page, Aspose::Pdf::Rectangle(0.0, 0.0, 100.0, 20.0, false));
    link.Action(Aspose::Pdf::Annotations::NamedAction(
        Aspose::Pdf::Annotations::PredefinedAction::LastPage));

    page.Annotations().Add(link);
    doc.Save("linked.pdf");
}

LinkAnnotation.Action(value) は任意の PdfAction サブタイプを受け取り内部でクローンするため、アノテーションはアクションの独自コピーを保持します。LinkAnnotation.Destination() / Destination(value) はアクションの代わりに明示的なナビゲーションターゲットを設定し、Highlighting() / Highlighting(value) はリンクがクリックされたときに表示されるビジュアルフィードバックを制御します。

アノテーションの外観：枠線、フラグ、カラー

すべてのAnnotationは、Border、AnnotationFlagsのビットフィールド、そして外観を描画するために使用されるColorを公開します：

#include <aspose/pdf/annotations/border_style.hpp>
#include <aspose/pdf/annotations/annotation_flags.hpp>
#include <aspose/pdf/color.hpp>

// 'note' is an existing Annotation reference, e.g. from AnnotationCollection.
note.Border().Width(2);
note.Border().Style(Aspose::Pdf::Annotations::BorderStyle::Dashed);
note.Flags(Aspose::Pdf::Annotations::AnnotationFlags::Print);
note.Color(Aspose::Pdf::Color::Red());

Border.Style()はBorderStyle::Solid、Dashed、Beveled、Inset、またはUnderlineを受け入れます。Border.Effect()はさらに、BorderEffect::Cloudyアウトラインをサポートし、EffectIntensity()がその強さを制御します。AnnotationFlagsはビットフィールドです — Print、NoZoom、ReadOnly、LockedContentsなどの値を組み合わせて、表示内容を変更せずにビューア内でアノテーションの動作を制御します。

アノテーションのフラット化

単一のアノテーションは、Annotation.Flatten()を直接呼び出すことでフラット化（ページコンテンツにマージされ、インタラクティブでなくなる）できます：

#include <aspose/pdf/document.hpp>

int main() {
    Aspose::Pdf::Document doc("annotated.pdf");
    auto& annotations = doc.Pages()[1].Annotations();
    for (int i = 0; i < annotations.Count(); ++i) {
        annotations[i].Flatten();
    }
    doc.Save("flattened.pdf");
}

文書全体のアノテーション操作では、PdfAnnotationEditorはAPI全体で使用されている共通のFacadeパターンに従います：BindPdf()でソース文書をバインドし、1つ以上のアノテーション操作を適用し、最後にSave()で結果を書き出します：

#include <aspose/pdf/facades/pdf_annotation_editor.hpp>

int main() {
    Aspose::Pdf::Facades::PdfAnnotationEditor editor;
    editor.BindPdf("annotated.pdf");
    editor.FlatteningAnnotations();
    editor.Save("flattened.pdf");
}

PdfAnnotationEditor.DeleteAnnotations()はバインドされた文書からすべてのアノテーションを削除します；DeleteAnnotations(annotType)は削除を単一のAnnotationTypeに限定します。ImportAnnotationsFromXfdf(xfdfFile)とImportAnnotationsFromFdf(fdfFile)は他のPDFビューアからエクスポートされたアノテーションデータを読み込みます。

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

• 新しく作成したアノテーションは、Document.Save()を呼び出す前に必ずPage.Annotations()に追加してください — コレクションに追加されていないアノテーションは出力ファイルに書き込まれません。
• アノテーションがまだ存在しているか確信がない場合は、AnnotationCollection.Contains(annotation) を使用してから Remove() を呼び出してください；Remove() は、アノテーションが存在しないときに例外を投げる代わりに false を返します。
• 信頼できない、またはサードパーティの PDF ファイルからロードされたアノテーションを反復処理する際、サブタイプの挙動に対してキャストや分岐を行う前に Annotation.AnnotationType() を確認してください。
• 文書をアーカイブする前に Annotation.Flatten()（ドキュメント全体の場合は PdfAnnotationEditor.FlatteningAnnotations()）でアノテーションをフラット化し、他のツールのレビューアがあなたが作成した外観と同じものを確認できるようにします。
• AnnotationFlags はビットフィールドです — フラグを列挙型の基となる整数値と組み合わせて使用し、同時に複数のフラグが有効になる可能性があることを前提にしてください。

一般的な問題

FAQ

PDF ページにコメント形式のアノテーションを追加するにはどうすればよいですか？

対象の Document を持つ TextAnnotation を作成し、その Rect() と Contents() を設定してから、保存前に page.Annotations() に追加します。

自分が見ている注釈の種類はどうやって確認できますか？

Annotation.AnnotationType() を呼び出すと、AnnotationType 列挙型の値が返されます。たとえば Text、Link、Highlight、FreeText、FileAttachment、または Watermark です。

1つの注釈が複数のフラグを持つことはできますか？

はい。AnnotationFlags はビットフィールドであり（Default、Invisible、Hidden、Print、NoZoom、ReadOnly、LockedContents など）、複数のフラグを1つの注釈に組み合わせることができます。

1つの注釈をフラット化することと、ドキュメント全体をフラット化することの違いは何ですか？

Annotation.Flatten() は単一の注釈をそのページのコンテンツにマージします。PdfAnnotationEditor.FlatteningAnnotations()（ページ範囲でオプション的にスコープ指定でき、AnnotationType は start、end、annotType を受け取るオーバーロードを介して指定できます）は、1回の呼び出しで結合されたドキュメント全体にわたってフラット化します。

ドキュメントから特定のタイプの注釈をすべて削除するにはどうすればいいですか？

PdfAnnotationEditor.BindPdf() でドキュメントをバインドし、DeleteAnnotations(annotType) を対象の AnnotationType で呼び出し、最後に結果を Save() します。

API Reference 概要

参照

• Aspose.PDF — Enterprise Documentation