Hogyan dolgozzunk PDF-annotációkkal a Python környezetben

Aspose.PDF FOSS for Python minden oldal annotációját élő Annotation objektumként teszi elérhetővé az oldal AnnotationCollection segítségével, így hozzáadhatsz megjelöléseket, hivatkozásokat és 3D annotációkat, megvizsgálhatod típusspecifikus tulajdonságaikat, és előállíthatod azokat a megjelenési adatfolyamokat, amelyekre a PDF-nézőknek szükségük van a megjelenítéshez — mindezt tiszta Python-ből. Ez az útmutató bemutatja, hogyan telepítsd a könyvtárat, hogyan adj hozzá annotációkat, hogyan olvasd vissza őket, és hogyan generáld a megjelenési adatfolyamokat.

Lépésről lépésre útmutató

1. lépés: A csomag telepítése

Telepítsd a Aspose.PDF FOSS csomagot:

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

Ellenőrizd a telepítést a legfelső szintű aspose_pdf modul importálásával, amely elérhetővé teszi az alábbi lépésekben használt Document osztályt. A kódrészlet aspose_pdf OK értéket ír ki, ha az import sikeres; egy ModuleNotFoundError általában azt jelenti, hogy a csomagot egy másik Python környezetbe telepítették, mint amelyik a scriptedet futtatja:

import aspose_pdf
print("aspose_pdf OK")

2. lépés: A szükséges osztályok importálása

Importálja a Document elemet a PDF tárolásához, valamint az annotációs osztályokat, amelyeket az annotációk létrehozásához és vizsgálatához használni fog:

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

3. lépés: Annotáció hozzáadása egy oldalhoz

Minden Page a annotations tulajdonságán keresztül teszi elérhetővé az annotációit, ami egy AnnotationCollection. Hívja meg a add(subtype, rect, contents) függvényt egy al-típus névvel, egy (left, bottom, right, top) téglalappal és az annotáció szövegtartalmával. A szabványos jelölő al-típusok, például a "Highlight", egy MarkupAnnotation példányként kerülnek visszaadva:

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

4. lépés: Annotációk létrehozása enum al-típusokból

AnnotationType felsorolja az összes szabványos PDF annotáció al-típusát (PDF 32000-1:2008, 169. táblázat), így átadhat egy enum tagot nyers karakterlánc helyett. Típus-specifikus adatok — például egy sokszög csúcspontjai — a properties szótárban szerepelnek, és a get_property segítségével olvashatók vissza:

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]

5. lépés: Létező annotációk olvasása és iterálása

AnnotationCollection iterálható, így végigjárhatja az oldalon már meglévő minden annotációt – beleértve a meglévő PDF-ből betöltötteket is – és elolvashatja az összes közös tulajdonságot, amelyet minden Annotation nyújt (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)

6. lépés: Anotáció megjelenési adatfolyamok generálása

Az explicit appearance_normal nélküli annotáció nem rendelkezik látható megjelenítéssel (/AP /N), amíg az nem kerül generálásra. Hívja a generate_appearance(force) egyetlen Annotation esetén, vagy a generate_appearances(force) az egész AnnotationCollection esetén, hogy egyszerre szintetizálja az összes hiányzó megjelenési adatfolyamot az oldalon:

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

7. lépés: Anotáció alosztályok megkülönböztetése

AnnotationCollection.add() a típusa alapján egy konkrét alosztályra irányít: a markup-stílusú altípusok (Highlight, Square, Stamp és hasonlóak) MarkupAnnotation formában térnek vissza, míg a "Link" LinkAnnotation formában. Mindkettő örökli az összes metódust és tulajdonságot a Annotation-től, ezért a isinstance ellenőrzések lehetővé teszik, hogy az annotáció típusát ágaztatás nélkül vizsgálja, anélkül, hogy közvetlenül a subtype karakterláncokat ellenőrizné.

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

Gyakori problémák és megoldások

get_property returns None egy tulajdonsághoz, amit most állítottam be

properties kulcsok pontos, kis- és nagybetű érzékeny PDF mezőnevek ("Vertices", "Name" és hasonlóak) — egy elütés vagy helytelen nagybetűs írás csendben figyelmen kívül marad, ahelyett, hogy hibát dobna. Adj át egy default argumentumot a get_property(name, default)-nek, és ellenőrizd explicit módon a hibakeresés során egy új altípusnál.

generate_appearance() returns False

Nem minden altípus- és tulajdonság-kombináció szintetizálható megjelenítési adatfolyammá a beépített generátor által. Ellenőrizze a has_appearance-t, mielőtt feltételezné, hogy a hívás sikeres volt, és adjon meg egy előre renderelt appearance_normal (bytes) közvetlenül a add()-on azoknál az altípusoknál, amelyeket a generátor nem fed le.

Váratlan annotáció alosztály után add()

Az Ön által megadott altípus karakterlánc (vagy AnnotationType tag) meghatározza a visszaadott osztályt: a markup altípusok MarkupAnnotation-ként érkeznek vissza, a "Link" LinkAnnotation-ként érkezik vissza, és minden más felismert altípus a bázis Annotation-ként érkezik vissza. Inkább használja a isinstance()-t a MarkupAnnotation/LinkAnnotation ellen, ahelyett, hogy egy konkrét altípus karakterláncot feltételezne.

AnnotationFlags az értékek nem változtatják a renderelést

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY, és hasonló) egy szabványos Python IntFlag felsorolt típus, amely az annotáció viselkedési bitek összerakására és értelmezésére szolgál a | operátorral — ez egy értéktípus, nem egy tulajdonság, amelyet a Annotation.add() automatikusan ír. Kombinálja a szükséges zászlókat, és adja át őket ugyanazon a típus-specifikus properties mechanizmuson keresztül, amelyet más altípus-specifikus adatoknál használ.

Munkavégzés egy olyan oldalon, amely még nem tartalmaz annotációkat

page.annotations mindig egy érvényes (esetleg üres) AnnotationCollection — soha nem kell ellenőrizni a None létezését, mielőtt meghívná a add()-t, iterálna, vagy meghívná a clear()-t.

Gyakran Ismételt Kérdések

Milyen annotáció alaptípusokat támogat a Aspose.PDF FOSS a Python számára?

AnnotationType felsorolja a PDF 32000-1:2008 169. táblázatában szereplő összes 25 szabványos alaptípust, többek között TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT és továbbiakat.

Támogatja-e ez a könyvtár a 3D annotációkat?

Igen. PDF3DAnnotation, együtt PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, és PDF3DRenderMode, egy minimális PDF 3D annotációs felületet (téglalap, beágyazott műalkotás és elnevezett nézetek) modellez a kiadás előtti PDF 3D munkafolyamatokhoz. Lásd a PDF3DAnnotation hivatkozás az összes tulajdonság teljes halmazához.

Hogyan távolíthatok el egy annotációt egy oldalról?

Hívja a page.annotations.delete(index) függvényt egy pozíció szerinti annotáció eltávolításához, vagy a page.annotations.clear() függvényt az oldal összes annotációjának eltávolításához.

Beszúrhatok-e egy annotációt egy adott pozícióba ahelyett, hogy a végére tenném?

Igen — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties) ugyanazokat az argumentumokat veszi, mint a add(), plusz a cél index.

Hogyan van ábrázolva egy annotáció színe?

A color tulajdonság a Annotation (és annak alosztályai) esetén egy tuple[float, ...], amely megfelel a PDF /C bejegyzés komponensszámának (üres, ha a szín nincs beállítva) — nem egy dedikált színobjektum.