Annotazioni PDF

Annotazioni PDF

Page.annotations espone un AnnotationCollection — una vista mutabile, simile a una sequenza, su ogni annotazione di una pagina. Ogni voce è un Annotation (o le sottoclassi MarkupAnnotation / LinkAnnotation), e i dati specifici del sottotipo come i punti quad, le liste di inchiostro o i colori vengono letti e scritti tramite get_property() / set_property() anziché tramite attributi dedicati.

Aggiungere annotazioni

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) crea una nuova annotazione e la aggiunge alla pagina. subtype accetta o una stringa semplice ("Text", "Square", "Highlight") o un membro enum 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]},
)

Lettura e aggiornamento delle proprietà

get_property(name, default) legge un valore specifico del sottotipo; set_property(name, value) ne scrive uno, e impostare una proprietà a None la rimuove dal dizionario properties dell’annotazione.

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

Denominare le annotazioni con AnnotationName

I nomi PDF (ad esempio la voce Name di un’annotazione Stamp) sono contrassegnati in modo distinto dalle stringhe normali usando AnnotationName, una sottoclasse str di aspose_pdf.engine.cos. Un valore memorizzato in questo modo è comunque uguale a una stringa ordinaria.

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

Inserimento, Eliminazione e Pulizia

insert(index, subtype, rect, contents, title, appearance_normal, properties) inserisce una nuova annotazione in una posizione specifica; delete(index) rimuove una per indice (sollevando IndexError per un indice fuori intervallo); clear() rimuove tutte le annotazioni dalla 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

Generazione delle apparenze delle annotazioni

Annotation.generate_appearance(force) costruisce il flusso di aspetto /AP /N per una singola annotazione e restituisce True quando esiste un renderer per quel sottotipo; AnnotationCollection.generate_appearances(force) fa lo stesso per ogni annotazione sulla pagina in una sola chiamata e restituisce il numero di annotazioni effettivamente generate (i sottotipi non supportati vengono ignorati).

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

Sottotipi e flag delle annotazioni

AnnotationType elenca i nomi dei sottotipi standard PDF 32000-1:2008 (Tabella 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, e REDACT.

AnnotationFlags è un IntFlag che copre il comportamento di visualizzazione/interazione delle annotazioni: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED e TOGGLE_NO_VIEW.

Versione preliminare: Annotazioni 3D

PDF3DAnnotation, PDF3DArtwork, PDF3DContent e PDF3DView modellano un’opera d’arte 3D allegata a una pagina — un PDF3DAnnotation ha un rect: Rectangle, un artwork: PDF3DArtwork e un background_color: Color opzionale. PDF3DArtwork.add_view() registra un PDF3DView, ognuno con un render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) e un lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). La docstring della libreria stessa contrassegna PDF3DAnnotation come un “minimal annotation wrapper for prerelease imports” — considera questa superficie come in fase iniziale piuttosto che come un API di authoring 3D completamente sviluppato.

Consigli e migliori pratiche

• Preferisci i membri enum di AnnotationType rispetto alle stringhe di sottotipo grezze quando il valore deve anche essere confrontato o usato per rami altrove nel tuo codice.
• Chiama set_property(name, None) per rimuovere una proprietà del tutto invece di lasciare un valore obsoleto al suo posto — la voce scompare completamente da properties.
• Genera le apparizioni in batch con AnnotationCollection.generate_appearances invece di iterare generate_appearance() per annotazione; restituisce il conteggio effettivo generato così puoi rilevare sottotipi saltati o non supportati.
• delete() e l’indicizzazione in page.annotations sono entrambe basate su zero; valida un indice prima di chiamare delete() se proviene da input dell’utente, poiché un indice fuori intervallo genera IndexError.
• Avvolgi i valori dei nomi PDF (come il Name di un Stamp) in AnnotationName così verranno trattati come nomi PDF anziché come stringhe di testo semplici.

Problemi comuni

FAQ

Come aggiungo un’annotazione di commento in testo semplice?

Chiama page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). La tupla a quattro numeri è il rettangolo dell’annotazione sulla pagina.

Qual è la differenza tra Annotation, MarkupAnnotation e LinkAnnotation?

Annotation è la vista live restituita per qualsiasi annotazione su una pagina. MarkupAnnotation è la base per i sottotipi di tipo markup (evidenziazioni, note di testo, forme) e LinkAnnotation è mantenuto per le annotazioni di tipo link; entrambi attualmente espongono la stessa superficie di metodi/proprietà di Annotation.

Posso rimuovere una singola proprietà senza eliminare l’intera annotazione?

Sì — chiama annotation.set_property(name, None); l’annotazione stessa rimane intatta, solo quella voce viene rimossa da properties.

Il AnnotationCollection.generate_appearances fallisce se un sottotipo non è supportato?

No. Salta i sottotipi senza un renderer di aspetto integrato e restituisce il conteggio delle annotazioni per le quali ha effettivamente generato un aspetto.

Le classi di annotazione 3D sono pronte per la produzione?

PDF3DAnnotation e i tipi correlati sono documentati come un wrapper minimo per importazioni prerelease — verifica il comportamento con il visualizzatore PDF di destinazione prima di fare affidamento su di essi per contenuti 3D di produzione.

API Reference Riepilogo

Vedi anche

• Aspose.PDF for Python — Enterprise Documentation