Adnotacje PDF

Adnotacje PDF

Page.annotations udostępnia AnnotationCollection — mutowalny, przypominający sekwencję widok na wszystkie adnotacje na stronie. Każdy wpis jest Annotation (lub podklasami MarkupAnnotation / LinkAnnotation), a dane specyficzne dla podtypów, takie jak punkty kwadratu, listy atramentu lub kolory, są odczytywane i zapisywane za pośrednictwem get_property() / set_property() zamiast dedykowanych atrybutów.

Dodawanie adnotacji

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) tworzy nową adnotację i dodaje ją do strony. subtype przyjmuje albo zwykły ciąg znaków ("Text", "Square", "Highlight") albo członka wyliczenia 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]},
)

Odczytywanie i aktualizacja właściwości

get_property(name, default) odczytuje wartość specyficzną dla podtypu; set_property(name, value) zapisuje ją, a ustawienie właściwości na None usuwa ją ze słownika properties adnotacji.

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

Nazywanie adnotacji przy użyciu AnnotationName

Nazwy PDF (np. Stamp adnotacji Name wpis) są oznaczane wyraźnie od zwykłych łańcuchów przy użyciu AnnotationName, podklasy str z aspose_pdf.engine.cos. Wartość przechowywana w ten sposób jest nadal równa zwykłemu łańcuchowi.

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

Wstawianie, usuwanie i czyszczenie

insert(index, subtype, rect, contents, title, appearance_normal, properties) umieszcza nową adnotację w określonej pozycji; delete(index) usuwa jedną według indeksu (rzucając IndexError przy indeksie poza zakresem); clear() usuwa wszystkie adnotacje ze strony.

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

Generowanie wyglądu adnotacji

Annotation.generate_appearance(force) buduje /AP /N appearance stream dla jednej adnotacji i zwraca True, gdy istnieje renderer dla tego podtypu; AnnotationCollection.generate_appearances(force) robi to samo dla każdej adnotacji na stronie w jednym wywołaniu i zwraca liczbę adnotacji, które faktycznie zostały wygenerowane (nieobsługiwane podtypy są pomijane).

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 adnotacji i flagi

AnnotationType wymienia standardowe nazwy podtypów PDF 32000-1:2008 (Tabela 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 i REDACT.

AnnotationFlags jest IntFlag obejmującym zachowanie wyświetlania/interakcji adnotacji: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED i TOGGLE_NO_VIEW.

Wersja wstępna: 3D Annotations

PDF3DAnnotation, PDF3DArtwork, PDF3DContent i PDF3DView modelują trójwymiarową grafikę dołączoną do strony — PDF3DAnnotation ma rect: Rectangle, artwork: PDF3DArtwork oraz opcjonalny background_color: Color. PDF3DArtwork.add_view() rejestruje PDF3DView, z których każdy niesie render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) oraz lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). Docstring biblioteki oznacza PDF3DAnnotation jako „minimalny wrapper adnotacji dla importów wersji wstępnej” — traktuj tę powierzchnię jako wczesny etap, a nie w pełni opracowane API autorskie 3D.

Wskazówki i najlepsze praktyki

• Preferuj członków wyliczenia AnnotationType zamiast surowych ciągów podtypów, gdy wartość musi być również porównywana lub rozgałęziana w innym miejscu w kodzie.
• Wywołaj set_property(name, None), aby usunąć właściwość całkowicie, zamiast pozostawiać przestarzałą wartość — wpis znika z properties całkowicie.
• Generuj wygląd wsadowo przy użyciu AnnotationCollection.generate_appearances zamiast iterować generate_appearance() dla każdej adnotacji; zwraca rzeczywistą liczbę wygenerowaną, dzięki czemu możesz wykryć pominięte/nieobsługiwane podtypy.
• delete() oraz indeksowanie w page.annotations są oparte na zerze; zwaliduj indeks przed wywołaniem delete(), jeśli pochodzi z danych użytkownika, ponieważ indeks poza zakresem powoduje IndexError.
• Otocz wartości nazw PDF (np. Stamp’s Name) w AnnotationName, aby były przesyłane jako nazwy PDF, a nie zwykłe ciągi tekstowe.

Częste problemy

FAQ

Jak dodać adnotację komentarza w formie zwykłego tekstu?

Wywołaj page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Czteroelementowa krotka określa prostokąt adnotacji na stronie.

Jaka jest różnica między Annotation, MarkupAnnotation i LinkAnnotation?

Annotation jest widokiem na żywo zwracanym dla każdej adnotacji na stronie. MarkupAnnotation jest bazą dla podtypów w stylu znaczników (podświetlenia, notatki tekstowe, kształty), a LinkAnnotation jest przechowywany dla adnotacji w stylu linku; oba obecnie udostępniają tę samą powierzchnię metod/właściwości co Annotation.

Czy mogę usunąć pojedynczą właściwość bez usuwania całej adnotacji?

Tak — wywołaj annotation.set_property(name, None); sama adnotacja pozostaje niezmieniona, tylko ten jeden wpis zostaje usunięty z properties.

Czy AnnotationCollection.generate_appearances zawiedzie, jeśli podtyp nie jest obsługiwany?

Nie. Pomija podtypy bez wbudowanego renderera wyglądu i zwraca liczbę adnotacji, dla których faktycznie wygenerowano wygląd.

Czy klasy adnotacji 3D są gotowe do produkcji?

PDF3DAnnotation i powiązane typy są udokumentowane jako minimalny wrapper dla importów przedpremierowych — sprawdź zachowanie w docelowej przeglądarce PDF, zanim będziesz polegać na nich w produkcyjnych treściach 3D.

API Reference Podsumowanie

Zobacz także

• Aspose.PDF for Python — Enterprise Documentation