Como trabalhar com anotações PDF em Python

Aspose.PDF FOSS para Python expõe cada anotação em uma página como um objeto Annotation ao vivo através do AnnotationCollection da página, permitindo adicionar anotações de marcação, link e 3D, inspecionar suas propriedades específicas de tipo e gerar os fluxos de aparência que os visualizadores de PDF precisam para renderizá-las — tudo a partir de puro Python. Este guia mostra como instalar a biblioteca, adicionar anotações, lê-las de volta e gerar seus fluxos de aparência.

Guia passo a passo

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

Problemas comuns e correções

get_property returns None para uma propriedade que acabei de definir

As chaves properties são nomes de campo PDF exatos e sensíveis a maiúsculas/minúsculas ("Vertices", "Name" e similares) — um erro de digitação ou caso incorreto é ignorado silenciosamente em vez de gerar erro. Passe um argumento default para get_property(name, default) e verifique-o explicitamente ao depurar um novo subtipo.

generate_appearance() returns False

Nem toda combinação de subtipo e propriedade pode ser sintetizada em um fluxo de aparência pelo gerador interno. Verifique has_appearance antes de assumir que a chamada teve sucesso, e forneça um appearance_normal pré-renderizado (bytes) diretamente em add() para subtipos que o gerador não cobre.

Subclasse de anotação inesperada após add()

A string de subtipo (ou membro AnnotationType) que você fornece determina a classe retornada: subtipos de marcação retornam como MarkupAnnotation, "Link" retorna como LinkAnnotation, e qualquer outro subtipo reconhecido retorna como o Annotation base. Use isinstance() contra MarkupAnnotation/LinkAnnotation ao invés de assumir uma string de subtipo específica.

AnnotationFlags os valores não parecem mudar a renderização

AnnotationFlags (PRINT, HIDDEN, NO_ZOOM, READ_ONLY e similares) é um enum padrão Python IntFlag para compor e interpretar os bits de comportamento de uma anotação com o operador | — é um tipo de valor, não uma propriedade que Annotation.add() grava automaticamente. Combine as flags que você precisa e passe-as através do mesmo mecanismo properties específico de tipo usado para outros dados específicos de subtipo.

Trabalhando com uma página que ainda não tem anotações

page.annotations é sempre um AnnotationCollection válido (possivelmente vazio) — você nunca precisa verificar None antes de chamar add(), iterar ou chamar clear().

Perguntas Frequentes

Quais subtipos de anotação Aspose.PDF FOSS para Python suporta?

AnnotationType enumera todos os 25 subtipos padrão da PDF 32000-1:2008 Tabela 169, incluindo TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, HIGHLIGHT, STAMP, INK, FILE_ATTACHMENT, REDACT e mais.

Esta biblioteca suporta anotações 3D?

Sim. PDF3DAnnotation, juntamente com PDF3DArtwork, PDF3DContent, PDF3DView, PDF3DLightingScheme, e PDF3DRenderMode, modela uma superfície mínima de anotação PDF 3D (um retângulo, arte incorporada e visualizações nomeadas) para fluxos de trabalho PDF 3D em pré-lançamento. Veja o referência PDF3DAnnotation para seu conjunto completo de propriedades.

Como remover uma anotação de uma página?

Chame page.annotations.delete(index) para remover uma anotação por posição, ou page.annotations.clear() para remover todas as anotações da página.

Posso inserir uma anotação em uma posição específica em vez de adicioná-la ao final?

Sim — AnnotationCollection.insert(index, subtype, rect, contents, title, appearance_normal, properties) aceita os mesmos argumentos que add() mais o index de destino.

Como a cor de uma anotação é representada?

A propriedade color em Annotation (e suas subclasses) é um tuple[float, ...] que corresponde ao número de componentes da entrada /C do PDF (vazio quando a cor não está definida) — não um objeto de cor dedicado.

Ver também

• Gerenciamento de Documentos (Guia do Desenvolvedor)
• Como Carregar um Documento em Python
• Guia de Instalação
• API Reference
• Repositório GitHub
• Aspose.PDF for Python — Enterprise Knowledge Base