PDF-Anmerkungen

PDF-Anmerkungen

Page.annotations stellt ein AnnotationCollection bereit — eine veränderbare, sequenzähnliche Ansicht über jede Anmerkung auf einer Seite. Jeder Eintrag ist ein Annotation (oder die Unterklassen MarkupAnnotation / LinkAnnotation), und typ-spezifische Daten wie Quad-Punkte, Tintenlisten oder Farben werden über get_property() / set_property() gelesen und geschrieben, anstatt über dedizierte Attribute.

Hinzufügen von Anmerkungen

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) erstellt eine neue Anmerkung und fügt sie der Seite hinzu. subtype akzeptiert entweder einen einfachen String ("Text", "Square", "Highlight") oder ein AnnotationType Enum-Mitglied.

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]},
)

Lesen und Aktualisieren von Eigenschaften

get_property(name, default) liest einen typ-spezifischen Wert; set_property(name, value) schreibt einen, und das Setzen einer Eigenschaft auf None entfernt sie aus dem properties-Dict der Anmerkung.

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

Benennen von Anmerkungen mit AnnotationName

PDF-Namen (z.B. ein Stamp-Annotationseintrag Name) werden deutlich von einfachen Zeichenketten unterschieden, indem AnnotationName verwendet wird, eine str Unterklasse von aspose_pdf.engine.cos. Ein auf diese Weise gespeicherter Wert ist weiterhin gleichwertig zu einer normalen Zeichenkette.

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")},
)

Einfügen, Löschen und Leeren

insert(index, subtype, rect, contents, title, appearance_normal, properties) legt eine neue Annotation an einer bestimmten Position ab; delete(index) entfernt eine nach Index (wirft IndexError bei einem Index außerhalb des Bereichs); clear() entfernt alle Annotationen von der Seite.

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

Erzeugen von Annotationsdarstellungen

Annotation.generate_appearance(force) erstellt den /AP /N-Darstellungsstream für eine Annotation und gibt True zurück, wenn ein Renderer für diesen Subtyp existiert; AnnotationCollection.generate_appearances(force) erledigt dasselbe für jede Annotation auf der Seite in einem Aufruf und gibt die Anzahl der tatsächlich erzeugten Annotationen zurück (nicht unterstützte Subtypen werden übersprungen).

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

Annotation-Subtypen und Flags

AnnotationType listet die standardmäßigen PDF 32000-1:2008 (Tabelle169) Subtypnamen auf: 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 und REDACT.

AnnotationFlags ist ein IntFlag, das das Anzeige-/Interaktionsverhalten von Annotationen abdeckt: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED und TOGGLE_NO_VIEW.

Vorabversion: 3D-Anmerkungen

PDF3DAnnotation, PDF3DArtwork, PDF3DContent und PDF3DView modellieren 3D-Grafiken, die an einer Seite angehängt sind — ein PDF3DAnnotation hat ein rect: Rectangle, ein artwork: PDF3DArtwork und ein optionales background_color: Color. PDF3DArtwork.add_view() registriert ein PDF3DView, das jeweils ein render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) und ein lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM) enthält. Der Docstring der Bibliothek kennzeichnet PDF3DAnnotation als „minimaler Anmerkungs-Wrapper für Vorabversions-Imports“ — betrachte diese Oberfläche als frühes Stadium und nicht als vollständig ausgearbeitete 3D authoring API.

Tipps und bewährte Vorgehensweisen

• Bevorzuge AnnotationType-Enum-Mitglieder gegenüber rohen Subtyp-Strings, wenn der Wert auch an anderer Stelle in deinem Code verglichen oder verzweigt werden muss.
• Rufe set_property(name, None) auf, um eine Eigenschaft vollständig zu entfernen, anstatt einen veralteten Wert zu belassen — der Eintrag verschwindet vollständig aus properties.
• Erstelle das Erscheinungsbild stapelweise mit AnnotationCollection.generate_appearances anstelle einer Schleife über generate_appearance() pro Anmerkung; sie gibt die tatsächlich erzeugte Anzahl zurück, sodass du übersprungene/ nicht unterstützte Subtypen erkennen kannst.
• delete() und das Indexieren in page.annotations sind beide nullbasiert; prüfe einen Index, bevor du delete() aufrufst, wenn er aus Benutzereingaben stammt, da ein Index außerhalb des Bereichs IndexError auslöst.
• Wickle PDF-Namenswerte (wie das Name eines Stamp) in AnnotationName, damit sie als PDF-Namen und nicht als einfache Textzeichenketten round-tripen.

Häufige Probleme

FAQ

Wie füge ich eine reine Textkommentar-Annotation hinzu?

Rufen Sie page.annotations.add("Text", (x0, y0, x1, y1), "comment text") auf. Das Vierzahl-Tupel ist das Rechteck der Annotation auf der Seite.

Was ist der Unterschied zwischen Annotation, MarkupAnnotation und LinkAnnotation?

Annotation ist die Live-Ansicht, die für jede Annotation auf einer Seite zurückgegeben wird. MarkupAnnotation ist die Basis für Markup-artige Subtypen (Markierungen, Textnotizen, Formen) und LinkAnnotation wird für Link-artige Annotationen beibehalten; beide stellen derzeit dieselbe Methoden-/Eigenschaftsoberfläche wie Annotation bereit.

Kann ich eine einzelne Eigenschaft entfernen, ohne die gesamte Annotation zu löschen?

Ja — rufen Sie annotation.set_property(name, None) auf; die Annotation selbst bleibt unverändert, nur dieser ein Eintrag wird aus properties entfernt.

Scheitert AnnotationCollection.generate_appearances, wenn ein Subtyp nicht unterstützt wird?

Nein. Es überspringt Subtypen ohne integrierten appearance renderer und gibt die Anzahl der Annotationen zurück, für die tatsächlich ein appearance erzeugt wurde.

Sind die 3D-Annotation-Klassen produktionsreif?

PDF3DAnnotation und verwandte Typen sind als minimaler Wrapper für Vorabveröffentlichungs-Imports dokumentiert — prüfen Sie das Verhalten mit Ihrem Ziel-PDF-Viewer, bevor Sie sich für den Einsatz in produktiven 3D-Inhalten darauf verlassen.

API Reference Zusammenfassung

Siehe auch

• Aspose.PDF for Python — Enterprise Documentation