So arbeiten Sie mit PDF-Anmerkungen in Python

Aspose.PDF FOSS für Python stellt jede Anmerkung auf einer Seite als ein lebendes Annotation-Objekt über das AnnotationCollection der Seite bereit, sodass Sie Markup-, Link- und 3D-Anmerkungen hinzufügen, deren typenspezifische Eigenschaften prüfen und die Appearance-Streams erzeugen können, die PDF-Viewer zum Rendern benötigen – alles aus reinem Python. Dieser Leitfaden zeigt, wie man die Bibliothek installiert, Anmerkungen hinzufügt, sie wieder ausliest und ihre Appearance-Streams erzeugt.

Schritt-für-Schritt-Anleitung

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

import aspose_pdf
print("aspose_pdf OK")

from aspose_pdf import Document
from aspose_pdf.annotations import (
    Annotation,
    AnnotationType,
    AnnotationFlags,
    MarkupAnnotation,
    LinkAnnotation,
)

from aspose_pdf import Document

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

annotation = page.annotations.add(
    "Highlight",
    (100, 700, 300, 720),
    "Key clause",
)
print(type(annotation).__name__)   # MarkupAnnotation
print(annotation.contents)         # Key clause

from aspose_pdf import Document
from aspose_pdf.annotations import AnnotationType

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

annotation = page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)
print(annotation.subtype)                    # Polygon
print(annotation.get_property("Vertices"))   # [0, 0, 10, 0, 5, 10]

from aspose_pdf import Document

document = Document()
document.pages.add()
page = document.pages[0]
page.annotations.add("Text", (50, 50, 70, 70), "First note")
page.annotations.add("Text", (80, 80, 100, 100), "Second note")

for annotation in page.annotations:
    print(annotation.subtype, "-", annotation.contents)

from aspose_pdf import Document
from aspose_pdf.engine.cos import AnnotationName

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

stamp = page.annotations.add(
    "Stamp",
    (100, 100, 260, 150),
    "",
    properties={"Name": AnnotationName("Approved")},
)
if stamp.generate_appearance():
    print(f"Appearance stream: {len(stamp.appearance_normal)} byte(s)")

# Regenerate every missing appearance stream on the page in one call:
count = page.annotations.generate_appearances(force=True)
print(f"Regenerated {count} appearance stream(s)")

from aspose_pdf import Document
from aspose_pdf.annotations import LinkAnnotation, MarkupAnnotation

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

link = page.annotations.add("Link", (50, 750, 200, 770), "")
highlight = page.annotations.add("Highlight", (50, 700, 200, 720), "")

print(isinstance(link, LinkAnnotation))         # True
print(isinstance(highlight, MarkupAnnotation))  # True

Häufige Probleme und Lösungen

get_property returns None für eine Eigenschaft, die ich gerade gesetzt habe

properties-Schlüssel sind exakte, case-sensitive PDF-Feldnamen ("Vertices", "Name" und ähnliche) — ein Tippfehler oder falsche Groß-/Kleinschreibung wird stillschweigend ignoriert, anstatt einen Fehler auszulösen. Übergeben Sie ein default-Argument an get_property(name, default) und prüfen Sie es explizit, während Sie einen neuen Subtyp debuggen.

generate_appearance() returns False

Nicht jede Subtyp- und Eigenschaftskombination kann vom integrierten Generator in einen Appearance-Stream synthetisiert werden. Prüfen Sie has_appearance, bevor Sie annehmen, dass der Aufruf erfolgreich war, und liefern Sie ein vorgerendertes appearance_normal (bytes) direkt auf add() für Subtypen, die der Generator nicht abdeckt.

Unerwartete Annotationsunterklasse nach add()

Der von Ihnen übergebene Subtyp-String (oder AnnotationType-Member) bestimmt die zurückgegebene Klasse: Markup-Subtypen werden als MarkupAnnotation zurückgeliefert, "Link" wird als LinkAnnotation zurückgegeben, und jeder andere erkannte Subtyp wird als die Basis-Annotation zurückgeliefert. Verwenden Sie isinstance() gegenüber MarkupAnnotation/LinkAnnotation, anstatt einen bestimmten Subtyp-String anzunehmen.

AnnotationFlags Werte scheinen die Darstellung nicht zu ändern

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY und ähnliche) ist ein standardmäßiges Python IntFlag-Enum zum Zusammensetzen und Interpretieren der Verhaltensbits einer Annotation mit dem |-Operator — es ist ein Werttyp, keine Eigenschaft, die Annotation.add() automatisch schreibt. Kombinieren Sie die benötigten Flags und übergeben Sie sie über denselben typenspezifischen properties-Mechanismus, der für andere subtyp-spezifische Daten verwendet wird.

Arbeiten mit einer Seite, die noch keine Anmerkungen hat

page.annotations ist immer ein gültiges (möglicherweise leeres) AnnotationCollection — Sie müssen nie auf None prüfen, bevor Sie add() aufrufen, iterieren oder clear() aufrufen.

Häufig gestellte Fragen

Welche Annotationsuntertypen unterstützt Aspose.PDF FOSS für Python?

AnnotationType enumeriert alle 25 Standard-PDF32000-1:2008 Tabelle169 Untertypen, einschließlich TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT und mehr.

Unterstützt diese Bibliothek 3D-Annotationen?

Ja. PDF3DAnnotation, zusammen mit PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, und PDF3DRenderMode, modelliert eine minimale PDF-3D-Annotationsfläche (ein Rechteck, eingebettete Grafik und benannte Ansichten) für Vorab-PDF-3D-Workflows. Siehe die PDF3DAnnotation-Referenz für seinen vollständigen Eigenschaftensatz.

Wie entferne ich eine Annotation von einer Seite?

Rufen Sie page.annotations.delete(index) auf, um eine Annotation nach Position zu entfernen, oder page.annotations.clear(), um alle Annotationen auf der Seite zu entfernen.

Kann ich eine Annotation an einer bestimmten Position einfügen, anstatt sie anzuhängen?

Ja — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties) verwendet dieselben Argumente wie add() plus das Ziel index.

Wie wird die Farbe einer Annotation dargestellt?

Die color-Eigenschaft von Annotation (und deren Unterklassen) ist ein tuple[float, ...], das der Komponentenanzahl des PDF-/C-Eintrags entspricht (leer, wenn die Farbe nicht gesetzt ist) — kein dediziertes Farbe-Objekt.

Siehe auch

• Dokumentenverwaltung (Entwicklerhandbuch)
• Wie man ein Dokument in Python lädt
• Installationsanleitung
• API Reference
• GitHub-Repository
• Aspose.PDF for Python — Enterprise Knowledge Base