PDF-annotaties

PDF Annotaties

Page.annotations biedt een AnnotationCollection — een mutabel, sequentie-achtig overzicht van elke annotatie op een pagina. Elk item is een Annotation (of de MarkupAnnotation / LinkAnnotation subklassen), en subtype-specifieke gegevens zoals quad-punten, inktlijsten, of kleuren worden gelezen en geschreven via get_property() / set_property() in plaats van toegewijde attributen.

Annotaties toevoegen

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) maakt een nieuwe annotatie aan en voegt deze toe aan de pagina. subtype accepteert ofwel een eenvoudige string ("Text", "Square", "Highlight") of een AnnotationType enum-lid.

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

Eigenschappen lezen en bijwerken

get_property(name, default) leest een subtype-specifieke waarde; set_property(name, value) schrijft er een, en het instellen van een eigenschap op None verwijdert deze uit het properties-dict van de annotatie.

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

Annotaties benoemen met AnnotationName

PDF-namen (bijv. een Stamp annotatie’s Name invoer) worden duidelijk gemarkeerd van gewone tekenreeksen met behulp van AnnotationName, een str subklasse van aspose_pdf.engine.cos. Een waarde die op deze manier is opgeslagen blijft gelijk aan een gewone tekenreeks.

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

Invoegen, Verwijderen en Wissen

insert(index, subtype, rect, contents, title, appearance_normal, properties) plaatst een nieuwe annotatie op een specifieke positie; delete(index) verwijdert er één op basis van index (werpt IndexError bij een index buiten bereik); clear() verwijdert alle annotaties van de pagina.

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

Genereren van annotatie-weergaven

Annotation.generate_appearance(force) bouwt de /AP /N weergavestroom voor één annotatie en retourneert True wanneer er een renderer voor dat subtype bestaat; AnnotationCollection.generate_appearances(force) doet hetzelfde voor elke annotatie op de pagina in één oproep en retourneert het aantal annotaties dat daadwerkelijk werd gegenereerd (niet-ondersteunde subtypes worden overgeslagen).

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

Annotatie-subtypes en vlaggen

AnnotationType somt de standaard PDF 32000-1:2008 (Tabel 169) subtype-namen op: 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, en REDACT.

AnnotationFlags is een IntFlag die het weergave-/interactieve gedrag van annotaties omvat: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED, en TOGGLE_NO_VIEW.

Pre-release: 3D-annotaties

PDF3DAnnotation, PDF3DArtwork, PDF3DContent en PDF3DView modelleren 3D-kunstwerk dat aan een pagina is gekoppeld — een PDF3DAnnotation heeft een rect: Rectangle, een artwork: PDF3DArtwork, en een optionele background_color: Color. PDF3DArtwork.add_view() registreert een PDF3DView, elk met een render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) en een lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). De docstring van de bibliotheek zelf markeert PDF3DAnnotation als een “minimal annotation wrapper for prerelease imports” — behandel dit oppervlak als vroegstadium in plaats van een volledig uitgewerkte 3D-authoring API.

Tips en best practices

• Geef de voorkeur aan AnnotationType enum-leden boven ruwe subtype-strings wanneer de waarde ook elders in je code moet worden vergeleken of gebruikt voor vertakkingen.
• Roep set_property(name, None) aan om een eigenschap volledig te verwijderen in plaats van een verouderde waarde te laten staan — het item verdwijnt volledig uit properties.
• Genereer op batch-basis verschijningen met AnnotationCollection.generate_appearances in plaats van per annotatie generate_appearance() te loopen; het retourneert het daadwerkelijke aantal gegenereerd zodat je overgeslagen/ondersteunde subtypes kunt detecteren.
• delete() en indexering in page.annotations zijn beide 0-gebaseerd; valideer een index voordat je delete() aanroept als deze afkomstig is van gebruikersinvoer, aangezien een index buiten bereik IndexError veroorzaakt.
• Omhul PDF-naamwaarden (zoals een Stamp’s Name) in AnnotationName zodat ze als PDF-namen worden doorgegeven in plaats van als gewone tekststrings.

Veelvoorkomende problemen

FAQ

Hoe voeg ik een platte-tekst commentaarannotatie toe?

Roep page.annotations.add("Text", (x0, y0, x1, y1), "comment text") aan. De vier-getallen-tuple is de rechthoek van de annotatie op de pagina.

Wat is het verschil tussen Annotation, MarkupAnnotation en LinkAnnotation?

Annotation is de live-view die wordt geretourneerd voor elke annotatie op een pagina. MarkupAnnotation is de basis voor subtypes in mark-up-stijl (highlights, tekstnotities, vormen) en LinkAnnotation wordt bewaard voor link-style annotaties; beiden bieden momenteel hetzelfde methoden-/eigenschappen-oppervlak als Annotation.

Kan ik een enkele eigenschap verwijderen zonder de hele annotatie te verwijderen?

Ja — roep annotation.set_property(name, None) aan; de annotatie zelf blijft onaangetast, alleen die ene vermelding wordt verwijderd uit properties.

Falt AnnotationCollection.generate_appearances als een subtype niet wordt ondersteund?

Nee. Het slaat subtypes over zonder een ingebouwde appearance renderer en retourneert het aantal annotaties waarvoor het daadwerkelijk een appearance heeft gegenereerd.

Zijn de 3D-annotatieklassen gereed voor productie?

PDF3DAnnotation en gerelateerde types worden gedocumenteerd als een minimale wrapper voor prerelease-imports — verifieer het gedrag met uw doel-PDF-viewer voordat u erop vertrouwt voor productie-3D-inhoud.

API Reference Samenvatting

Zie ook

• Aspose.PDF for Python — Enterprise Documentation