PDF-anteckningar

PDF-annotationer

Page.annotations exponerar en AnnotationCollection — en muterbar, sekvensliknande vy över varje annotation på en sida. Varje post är en Annotation (eller MarkupAnnotation / LinkAnnotation underklasser), och subtyp-specifik data såsom quad points, ink lists eller colors läses och skrivs via get_property() / set_property() snarare än dedikerade attribut.

Lägga till annotationer

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) skapar en ny annotation och lägger till den på sidan. subtype accepterar antingen en vanlig sträng ("Text", "Square", "Highlight") eller en AnnotationType enum-medlem.

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

Läsa och uppdatera egenskaper

get_property(name, default) läser ett subtyp-specifikt värde; set_property(name, value) skriver ett, och att sätta en egenskap till None tar bort den från annotationens properties dict.

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

Namnge annotationer med AnnotationName

PDF-namn (t.ex. en Stamp annoterings Name post) markeras tydligt från vanliga strängar med AnnotationName, en str underklass till aspose_pdf.engine.cos. Ett värde som lagras på detta sätt jämförs fortfarande lika med en vanlig sträng.

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

Infoga, radera och rensa

insert(index, subtype, rect, contents, title, appearance_normal, properties) placerar en ny annotation på en specifik position; delete(index) tar bort en efter index (kastar IndexError för ett index utanför intervallet); clear() tar bort alla annotationer från sidan.

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

Generera annoteringsutseenden

Annotation.generate_appearance(force) bygger /AP /N utseendeströmmen för en annotation och returnerar True när en renderare för den underklassen finns; AnnotationCollection.generate_appearances(force) gör samma sak för varje annotation på sidan i ett enda anrop och returnerar antalet annotationer som faktiskt genererades (ej stödda underklasser hoppas över).

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

Annoteringsunderklasser och flaggor

AnnotationType uppräkner de standardiserade PDF 32000-1:2008 (Tabell 169) underklassenamnen: 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, och REDACT.

AnnotationFlags är en IntFlag som täcker annoteringsvisnings-/interaktionsbeteende: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED och TOGGLE_NO_VIEW.

Förhandsutgåva: 3D-anteckningar

PDF3DAnnotation, PDF3DArtwork, PDF3DContent och PDF3DView modellerar 3D-konstverk som är bifogat till en sida — en PDF3DAnnotation har en rect: Rectangle, en artwork: PDF3DArtwork och en valfri background_color: Color. PDF3DArtwork.add_view() registrerar en PDF3DView, var och en bär en render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) och en lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). Bibliotekets egen docstring markerar PDF3DAnnotation som en “minimal annotation wrapper for prerelease imports” — behandla denna yta som tidig fas snarare än ett fullt utvecklat 3D-författnings API.

Tips och bästa praxis

• Föredra AnnotationType enum-medlemmar framför råa subtypsträngar när värdet också måste jämföras eller användas i grenlogik någon annanstans i din kod.
• Anropa set_property(name, None) för att ta bort en egenskap helt och hållet istället för att lämna ett föråldrat värde på plats — posten försvinner helt från properties.
• Generera uppträdanden i batch med AnnotationCollection.generate_appearances istället för att loopa generate_appearance() per annotation; den returnerar det faktiska antalet som skapats så att du kan upptäcka överhoppade/ej stödda subtyper.
• delete() och indexering i page.annotations är båda 0-baserade; validera ett index innan du anropar delete() om det kommer från användarinmatning, eftersom ett index utanför intervallet kastar IndexError.
• Wrappa PDF-namnvärden (t.ex. en Stamps Name) i AnnotationName så att de återvänder som PDF-namn snarare än vanliga textsträngar.

Vanliga problem

FAQ

Hur lägger jag till en vanlig textkommentarannotation?

Anropa page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Det fyrsiffriga tupeln är annotationens rektangel på sidan.

Vad är skillnaden mellan Annotation, MarkupAnnotation och LinkAnnotation?

Annotation är den levande vyn som returneras för vilken annotation som helst på en sida. MarkupAnnotation är basen för markup-stil underklasser (markeringar, textanteckningar, former) och LinkAnnotation används för länkningsstil-annotationer; båda exponerar för närvarande samma metod-/egenskapsyta som Annotation.

Kan jag ta bort en enskild egenskap utan att radera hela annotationen?

Ja — anropa annotation.set_property(name, None); annotationen själv förblir orörd, endast den posten tas bort från properties.

Misslyckas AnnotationCollection.generate_appearances om en undertyp inte stöds?

Nej. Den hoppar över undertyper utan en inbyggd framträdanderenderare och returnerar antalet annotationer som den faktiskt genererade ett utseende för.

Är 3D-annotationsklasserna redo för produktion?

PDF3DAnnotation och relaterade typer är dokumenterade som ett minimalt omslag för förhandsutgåveimport — verifiera beteendet mot din mål-PDF-visare innan du förlitar dig på dem för produktions-3D-innehåll.

API Reference Sammanfattning

Se även

• Aspose.PDF for Python — Enterprise Documentation