PDF アノテーション

PDF アノテーション

Page.annotations は AnnotationCollection を公開します — ページ上のすべてのアノテーションに対する可変でシーケンスのようなビューです。各エントリは Annotation（または MarkupAnnotation / LinkAnnotation サブクラス）であり、四角点、インクリスト、色などのサブタイプ固有のデータは、専用属性ではなく get_property() / set_property() を通じて読み書きされます。

アノテーションの追加

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) は新しいアノテーションを作成し、ページに追加します。subtype はプレーン文字列（"Text"、"Square"、"Highlight"）または AnnotationType 列挙型メンバーのいずれかを受け取ります。

import aspose_pdf
from aspose_pdf import Document, AnnotationType

doc = Document()
doc.pages.add()
page = doc.pages[0]

# Plain string subtype
page.annotations.add("Text", (100, 100, 200, 200), "Hello")

# AnnotationType enum, with subtype-specific properties
page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)

プロパティの読み取りと更新

get_property(name, default) はサブタイプ固有の値を読み取ります; set_property(name, value) はその値を書き込み、プロパティを None に設定すると、アノテーションの properties 辞書から削除されます。

doc = Document()
doc.pages.add()
page = doc.pages[0]

ann = page.annotations.add(
    "Square", (0, 0, 50, 50), "x", properties={"C": [1, 0, 0]},
)
ann.set_property("IC", [0, 0, 1])
print(page.annotations[0].get_property("IC"))  # [0, 0, 1]

ann.set_property("C", None)  # removes the "C" entry entirely
print("C" in page.annotations[0].properties)  # False

AnnotationName を使用したアノテーションの命名

PDF 名（例: Stamp アノテーションの Name エントリ）は、AnnotationName を使用して通常の文字列とは明確に区別されます。これは aspose_pdf.engine.cos の str サブクラスです。このように格納された値は、普通の文字列と等価比較が可能です。

from aspose_pdf.engine.cos import AnnotationName

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add(
    "Stamp", (10, 10, 110, 60), "",
    properties={"Name": AnnotationName("Approved")},
)

挿入、削除、クリア

insert(index, subtype, rect, contents, title, appearance_normal, properties) は特定の位置に新しいアノテーションを配置します; delete(index) はインデックスで1つ削除します（範囲外インデックスの場合は IndexError を送出）; clear() はページ上のすべてのアノテーションを削除します。

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Text", (0, 0, 100, 100), "A")
page.annotations.add("Text", (200, 200, 300, 300), "C")
page.annotations.insert(1, "Text", (100, 100, 200, 200), "B")
# order is now: A, B, C

page.annotations.delete(1)   # removes "B"
page.annotations.clear()     # removes everything remaining

アノテーション外観の生成

Annotation.generate_appearance(force) は1つのアノテーションの /AP /N 外観ストリームを構築し、そのサブタイプのレンダラが存在する場合は True を返します; AnnotationCollection.generate_appearances(force) はページ上のすべてのアノテーションに対して同様の処理を一度に行い、実際に生成されたアノテーション数（サポートされていないサブタイプはスキップされます）を返します。

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Square", (0, 0, 50, 50), "")
page.annotations.add("Circle", (60, 0, 110, 50), "")
page.annotations.add("Text", (0, 60, 20, 80), "")  # unsupported subtype -> skipped

generated = page.annotations.generate_appearances()
print(generated)  # 2

アノテーションのサブタイプとフラグ

AnnotationType は標準 PDF 32000-1:2008（表 169）のサブタイプ名を列挙します: TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, POLY_LINE, HIGHLIGHT, UNDERLINE, SQUIGGLY, STRIKE_OUT, STAMP, CARET, INK, POPUP, FILE_ATTACHMENT, SOUND, MOVIE, WIDGET, SCREEN, PRINTER_MARK, TRAP_NET, WATERMARK, および REDACT。

AnnotationFlags は IntFlag で、アノテーションの表示/操作動作を包括します: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED, および TOGGLE_NO_VIEW。

プレリリース: 3D アノテーション

PDF3DAnnotation、PDF3DArtwork、PDF3DContent、および PDF3DView がページに添付された 3D アートワークをモデル化します — PDF3DAnnotation は rect: Rectangle、artwork: PDF3DArtwork、およびオプションの background_color: Color を持ちます。PDF3DArtwork.add_view() は PDF3DView を登録し、各々が render_mode（PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT）と lighting_scheme（PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM）を保持します。ライブラリ独自の docstring は PDF3DAnnotation を「プレリリースインポート用の最小限アノテーションラッパー」とマークしています — この表面は完全に仕上がった 3D 著者ツール API ではなく、初期段階として扱ってください。

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

• AnnotationType の enum メンバーを、生のサブタイプ文字列よりも優先してください。値をコードの他の場所で比較したり分岐させたりする必要がある場合です。
• set_property(name, None) を呼び出してプロパティを完全に削除し、古い値を残さないようにしてください — エントリは properties から完全に消えます。
• 各アノテーションごとに generate_appearance() をループする代わりに、AnnotationCollection.generate_appearances を使用して外観のバッチ生成を行ってください。生成された実際の数を返すので、スキップされた/サポートされていないサブタイプを検出できます。
• delete() と page.annotations へのインデックスはどちらも 0 基準です。ユーザー入力から取得したインデックスを delete() に渡す前に検証してください。範囲外のインデックスは IndexError を発生させます。
• PDF 名の値（例: Stamp の Name）を AnnotationName でラップして、プレーンテキスト文字列ではなく PDF 名として往復できるようにしてください。

一般的な問題

FAQ

プレーンテキストのコメント注釈はどうやって追加しますか？

page.annotations.add("Text", (x0, y0, x1, y1), "comment text") を呼び出します。4つの数値のタプルは、ページ上の注釈の矩形を表します。

Annotation、MarkupAnnotation、および LinkAnnotation の違いは何ですか？

Annotation は、ページ上の任意の注釈に対して返されるライブビューです。MarkupAnnotation は、マークアップスタイルのサブタイプ（ハイライト、テキストノート、シェイプ）の基礎であり、LinkAnnotation はリンクスタイルの注釈用に保持されています。両方とも現在、Annotation と同じメソッド/プロパティのインターフェースを提供しています。

注釈全体を削除せずに、単一のプロパティだけを削除できますか？

はい — annotation.set_property(name, None) を呼び出してください；注釈自体は変更されず、properties からそのエントリだけが削除されます。

サブタイプがサポートされていない場合、AnnotationCollection.generate_appearances は失敗しますか？

いいえ。組み込みの外観レンダラーがないサブタイプはスキップし、実際に外観を生成したアノテーションの数を返します。

3D アノテーションクラスは本番環境で使用できる状態ですか？

PDF3DAnnotation と関連タイプはプレリリースインポート用の最小ラッパーとして文書化されています — 本番環境の 3D コンテンツで使用する前に、対象の PDF ビューアで動作を確認してください。

API Reference の概要

参照

• Aspose.PDF for Python — Enterprise Documentation