PDF-annotációk

PDF annotációk

Page.annotations egy AnnotationCollection-t tesz elérhetővé — egy módosítható, sor-szerű nézetet minden oldal annotációján. Minden bejegyzés egy Annotation (vagy a MarkupAnnotation / LinkAnnotation alosztályok), és az altípus-specifikus adatok, mint például a quad pontok, tintalisták vagy színek, a get_property() / set_property() segítségével olvashatók és írhatók, nem pedig dedikált attribútumokon keresztül.

Annotációk hozzáadása

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) új annotációt hoz létre, és hozzáfűzi az oldalhoz. subtype elfogad egy egyszerű karakterláncot ("Text", "Square", "Highlight") vagy egy AnnotationType enum tagot.

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

Tulajdonságok olvasása és frissítése

get_property(name, default) altípus-specifikus értéket olvas; set_property(name, value) ír egyet, és egy tulajdonság None-ra állítása eltávolítja azt az annotáció properties szótárából.

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

Annotációk elnevezése a AnnotationName használatával

A PDF nevek (pl. egy Stamp annotáció Name bejegyzése) egyértelműen megkülönböztethetők a sima karakterláncoktól a AnnotationName használatával, amely egy str alosztály a aspose_pdf.engine.cos-ból. Az ilyen módon tárolt érték továbbra is egyenlőnek tekinthető egy hagyományos karakterlánccal.

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

Beszúrás, törlés és ürítés

insert(index, subtype, rect, contents, title, appearance_normal, properties) egy új annotációt helyez el egy adott pozícióban; delete(index) egyet eltávolít index alapján (kivételt dob IndexError, ha az index a tartományon kívül van); clear() az oldal összes annotációját eltávolítja.

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

Annotációk megjelenésének generálása

Annotation.generate_appearance(force) felépíti a /AP /N megjelenítési adatfolyamot egy annotációhoz, és True értéket ad vissza, ha létezik renderelő az adott alosztályhoz; AnnotationCollection.generate_appearances(force) ugyanezt teszi minden annotációval az oldalon egy hívásban, és visszaadja a ténylegesen generált annotációk számát (a nem támogatott alosztályok kihagyásra kerülnek).

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

Annotáció alosztályok és jelzők

AnnotationType felsorolja a szabványos PDF 32000-1:2008 (169. táblázat) alosztály neveket: 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, és REDACT.

AnnotationFlags egy IntFlag, amely az annotáció megjelenítésének/kezelésének viselkedését fedi le: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED és TOGGLE_NO_VIEW.

Előzetes kiadás: 3D megjegyzések

PDF3DAnnotation, PDF3DArtwork, PDF3DContent és PDF3DView modellezik a 3D műalkotást, amely egy oldalhoz van csatolva — egy PDF3DAnnotation rendelkezik egy rect: Rectangle, egy artwork: PDF3DArtwork és egy opcionális background_color: Color elemmel. PDF3DArtwork.add_view() regisztrál egy PDF3DView-t, amely mindegyike egy render_mode-t hordoz (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) és egy lighting_scheme-t (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). A könyvtár saját docstringje PDF3DAnnotation-t megjelöli “minimal annotation wrapper for prerelease imports"ként — tekintse ezt a felületet korai szakasznak, nem pedig egy teljesen kidolgozott 3D szerzői API-nak.

Tippek és bevált gyakorlatok

• Részesítsd előnyben a AnnotationType enum tagjait a nyers altípus karakterláncok helyett, ha az értéket a kódban máshol is össze kell hasonlítani vagy elágaztatni kell.
• Hívd meg a set_property(name, None) függvényt, hogy egy tulajdonságot teljesen eltávolíts, ahelyett, hogy elavult értéket hagynál helyben — a bejegyzés teljesen eltűnik a properties-ből.
• Csoportos megjelenés-generálás a AnnotationCollection.generate_appearances segítségével ahelyett, hogy minden megjegyzéshez generate_appearance()-t iterálnál; visszaadja a ténylegesen generált darabszámot, így felismerheted a kihagyott/támogatott nélküli altípusokat.
• delete() és a page.annotations indexelése egyaránt 0-alapú; ellenőrizd az indexet, mielőtt meghívnád a delete()-t, ha felhasználói bemenetről származik, mivel egy tartományon kívüli index IndexError-t vált ki.
• A PDF névértékeket (például egy Stamp Name-jét) csomagold AnnotationName-be, hogy PDF nevekként térjenek vissza, ne pedig egyszerű szöveges karakterláncokként.

Gyakori problémák

FAQ

Hogyan adhatok hozzá egyszerű szöveges megjegyzés-annotációt?

Hívja a page.annotations.add("Text", (x0, y0, x1, y1), "comment text") függvényt. A négy számot tartalmazó tuple az annotáció téglalapja az oldalon.

Mi a különbség a Annotation, MarkupAnnotation és a LinkAnnotation között?

Annotation a dinamikus nézet, amely bármely annotációhoz egy oldalon visszaadódik. MarkupAnnotation a jelölő-stílusú altípusok (kiemelések, szöveges jegyzetek, alakzatok) alapja, és a LinkAnnotation a link-stílusú annotációk számára van fenntartva; mindkettő jelenleg ugyanazt a metódus/tulajdonos felületet biztosítja, mint a Annotation.

Eltávolíthatok egyetlen tulajdonságot anélkül, hogy az egész annotációt törölném?

Igen — hívja a annotation.set_property(name, None) függvényt; az annotáció maga érintetlen marad, csak az az egy bejegyzés kerül eltávolításra a properties-ből.

Meghiúsul a AnnotationCollection.generate_appearances, ha egy altípus nem támogatott?

Nem. Kihagyja azokat az altípusokat, amelyekhez nincs beépített megjelenítő, és visszaadja azoknak az annotációknak a számát, amelyekhez ténylegesen generált megjelenést.

A 3D annotációs osztályok termelésre készek?

PDF3DAnnotation és a kapcsolódó típusok minimális burként vannak dokumentálva a kiadás előtti importokhoz — ellenőrizze a viselkedést a cél PDF-olvasóval, mielőtt termelési 3D tartalomra támaszkodna.

API Reference Összegzés

Lásd még:

• Aspose.PDF for Python — Enterprise Documentation