Anotări PDF

Anotări PDF

Page.annotations expune un AnnotationCollection — o vizualizare mutabilă, asemănătoare unui șir, asupra fiecărei adnotări de pe o pagină. Fiecare intrare este un Annotation (sau subclasele MarkupAnnotation / LinkAnnotation), iar datele specifice tipului, cum ar fi punctele quad, listele de cerneală sau culorile, sunt citite și scrise prin get_property() / set_property() în loc de atribute dedicate.

Adăugarea adnotărilor

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) creează o nouă adnotare și o adaugă la pagină. subtype acceptă fie un șir simplu ("Text", "Square", "Highlight") fie un membru 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]},
)

Citirea și actualizarea proprietăților

get_property(name, default) citește o valoare specifică subtipului; set_property(name, value) scrie una, iar setarea unei proprietăți la None o elimină din dicționarul properties al adnotării.

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

Denominarea adnotărilor cu AnnotationName

Numele PDF (de ex. intrarea Name a unei adnotări Stamp) sunt marcate distinct de șirurile obișnuite utilizând AnnotationName, o subclasă str din aspose_pdf.engine.cos. O valoare stocată în acest fel se compară în continuare egal cu un șir obișnuit.

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

Inserare, ștergere și golire

insert(index, subtype, rect, contents, title, appearance_normal, properties) plasează o nouă adnotare la o poziție specifică; delete(index) elimină una prin indice (generând IndexError pentru un indice în afara intervalului); clear() elimină toate adnotările de pe pagină.

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

Generarea aspectelor adnotărilor

Annotation.generate_appearance(force) construiește fluxul de aspect /AP /N pentru o singură adnotare și returnează True când există un renderer pentru acel subtip; AnnotationCollection.generate_appearances(force) face același lucru pentru fiecare adnotare de pe pagină într-un singur apel și returnează numărul de adnotări care au fost generate efectiv (subtipurile nesuportate sunt sărite).

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

Subtipuri de adnotări și steaguri

AnnotationType enumeră numele standard ale subtipurilor PDF 32000-1:2008 (Tabelul 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 și REDACT.

AnnotationFlags este un IntFlag care acoperă comportamentul de afișare/interacțiune al adnotărilor: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED și TOGGLE_NO_VIEW.

Prelansare: 3D Anotări

PDF3DAnnotation, PDF3DArtwork, PDF3DContent și PDF3DView modelează lucrări 3D atașate unei pagini — un PDF3DAnnotation are un rect: Rectangle, un artwork: PDF3DArtwork și un background_color: Color opțional. PDF3DArtwork.add_view() înregistrează un PDF3DView, fiecare având un render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) și un lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). Docstring-ul propriu al bibliotecii marchează PDF3DAnnotation ca un „împachet minimal de adnotare pentru importuri în pre-lansare” — tratează această suprafață ca fiind în stadiu incipient, nu ca un API de authoring 3D complet realizat.

Sfaturi și cele mai bune practici

• Preferă membrii enum AnnotationType în loc de șiruri brute de subtipuri când valoarea trebuie, de asemenea, comparată sau utilizată în ramificări în altă parte a codului tău.
• Apelă set_property(name, None) pentru a elimina complet o proprietate în loc să lași o valoare învechită în loc — intrarea dispare complet din properties.
• Generează în lot aspectele cu AnnotationCollection.generate_appearances în loc să iterezi generate_appearance() pentru fiecare adnotare; aceasta returnează numărul real generat, astfel încât să poți detecta subtipurile sărite/nesuportate.
• delete() și indexarea în page.annotations sunt ambele bazate pe 0; validează un index înainte de a apela delete() dacă provine din intrarea utilizatorului, deoarece un index în afara intervalului declanșează IndexError.
• Înfășoară valorile de nume PDF (cum ar fi Stamp’s Name) în AnnotationName pentru ca acestea să fie transportate ca nume PDF și nu ca șiruri de text simple.

Probleme comune

FAQ

Cum adaug o adnotare de comentariu în text simplu?

Apelă page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Tupla de patru numere este dreptunghiul adnotării pe pagină.

Care este diferența dintre Annotation, MarkupAnnotation și LinkAnnotation?

Annotation este vizualizarea în timp real returnată pentru orice adnotare pe o pagină. MarkupAnnotation este baza pentru subtipurile de tip markup (evidențieri, note text, forme) și LinkAnnotation este păstrat pentru adnotările de tip link; ambele expun în prezent aceeași suprafață de metodă/proprietate ca Annotation.

Pot elimina o singură proprietate fără a șterge întreaga adnotare?

Da — apelă annotation.set_property(name, None); adnotarea în sine rămâne neschimbată, doar acea intrare este eliminată din properties.

Eșuează AnnotationCollection.generate_appearances dacă un subtip nu este suportat?

Nu. Omite subtipurile fără un renderer de aspect încorporat și returnează numărul de adnotări pentru care a generat efectiv un aspect.

Sunt clasele de adnotare 3D pregătite pentru producție?

PDF3DAnnotation și tipurile aferente sunt documentate ca un înveliș minimal pentru importuri prerelease — verificați comportamentul în raport cu vizualizatorul PDF țintă înainte de a vă baza pe ele pentru conținut 3D de producție.

Rezumat API Reference

Vezi și:

• Aspose.PDF for Python — Enterprise Documentation