PDF anotace

PDF anotace

Page.annotations poskytuje AnnotationCollection — mutovatelný, sekvenčně podobný pohled na každou anotaci na stránce. Každá položka je Annotation (nebo podtřídy MarkupAnnotation / LinkAnnotation), a data specifická pro podtyp, jako jsou quad body, seznamy inkoustu nebo barvy, se čtou a zapisují přes get_property() / set_property() místo dedikovaných atributů.

Přidávání anotací

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) vytvoří novou anotaci a připojí ji ke stránce. subtype přijímá buď prostý řetězec ("Text", "Square", "Highlight") nebo člena výčtu 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]},
)

Čtení a aktualizace vlastností

get_property(name, default) načte hodnotu specifickou pro podtyp; set_property(name, value) ji zapíše a nastavení vlastnosti na None ji odstraní ze slovníku properties anotace.

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

Pojmenování anotací pomocí AnnotationName

PDF názvy (např. Stamp anotace Name položka) jsou označeny odlišně od prostých řetězců pomocí AnnotationName, podtřídy str z aspose_pdf.engine.cos. Hodnota uložená tímto způsobem je stále rovna běžnému řetězci.

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

Vkládání, odstraňování a vymazání

insert(index, subtype, rect, contents, title, appearance_normal, properties) umístí novou anotaci na konkrétní pozici; delete(index) odstraní jednu podle indexu (vyvolá IndexError při indexu mimo rozsah); clear() odstraní všechny anotace ze stránky.

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

Generování vzhledu anotací

Annotation.generate_appearance(force) vytvoří proud vzhledu /AP /N pro jednu anotaci a vrátí True, pokud existuje vykreslovač pro tento podtyp; AnnotationCollection.generate_appearances(force) provede totéž pro každou anotaci na stránce v jednom volání a vrátí počet anotací, které byly skutečně vygenerovány (nepodporované podtypy jsou přeskočeny).

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

Podtypy anotací a příznaky

AnnotationType vyjmenovává standardní názvy podtypů PDF 32000-1:2008 (Tabulka 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 a REDACT.

AnnotationFlags je IntFlag pokrývající chování zobrazení/interakce anotací: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED a TOGGLE_NO_VIEW.

Předverze: 3D anotace

PDF3DAnnotation, PDF3DArtwork, PDF3DContent a PDF3DView modelují 3D umělecká díla připojená k stránce — PDF3DAnnotation má rect: Rectangle, artwork: PDF3DArtwork a volitelný background_color: Color. PDF3DArtwork.add_view() registruje PDF3DView, z nichž každý nese render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) a lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). Docstring knihovny označuje PDF3DAnnotation jako „minimální obal anotace pro předverze importů“ — považujte tento povrch za ranou fázi spíše než za plně vypracovaný 3D autorizační API.

Tipy a osvědčené postupy

• Upřednostňujte členy výčtu AnnotationType před surovými řetězci podtypů, pokud je hodnota také potřeba porovnávat nebo rozvětvovat jinde ve vašem kódu.
• Zavolejte set_property(name, None) k úplnému odstranění vlastnosti místo ponechání zastaralé hodnoty — položka zmizí z properties úplně.
• Generujte vzhled hromadně pomocí AnnotationCollection.generate_appearances místo iterování generate_appearance() pro každou anotaci; vrací skutečný počet vygenerovaných položek, takže můžete detekovat vynechané/nepodporované podtypy.
• delete() a indexování do page.annotations jsou oba založeny na nule; ověřte index před voláním delete(), pokud pochází od uživatele, protože index mimo rozsah vyvolá IndexError.
• Zabalte hodnoty názvů PDF (např. Stamp’s Name) do AnnotationName, aby se přenášely jako názvy PDF místo prostých textových řetězců.

Časté problémy

FAQ

Jak přidám anotaci s prostým textovým komentářem?

Zavolejte page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Čtyřčlenný n-tuple je obdélník anotace na stránce.

Jaký je rozdíl mezi Annotation, MarkupAnnotation a LinkAnnotation?

Annotation je živý pohled vrácený pro jakoukoli anotaci na stránce. MarkupAnnotation je základ pro podtypy typu markup (zvýraznění, textové poznámky, tvary) a LinkAnnotation se používá pro anotace typu odkaz; oba v současnosti poskytují stejný soubor metod/vlastností jako Annotation.

Mohu odstranit jedinou vlastnost, aniž bych smazal celou anotaci?

Ano — zavolejte annotation.set_property(name, None); samotná anotace zůstane nedotčena, pouze tento jeden záznam je odstraněn z properties.

Selže AnnotationCollection.generate_appearances, pokud podtyp není podporován?

Ne. Přeskočí podtypy bez vestavěného vykreslovatele vzhledu a vrátí počet anotací, pro které skutečně vytvořil vzhled.

Jsou třídy 3D anotací připravené pro produkci?

PDF3DAnnotation a související typy jsou dokumentovány jako minimální obal pro předběžné importy — ověřte jejich chování v cílovém PDF prohlížeči, než na ně budete spoléhat při produkčním 3D obsahu.

API Reference Shrnutí

Viz také:

• Aspose.PDF for Python — Enterprise Documentation