Cum să lucrați cu adnotări PDF în Python

Aspose.PDF FOSS pentru Python expune fiecare adnotare de pe o pagină ca un obiect Annotation live prin AnnotationCollection paginii, astfel încât puteţi adăuga adnotări de tip markup, link și 3D, inspecta proprietăţile specifice tipului şi genera fluxurile de apariție de care au nevoie vizualizatoarele PDF pentru a le reda — totul din Python pur. Acest ghid arată cum să instalaţi biblioteca, să adăugaţi adnotări, să le citiţi înapoi și să generaţi fluxurile lor de apariție.

Ghid pas cu pas

Pasul 1: Instalaţi pachetul

Instalaţi pachetul FOSS Aspose.PDF:

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

Verificaţi instalarea importând modulul aspose_pdf de nivel superior, care expune clasa Document utilizată în pașii de mai jos. Fragmentul afișează aspose_pdf OK când importul reuşeşte; un ModuleNotFoundError de obicei înseamnă că pachetul a fost instalat într-un mediu Python diferit de cel în care rulează scriptul dumneavoastră:

import aspose_pdf
print("aspose_pdf OK")

Pasul 2: Importă clasele necesare

Importă Document pentru a păstra PDF-ul, plus clasele de adnotare pe care le vei folosi pentru a crea și inspecta adnotări:

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

Pasul 3: Adaugă o adnotare la o pagină

Fiecare Page își expune adnotările prin proprietatea annotations, un AnnotationCollection. Apelează add(subtype, rect, contents) cu un nume de subtip, un dreptunghi (left, bottom, right, top) și conținutul text al adnotării. Subtipurile standard de markup, cum ar fi "Highlight", sunt returnate ca o instanță MarkupAnnotation:

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

Pasul 4: Creează adnotări din subtipuri enum

AnnotationType enumeră fiecare subtip standard de adnotare PDF (PDF 32000-1:2008, Tabelul 169), astfel încât poți furniza un membru enum în loc de un șir brut. Datele specifice tipului — cum ar fi vârfurile unui poligon — se pun în dicționarul properties și sunt citite înapoi cu get_property:

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]

Pasul 5: Citește și iterează prin adnotările existente

AnnotationCollection este iterabil, astfel încât poți parcurge fiecare adnotare deja existentă pe o pagină — inclusiv cele încărcate dintr-un PDF existent — și poți citi proprietățile comune pe care le expune fiecare Annotation (subtype, contents, rect, title, author, color):

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)

Pasul 6: Generați fluxuri de aspect ale adnotărilor

O adnotare creată fără un appearance_normal explicit nu are o redare vizibilă (/AP /N) până când una este generată. Apelați generate_appearance(force) pe un singur Annotation, sau generate_appearances(force) pe întregul AnnotationCollection pentru a sintetiza fiecare flux de aspect lipsă pe pagină simultan:

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

Pasul 7: Distingeți subclasele adnotărilor

AnnotationCollection.add() trimite către o subclasă specifică în funcție de subtip: subtipurile de tip marcaj (Highlight, Square, Stamp și altele) revin ca MarkupAnnotation, iar "Link" revine ca LinkAnnotation. Ambele moștenesc fiecare metodă și proprietate de la Annotation, astfel încât verificările isinstance vă permit să ramificați pe tipul adnotării fără a inspecta direct șirurile subtype:

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

Probleme comune și remedieri

get_property returns None pentru o proprietate pe care tocmai am setat-o

properties cheile sunt nume exacte, sensibile la majuscule ale câmpurilor PDF ("Vertices", "Name" și altele) — o greșeală de tastare sau o majusculă greșită este ignorată silențios în loc să declanșeze o eroare. Transmiteți un argument default către get_property(name, default) și verificați-l explicit în timpul depanării unui nou subtip.

generate_appearance() returns False

Nu fiecare combinație de subtip și proprietate poate fi sintetizată într-un flux de aspect de către generatorul încorporat. Verificați has_appearance înainte de a presupune că apelul a reușit și furnizați un appearance_normal pre-redat (bytes) direct pe add() pentru subtipurile pe care generatorul nu le acoperă.

Subclasă de adnotare neașteptată după add()

Șirul subtipului (sau membrul AnnotationType) pe care îl furnizați determină clasa returnată: subtipurile de markup revin ca MarkupAnnotation, "Link" revine ca LinkAnnotation, iar orice alt subtip recunoscut revine ca Annotation de bază. Utilizați isinstance() împotriva MarkupAnnotation/LinkAnnotation în loc să presupuneți un șir de subtip specific.

AnnotationFlags valorile par să nu schimbe randarea

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY și altele) este un enum standard Python IntFlag pentru compunerea și interpretarea biților de comportament ai unei adnotări cu operatorul | — este un tip de valoare, nu o proprietate pe care Annotation.add() o scrie automat. Combinați steagurile de care aveți nevoie și transmiteți-le prin același mecanism properties specific tipului, utilizat pentru alte date specifice subtipului.

Lucrul cu o pagină care încă nu are adnotări

page.annotations este întotdeauna un AnnotationCollection valid (posibil gol) — nu trebuie niciodată să verificați None înainte de a apela add(), de a itera sau de a apela clear().

Întrebări frecvente

Ce subtipuri de adnotări suportă Aspose.PDF FOSS pentru Python?

AnnotationType enumeră toate cele 25 de subtipuri standard PDF 32000-1:2008 Tabelul 169, inclusiv TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT și altele.

Această bibliotecă suportă adnotări 3D?

Da. PDF3DAnnotation, împreună cu PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, și PDF3DRenderMode, modelează o suprafață minimală de adnotare PDF 3D (un dreptunghi, artă încorporată și vizualizări numite) pentru fluxuri de lucru PDF 3D prerelease. Vezi referința PDF3DAnnotation pentru setul său complet de proprietăţi.

Cum elimin o adnotare de pe o pagină?

Apelați page.annotations.delete(index) pentru a elimina o adnotare prin poziție sau page.annotations.clear() pentru a elimina toate adnotările de pe pagină.

Pot insera o adnotare la o poziție specifică în loc să o adaug la sfârșit?

Da — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties) primește aceleași argumente ca add() plus ținta index.

Cum este reprezentată culoarea unei adnotări?

Proprietatea color pe Annotation (și subclasele sale) este un tuple[float, ...] care corespunde numărului de componente al intrării PDF /C (golă când culoarea nu este setată) — nu un obiect de culoare dedicat.