Jak pracovat s PDF anotacemi v Python

Aspose.PDF FOSS pro Python vystavuje každou anotaci na stránce jako živý objekt Annotation prostřednictvím AnnotationCollection stránky, takže můžete přidávat značky, odkazy a 3D anotace, prozkoumávat jejich vlastnosti specifické pro typ a generovat proudy vzhledu, které PDF prohlížeče potřebují k jejich vykreslení — vše z čistého Python. Tento průvodce ukazuje, jak nainstalovat knihovnu, přidat anotace, načíst je zpět a vygenerovat jejich proudy vzhledu.

Postupný návod

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

import aspose_pdf
print("aspose_pdf OK")

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

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

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]

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)

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

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

Časté problémy a opravy

get_property returns None pro vlastnost, kterou jsem právě nastavil

properties klíče jsou přesné, rozlišující velikost písmen názvy polí PDF ("Vertices", "Name" a podobné) — překlep nebo špatná velikost písmen je tiše ignorována místo vyvolání chyby. Předávejte argument default funkci get_property(name, default) a kontrolujte jej explicitně při ladění nového podtypu.

generate_appearance() returns False

Ne každá kombinace podtypu a vlastnosti může být vygenerována do proudu vzhledu vestavěným generátorem. Zkontrolujte has_appearance před tím, než předpokládáte úspěšnost volání, a pro podtypy, které generátor nepokrývá, poskytněte předem vykreslený appearance_normal (bytes) přímo na add().

Neočekávaná podtřída anotace po add()

Řetězec podtypu (nebo člen AnnotationType), který předáte, určuje vrácenou třídu: podtypy značek se vrací jako MarkupAnnotation, "Link" se vrací jako LinkAnnotation a jakýkoli jiný rozpoznaný podtyp se vrací jako základní Annotation. Použijte isinstance() proti MarkupAnnotation/LinkAnnotation místo předpokládání konkrétního řetězce podtypu.

AnnotationFlags hodnoty se nezdají měnit renderování

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY a podobně) je standardní Python IntFlag výčtový typ pro skládání a interpretaci bitů chování anotace pomocí operátoru |—jedná se o typ hodnoty, nikoli o vlastnost, kterou Annotation.add() zapisuje automaticky. Kombinujte potřebné příznaky a předávejte je prostřednictvím stejného typově specifického mechanismu properties, který se používá pro další data specifická pro podtyp.

Práce se stránkou, která zatím nemá žádné anotace

page.annotations je vždy platný (případně prázdný) AnnotationCollection—nikdy nemusíte kontrolovat None před voláním add(), iterací nebo voláním clear().

Často kladené otázky

Jaké podtypy anotací podporuje Aspose.PDF FOSS pro Python?

AnnotationType vyjmenovává všech 25 standardních podtypů PDF 32000-1:2008 Tabulka 169, včetně TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT a dalších.

Podporuje tato knihovna 3D anotace?

Ano. PDF3DAnnotation, spolu s PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, a PDF3DRenderMode, modeluje minimální PDF3D anotaci povrchu (obdélník, vložené umělecké dílo a pojmenované pohledy) pro předverzní PDF3D pracovní toky. Viz reference PDF3DAnnotation pro jeho kompletní sadu vlastností.

Jak odebrat anotaci ze stránky?

Voláním page.annotations.delete(index) odeberete jednu anotaci podle pozice, nebo page.annotations.clear() odeberete všechny anotace na stránce.

Mohu vložit anotaci na konkrétní pozici místo jejího připojení?

Ano — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties) přijímá stejné argumenty jako add() plus cílový index.

Jak je barva anotace reprezentována?

Vlastnost color na Annotation (a jejích podtřídách) je tuple[float, ...] odpovídající počtu komponent položky PDF /C (prázdná, když není barva nastavena) — ne dedikovaný objekt barvy.

Viz také:

• Správa dokumentů (průvodce pro vývojáře)
• Jak načíst dokument v Python
• Instalační příručka
• API Reference
• Repozitář GitHub
• Aspose.PDF for Python — Enterprise Knowledge Base