Анотації PDF

Анотації PDF

Page.annotations відкриває AnnotationCollection — змінюваний, схожий на послідовність вигляд всіх анотацій на сторінці. Кожен елемент є Annotation (або підкласами MarkupAnnotation / LinkAnnotation), а специфічні для підтипу дані, такі як квадратичні точки, списки чорнила або кольори, читаються і записуються через get_property() / set_property(), а не через окремі атрибути.

Додавання анотацій

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) створює нову анотацію і додає її до сторінки. subtype приймає або простий рядок ("Text", "Square", "Highlight") або член enum 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]},
)

Читання та оновлення властивостей

get_property(name, default) читає значення, специфічне для підтипу; set_property(name, value) записує його, і встановлення властивості в None видаляє її зі словника 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

Іменування анотацій за допомогою AnnotationName

PDF-імена (наприклад, Stamp анотації Name запис) позначаються окремо від звичайних рядків за допомогою AnnotationName, підкласу str від aspose_pdf.engine.cos. Значення, збережене таким чином, все одно порівнюється рівним звичайному рядку.

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

Вставка, Видалення та Очищення

insert(index, subtype, rect, contents, title, appearance_normal, properties) розташовує нову анотацію у вказаній позиції; delete(index) видаляє її за індексом (викидаючи IndexError при індексі поза діапазоном); clear() видаляє всі анотації зі сторінки.

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

Генерація зовнішнього вигляду анотацій

Annotation.generate_appearance(force) створює потік зовнішнього вигляду /AP /N для однієї анотації і повертає True, коли існує рендерер для цього підтипу; AnnotationCollection.generate_appearances(force) робить те ж саме для кожної анотації на сторінці в одному виклику і повертає кількість анотацій, які фактично були згенеровані (непідтримувані підтипи пропускаються).

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

Підтипи анотацій та прапорці

AnnotationType перераховує стандартні назви підтипів PDF 32000-1:2008 (Таблиця 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 та REDACT.

AnnotationFlags є IntFlag, що охоплює поведінку відображення/взаємодії анотації: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED та TOGGLE_NO_VIEW.

Попередній випуск: 3D анотації

PDF3DAnnotation, PDF3DArtwork, PDF3DContent та PDF3DView моделюють 3D-арт, прикріплений до сторінки — PDF3DAnnotation має rect: Rectangle, artwork: PDF3DArtwork та необов’язковий background_color: Color. PDF3DArtwork.add_view() реєструє PDF3DView, кожен з яких несе render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) і lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM). Докстрінг бібліотеки позначає PDF3DAnnotation як «minimal annotation wrapper for prerelease imports» — розглядайте цю поверхню як ранню стадію, а не як повністю розроблену 3D-авторську API.

Поради та кращі практики

• Надавайте перевагу членам enum AnnotationType замість необроблених рядків підтипу, коли значення також потрібно порівнювати або розгалужувати в іншому коді.
• Викличте set_property(name, None), щоб повністю видалити властивість, а не залишати застаріле значення — запис повністю зникає з properties.
• Генеруйте зовнішній вигляд пакетно за допомогою AnnotationCollection.generate_appearances замість циклічного виклику generate_appearance() для кожної анотації; він повертає фактичну кількість створених елементів, що дозволяє виявляти пропущені/непідтримувані підтипи.
• delete() та індексація в page.annotations обидва починаються з 0; перевіряйте індекс перед викликом delete(), якщо він отриманий від користувача, оскільки індекс поза діапазоном викликає IndexError.
• Обгорніть значення імен PDF (наприклад, Stamp’s Name) у AnnotationName, щоб вони передавалися як імена PDF, а не як прості текстові рядки.

Типові проблеми

FAQ

Як додати анотацію з простим текстовим коментарем?

Викличте page.annotations.add("Text", (x0, y0, x1, y1), "comment text"). Чотири-чисельний кортеж — це прямокутник анотації на сторінці.

У чому різниця між Annotation, MarkupAnnotation та LinkAnnotation?

Annotation — це живий вигляд, який повертається для будь-якої анотації на сторінці. MarkupAnnotation є базою для підтипів у вигляді розмітки (виділення, текстові нотатки, форми), а LinkAnnotation зберігається для анотацій типу посилання; обидва наразі надають той самий інтерфейс методів/властивостей, що й Annotation.

Чи можу я видалити окрему властивість, не видаляючи всю анотацію?

Так — викличте annotation.set_property(name, None); сама анотація залишається незмінною, лише цей запис видаляється з properties.

Чи AnnotationCollection.generate_appearances зазнає збою, якщо підтип не підтримується?

Ні. Він пропускає підтипи без вбудованого рендерера вигляду та повертає кількість анотацій, для яких фактично згенеровано вигляд.

Чи готові класи 3D-анотацій до виробничого використання?

PDF3DAnnotation та пов’язані типи документовані як мінімальна обгортка для попередніх релізів — перевірте їхню поведінку у вашому цільовому PDF-переглядачі, перш ніж покладатися на них у виробничому 3D-контенті.

API Reference Підсумок

Дивіться також

• Aspose.PDF for Python — Enterprise Documentation